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.
NGINX version in the Docker container
The Docker container uses NGINX of the version 1.14.x
. You may discover some vulnerabilities in this NGINX version but actually most of them are patched by the Debian team. The Docker container runs services on Debian 10.x, so discovered vulnerabilities should not result in data compromise.
Use cases¶
Among all supported Wallarm deployment options, NGINX-based Docker image is recommended for Wallarm deployment in these use cases:
-
If your organization utilizes Docker-based infrastructure, Wallarm Docker image is the ideal choice. It integrates effortlessly into your existing setup, whether you are employing a microservice architecture running on AWS ECS, Alibaba ECS, or other similar services. This solution also applies to those using virtual machines seeking a more streamlined management through Docker containers.
-
If you require fine-grained control over each container, the Docker image excels. It affords a greater level of resource isolation than typically possible with traditional VM-based deployments.
For more information on running Wallarm's NGINX-based Docker image on popular public cloud container orchestration services, refer to our guides: AWS ECS, GCP GCE, Azure Container Instances, Alibaba ECS.
Requirements¶
-
Docker installed on your host system
-
Access to
https://hub.docker.com/r/wallarm/node
to download the Docker image. Please ensure the access is not blocked by a firewall -
Access to the account with the Administrator role in Wallarm Console in the US Cloud or EU Cloud
-
Access to
https://us1.api.wallarm.com
if working with US Wallarm Cloud or tohttps://api.wallarm.com
if working with EU Wallarm Cloud. Please ensure the access is not blocked by a firewall -
Access to the IP addresses of Google Cloud Storage listed within the link. When you allowlist, denylist, or graylist entire countries, regions, or data centers instead of individual IP addresses, the Wallarm node retrieves precise IP addresses related to the entries in the IP lists from the aggregated database hosted on Google Storage.
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¶
To run the container:
-
Get Wallarm token of the appropriate type:
-
Run the container with the node:
docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e NGINX_BACKEND='example.com' -e WALLARM_API_HOST='us1.api.wallarm.com' -p 80:80 wallarm/node:4.6.2-1
docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e NGINX_BACKEND='example.com' -p 80:80 wallarm/node:4.6.2-1
You can pass the following basic filtering node settings to the container via the option -e
:
Environment variable | Description | Required |
---|---|---|
WALLARM_API_TOKEN | Wallarm node or API token. | Yes |
NGINX_BACKEND | Domain or IP address of the resource to protect with the Wallarm solution. | Yes |
WALLARM_API_HOST | Wallarm API server:
api.wallarm.com . | No |
WALLARM_MODE | Node mode:
monitoring .Detailed description of filtration modes → | No |
WALLARM_APPLICATION | Unique identifier of the protected application to be used in the Wallarm Cloud. The value can be a positive integer except for 0 .Default value (if the variable is not passed to the container) is -1 which indicates the default application displayed in Wallarm Console → Settings → Application.More details on setting up applications → | 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 |
NGINX_PORT | Sets a port that NGINX will use inside the Docker container. Starting from the Docker image 4.0.2-1 , the wallarm-status service automatically runs on the same port as NGINX.Default value (if the variable is not passed to the container) is 80 .Syntax is NGINX_PORT='443' . | No |
DISABLE_IPV6 | The variable with any value except for an empty one deletes the listen [::]:80 default_server ipv6only=on; line from the NGINX configuration file which will stop NGINX from IPv6 connection processing.If the variable is not specified explicitly or has an empty value "" , NGINX processes both IPv6 and IPv4 connections. | No |
WALLARM_LABELS | Available starting from node 4.6. Works only if
...will place node instance into the | Yes (for API tokens) |
The command does the following:
-
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 keyprivate.key
with Wallarm private 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:
To run the container:
-
Get Wallarm token of the appropriate type:
-
Run the container with the node:
docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_API_HOST='us1.api.wallarm.com' -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:4.6.2-1
docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:4.6.2-1
-
The
-e
option passes the following required environment variables to the container:Environment variable Description Required WALLARM_API_TOKEN
Wallarm node or API token. Yes WALLARM_API_HOST
Wallarm API server: us1.api.wallarm.com
for the US Cloudapi.wallarm.com
for the EU Cloud
api.wallarm.com
.No WALLARM_LABELS
Available starting from node 4.6. Works only if
WALLARM_API_TOKEN
is set to API token with theDeploy
role. Sets thegroup
label for node instance grouping, for example:WALLARM_LABELS="group=<GROUP>"
...will place node instance into the
<GROUP>
instance group (existing, or, if does not exist, it will be created).Yes (for API tokens) -
The
-v
option mounts the directory with the configuration filedefault
to the/etc/nginx/sites-enabled
container directory.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_application 1; location / { proxy_pass http://example.com; include proxy_params; } }
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 filtering node directives should be described in the
/etc/nginx/sites-enabled/default
file.
-
The command does the following:
-
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 keyprivate.key
with Wallarm private 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, rundocker ps
and copy the proper ID.
Testing Wallarm node operation¶
-
Send the request with test Path Traversal attack to a protected resource address:
curl http://localhost/etc/passwd
-
Open Wallarm Console → Events section in the US Cloud or EU Cloud and make sure the attack is 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: