Skip to content

Running Docker NGINX‑based image

Image overview

The WAF node can be deployed as a Docker container. The Docker container is a fat one and contains all subsystems of the WAF node.

The functionality of the WAF node installed inside the Docker container is completely identical to the functionality of the other deployment options.

If the Wallarm WAF image is already deployed in your environment

If you deploy Wallarm WAF image instead of 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:

apt 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 Wallarm Console in the EU Cloud or US Cloud

  • Access to https://api.wallarm.com:444 for working with EU Wallarm Cloud or to https://us1.api.wallarm.com:444 for 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 to configure only basic WAF node parameters, the most directives cannot be changed through environment variables.

  • In the mounted configuration file. This option allows to configure all the WAF node directives.

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 Wallarm Console. Yes
DEPLOY_PASSWORD Password to the Deploy or Administrator user account in Wallarm Console. Yes
NGINX_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. By default: 0.2 gygabytes. No
WALLARM_ACL_ENABLE Enables the IP blocking functionality. By default: false. No

To run the image, use the command:

docker run -d -e DEPLOY_USER="deploy@example.com" -e DEPLOY_PASSWORD="very_secret" -e NGINX_BACKEND="example.com" -e TARANTOOL_MEMORY_GB=16 -p 80:80 wallarm/node:2.16
docker run -d -e DEPLOY_USER="deploy@example.com" -e DEPLOY_PASSWORD="very_secret" -e NGINX_BACKEND="example.com" -e WALLARM_API_HOST=us1.api.wallarm.com -e TARANTOOL_MEMORY_GB=16 -p 80:80 wallarm/node:2.16

The command does the following:

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

  • Creates the file default with minimal NGINX configuration and passed WAF node configuration in the /etc/nginx/sites-enabled container directory.

  • Creates files with WAF node credentials to access 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://NGINX_BACKEND:80.

Run the container mounting the configuration file

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

See an example of the mounted file with minimal settings
server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;
    #listen 443 ssl;

    server_name localhost;

    #ssl_certificate cert.pem;
    #ssl_certificate_key cert.key;

    root /usr/share/nginx/html;

    index index.html index.htm;

    wallarm_mode monitoring;
    # wallarm_instance 1;
    # wallarm_acl default;

    location / {
            proxy_pass http://example.com;
            include proxy_params;
    }
}

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 Wallarm Console. Yes
    DEPLOY_PASSWORD Password to the Deploy or Administrator user account in 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
  2. Mount the directory with the configuration file default to the /etc/nginx/sites-enabled container directory via the -v option.

    docker run -d -e DEPLOY_USER="deploy@example.com" -e DEPLOY_PASSWORD="very_secret" -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node: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/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:2.16
    

The command does the following:

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

  • Mounts the file default into the /etc/nginx/sites-enabled container directory.

  • Creates files with WAF node credentials to access 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://NGINX_BACKEND:80.

Mounting other configuration files

The container directories used by NGINX:

  • /etc/nginx/conf.d — common settings
  • /etc/nginx/sites-enabled — virtual host settings
  • /var/www/html — static files

If required, you can mount any files to the listed container directories. The WAF node directives should be described in the /etc/nginx/sites-enabled/default file.

Logging configuration

The logging is enabled by default. The log directories are:

  • /var/log/nginx — NGINX logs

  • /var/log/wallarm — Wallarm WAF logs

To configure extended logging of the WAF node variables, please use these instructions.

By default, the logs rotate once every 24 hours. To set up the log rotation, change the configuration files in /etc/logrotate.d/. Changing the rotation parameters through environment variables is not possible.

Monitoring configuration

To monitor the WAF node, there are Nagios‑compatible scripts inside the container. See details in Monitoring the WAF node.

Example of running the scripts:

docker exec -it wallarm-node /usr/lib/nagios-plugins/check_wallarm_tarantool_timeframe -w 1800 -c 900
docker exec -it wallarm-node /usr/lib/nagios-plugins/check_wallarm_export_delay -w 120 -c 300

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 Forbidden will be returned.

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

    Attacks in the interface

Configuring the use cases

The configuration file mounted to the Docker container should describe the WAF node configuration in the available directive. Below are some commonly used WAF node configuration optins: