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 →
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 orhttps://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 . | No |
WALLARM_MODE | WAF node mode:
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. By default: 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 |
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.16
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.16
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 keylicense.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:
-
WAF node settings as described in the instructions
-
Envoy settings as described in the Envoy instructions
To run the image:
-
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 Cloudus1.api.wallarm.com
for the US Cloud
api.wallarm.com
.No -
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.16
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.16
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 keylicense.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¶
-
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 code403 blocked by wallarm filter
will be returned. -
Open the Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.