Skip to content

Running Docker Envoy‑based image

Image overview

These instructions describe the steps to run the WAF Docker image based on Envoy 1.15.0. The image contains all systems required for correct WAF operation:

  • Envoy proxy services with embedded Wallarm WAF module

  • Tarantool modules for postanalytics

  • Other services and scripts

Wallarm WAF module is designed as an Envoy HTTP filter for requests proxying.

Supported configuration parameters

Please note that the most directives for the NGINX‑based WAF node configuration are not supported for the Envoy‑based WAF node configuration. See the list of parameters available for the Envoy‑based WAF node configuration →

If the Wallarm WAF image is already deployed in your environment

If you deploy the Wallarm WAF image instead of the already deployed image or need to duplicate the deployment, please keep the same WAF version as currently used or update the version of all images to the latest.

To check the installed version, run the following command in the container:

yum list wallarm-node

More information about WAF node versioning is available in the WAF node versioning policy.

Requirements

  • Access to the account with the Deploy or Administrator role and two‑factor authentication disabled in the Wallarm Console in the EU Cloud or US Cloud

  • Access to https://api.wallarm.com:444 if working with EU Wallarm Cloud or https://us1.api.wallarm.com:444 if working with US Wallarm Cloud. Please ensure the access is not blocked by a firewall

Options for running the container

The WAF node configuration parameters can be passed to the docker run command in the following ways:

  • In the environment variables. This option allows for configuration of only basic WAF node parameters, the most parameters cannot be changed through environment variables.

  • In the mounted configuration file. This option allows for configuration of all the WAF node parameters.

Run the container passing the environment variables

You can pass the following basic WAF node settings to the container via the option -e:

Environment variable Description Required
DEPLOY_USER Email to the Deploy or Administrator user account in the Wallarm Console. Yes
DEPLOY_PASSWORD Password to the Deploy or Administrator user account in the Wallarm Console. Yes
ENVOY_BACKEND Domain or IP address of the resource to protect with WAF. Yes
WALLARM_API_HOST Wallarm API server:
  • api.wallarm.com for the EU Cloud
  • us1.api.wallarm.com for the US Cloud
By default: api.wallarm.com.
No
WALLARM_MODE WAF node mode:
  • block to block malicious requests
  • monitoring to analyze but not block requests
  • off to disable traffic analyzing and processing
By default: monitoring.
No
TARANTOOL_MEMORY_GB Amount of memory allocated to Tarantool. The value can be an integer or a float (a dot . is a decimal separator). By default: 0.2 gygabytes. No
WALLARM_ACL_ENABLE Enables the IP blocking functionality with default settings. Any value can be assigned to a variable to enable the IP blocking functionality. Default value (if the variable is not passed to the container) is false.

To enable the IP blocking functionality with custom settings, you need to define appropriate parameters and run the container mounting the configuration file with defined directives.
No
DEPLOY_FORCE Replaces an existing WAF node with a new one if an existing WAF node name matches the identifier of the container you are running. The following values can be assigned to a variable:
  • true to replace the WAF node
  • false to disable the replacement of the WAF node
Default value (if the variable is not passed to the container) is false.
The WAF node name always matches the identifier of the container you are running. WAF node replacement is helpful if the Docker container identifiers in your environment are static and you are trying to run another Docker container with the WAF node (for example, a container with a new version of the image). If in this case the variable value is false, the WAF node creation process will fail.
No

To run the image, use the command:

docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -e ENVOY_BACKEND='example.com' -e TARANTOOL_MEMORY_GB=16 -p 80:80 wallarm/envoy:2.18.1-3
docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -e ENVOY_BACKEND='example.com' -e WALLARM_API_HOST='us1.api.wallarm.com' -e TARANTOOL_MEMORY_GB=16 -p 80:80 wallarm/envoy:2.18.1-3

The command does the following:

  • Automatically creates new WAF node in the Wallarm Cloud. Created WAF node will be displayed in the Wallarm Console → Nodes.

  • Creates the file envoy.yaml with minimal Envoy configuration in the /etc/envoy container directory.

  • Creates files with WAF node credentials to access the Wallarm Cloud in the /etc/wallarm container directory:

    • node.yaml with WAF node UUID and secret key
    • license.key with Wallarm license key
  • Protects the resource http://ENVOY_BACKEND:80.

Run the container mounting envoy.yaml

You can mount the prepared file envoy.yaml to the Docker container via the -v option. The file must contain the following settings:

To run the image:

  1. Pass required environment variables to the container via the -e option:

    Environment variable Description Required
    DEPLOY_USER Email to the Deploy or Administrator user account in the Wallarm Console. Yes
    DEPLOY_PASSWORD Password to the Deploy or Administrator user account in the Wallarm Console. Yes
    WALLARM_API_HOST Wallarm API server:
    • api.wallarm.com for the EU Cloud
    • us1.api.wallarm.com for the US Cloud
    By default: api.wallarm.com.
    No
    DEPLOY_FORCE Replaces an existing WAF node with a new one if an existing WAF node name matches the identifier of the container you are running. The following values can be assigned to a variable:
    • true to replace the WAF node
    • false to disable the replacement of the WAF node
    Default value (if the variable is not passed to the container) is false.
    The WAF node name always matches the identifier of the container you are running. WAF node replacement is helpful if the Docker container identifiers in your environment are static and you are trying to run another Docker container with the WAF node (for example, a container with a new version of the image). If in this case the variable value is false, the WAF node creation process will fail.
    No
  2. Mount the directory with the configuration file envoy.yaml to the /etc/envoy container directory via the -v option.

    docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -v /configs/envoy.yaml:/etc/envoy/envoy.yaml -p 80:80 wallarm/envoy:2.18.1-3
    
    docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -e WALLARM_API_HOST='us1.api.wallarm.com' -v /configs/envoy.yaml:/etc/envoy/envoy.yaml -p 80:80 wallarm/envoy:2.18.1-3
    

The command does the following:

  • Automatically creates new WAF node in the Wallarm Cloud. Created WAF node will be displayed in the Wallarm Console → Nodes.

  • Mounts the file envoy.yaml into the /etc/envoy container directory.

  • Creates files with WAF node credentials to access the Wallarm Cloud in the /etc/wallarm container directory:

    • node.yaml with WAF node UUID and secret key
    • license.key with Wallarm license key
  • Protects the resource http://ENVOY_BACKEND:80.

Configuration of log rotation (optional)

The log file rotation is preconfigured and enabled by default. You can adjust the rotation settings if necessary. These settings are located in the /etc/logrotate.d directory of the container.

Testing WAF node operation

  1. Send the request with test SQLI and XSS attacks to the protected resource address:

    curl http://localhost/?id='or+1=1--a-<script>prompt(1)</script>'
    

    If the WAF node works in the block mode, the request will be blocked and the code 403 blocked by wallarm filter will be returned.

  2. Open the Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.

    Attacks in the interface