Running Docker NGINX‑based image¶

The Wallarm NGINX-based filtering node can be deployed as a Docker container. The Docker container is fat and contains all subsystems of the filtering node.

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

apt list wallarm-node

Requirements¶

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

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

Options for running the container¶

The filtering node configuration parameters should be passed to the deployed Docker container in one of the following ways:

• In the environment variables. This option allows for the configuration of only basic filtering node parameters. Most directives cannot be configured through environment variables.

• In the mounted configuration file. This option allows full filtering node configuration via any directives. With this configuration method, environment variables with the filtering node and Wallarm Cloud connection settings are also passed to the container.

Run the container passing the environment variables¶

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

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' -p 80:80 wallarm/node:2.18.1-5

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' -p 80:80 wallarm/node:2.18.1-5

The command does the following:

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

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

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

  • node.yaml with filtering 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:

• Filtering node directives

• NGINX 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: us1.api.wallarm.com for the US Cloud api.wallarm.com for the EU Cloud By default: api.wallarm.com.	No
   DEPLOY_FORCE	Replaces an existing Wallarm node with a new one if an existing Wallarm node name matches the identifier of the container you are running. The following values can be assigned to a variable: true to replace the filtering node false to disable the replacement of the filtering node Default value (if the variable is not passed to the container) is false. The Wallarm node name always matches the identifier of the container you are running. Filtering 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 filtering node (for example, a container with a new version of the image). If in this case the variable value is false, the filtering node creation process will fail.	No

2. Mount the directory with the configuration file default to the /etc/nginx/sites-enabled container directory via the -v option.

   EU CloudUS Cloud

   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.18.1-5
   

   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.18.1-5
   

The command does the following:

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

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

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

  • node.yaml with filtering node UUID and secret key
  • license.key with Wallarm license key

• Protects the resource http://example.com.

Logging configuration¶

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

• /var/log/nginx — NGINX logs

• /var/log/wallarm — Wallarm node logs

To configure extended logging of the filtering 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 filtering node, there are Nagios‑compatible scripts inside the container. See details in Monitoring the filtering node.

Example of running the scripts:

docker exec -it <WALLARM_NODE_CONTAINER_ID> /usr/lib/nagios/plugins/check_wallarm_tarantool_timeframe -w 1800 -c 900

docker exec -it <WALLARM_NODE_CONTAINER_ID> /usr/lib/nagios/plugins/check_wallarm_export_delay -w 120 -c 300

• <WALLARM_NODE_CONTAINER_ID> is the ID of the running Wallarm Docker container. To get the ID, run docker ps and copy the proper ID.

Testing Wallarm 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>'
   

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

Configuring the use cases¶

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

• Configuration of the filtration mode

• Logging Wallarm node variables

• Adding Wallarm Scanner addresses to the allowlist in the block filtration mode

• Limiting the single request processing time in the directive wallarm_process_time_limit

• Limiting the server reply waiting time in the NGINX directive proxy_read_timeout

• Limiting the maximum request size in the NGINX directive client_max_body_size

• Double‑detection of attacks with libdetection