Filtering node and Wallarm Cloud synchronization configuration¶
The filtering node regularly synchronizes with the Wallarm Cloud to:
-
Get updates for traffic processing rules (LOM)
-
Get updates of proton.db
-
Send data on detected attacks and vulnerabilities
-
Send metrics for processed traffic
These instructions describe parameters and methods used to configure filtering node and Wallarm Cloud synchronization.
The set of parameters and the method of its configuration depend on the deployed Wallarm node type:
-
Cloud filtering node created by the
addcloudnode
script -
Regular filtering node created by the
addnode
script
Cloud node and Wallarm Cloud synchronization¶
The /etc/wallarm/syncnode
file contains environment variables that define the way the cloud filtering node will synchronize with the Wallarm Cloud. The /etc/wallarm/syncnode
file containing the variable WALLARM_API_TOKEN
with the cloud node token is created after running the addcloudnode
script.
The wallarm-synccloud
service applies the changes made to the /etc/wallarm/syncnode
file to the synchronization process and runs the synchronization with the new configuration.
Available environment variables¶
The list of environment variables available for the cloud node and Wallarm Cloud synchronization configuration is provided below. To get the list of available environment variables, you can also run the following command:
/usr/share/wallarm-common/synccloud --help
Variable | Description |
---|---|
WALLARM_API_HOST | Wallarm API endpoint. Can be:
api.wallarm.com .This variable is required to be set in the file /etc/wallarm/syncnode . |
WALLARM_API_PORT | Wallarm API port. Default value is 443 . |
WALLARM_API_TOKEN | Cloud node token to access the Wallarm API. |
WALLARM_API_CA_VERIFY | Whether to enable/disable Wallarm API server certificate verification. Can be:
yes . |
WALLARM_API_CA_PATH | Path to the Wallarm API certificate authority file. |
WALLARM_SYNCNODE | Whether to enable/disable Wallarm node‑specific data synchronization. If the synchronization is enabled, the files for the cloud node operation (such as LOM file) will be periodically downloaded from the Cloud. If the synchronization is disabled, the files for the cloud node operation will not be downloaded. Can be:
yes . |
WALLARM_SYNCNODE_INTERVAL | Interval between filtering node and Wallarm Cloud synchronizations in seconds. The value cannot be less than the default value. Default value is 120 . |
WALLARM_SYNCNODE_RAND_DELAY | Synchronization delay jitter in seconds. Default value is 120 . |
WALLARM_SYNCNODE_TIMEOUT | Synchronization duration limit. This limit allows interrupting the synchronization if any issues occur during the process of downloading the files for the cloud node operation. For example, such issues can be caused by network outages. Default value is 900 . |
WALLARM_SYNCNODE_OWNER WALLARM_SYNCNODE_GROUP WALLARM_SYNCNODE_MODE | See Access rights to files needed for node operation. |
Configuring synchronization parameters¶
To change synchronization parameters, proceed with the following steps:
-
Make changes to the
/etc/wallarm/syncnode
file by adding the required environment variables and assigning the desired values to them.The valid
/etc/wallarm/syncnode
contents:WALLARM_API_TOKEN=K85iHWi0SXRxJTb+xxxxxxxxxxxxxxxxxxxxfiwo9twr9I5/+sjZ9v2UlRRgwwMD WALLARM_SYNCNODE_INTERVAL=800 WALLARM_SYNCNODE_TIMEOUT=600
-
Restart the
wallarm-synccloud
service to apply updated settings to the synchronization process:sudo /bin/systemctl restart wallarm-synccloud
The service will apply the values assigned to the environment variables in the
/etc/wallarm/syncnode
file as new parameters for the cloud node and Wallarm Cloud synchronization. After the command execution, the filtering node will be performing the synchronization procedure according to the new parameters.
Regular node and Wallarm Cloud synchronization¶
Configuration of the regular filtering node and Wallarm Cloud synchronization is set in the following way:
-
Credentials to access the Wallarm Cloud are set in the
node.yaml
file. Thenode.yaml
file containing the regular filtering node name and UUID, and secret key to access Wallarm API is created after running theaddnode
script.Default path to the file is
/etc/wallarm/node.yaml
. This path can be changed via thewallarm_api_conf
directive. -
Interval between filtering node and Wallarm Cloud synchronizations is set via the system environment variable
WALLARM_SYNCNODE_INTERVAL
. Variable value should be set in the/etc/environment
file. Default variable value is120
seconds.
Credentials to access the Wallarm Cloud¶
The node.yaml
file may contain the following parameters for accessing the regular filtering node to the Wallarm Cloud:
Parameter | Description |
---|---|
hostname | Regular node name. This variable is required to be set in the file node.yaml . |
uuid | Regular node UUID. This variable is required to be set in the file node.yaml . |
secret | Secret key to access the Wallarm API. This variable is required to be set in the file node.yaml . |
api.host | Wallarm API endpoint. Can be:
api.wallarm.com . |
api.port | Wallarm API port. Default value is 443 . |
api.ca_verify | Whether to enable/disable Wallarm API server certificate verification. Can be:
true . |
api.local_host | Local IP address of the network interface through which requests to Wallarm API are sent. This parameter is required if the network interface used by default restricts access to Wallarm API (for example, access to the Internet may be closed). |
api.local_port | Port of the network interface through which requests to Wallarm API are sent. This parameter is required if the network interface used by default restricts access to Wallarm API (for example, access to the Internet may be closed). |
syncnode.owner syncnode.group syncnode.mode | See Access rights to files needed for node operation. |
To change synchronization parameters, proceed with the following steps:
-
Make changes to the
node.yaml
file by adding the required parameters and assigning the desired values to them.The valid
node.yaml
contents:hostname: example-node-name uuid: ea1xa0xe-xxxx-42a0-xxxx-b1b446xxxxxx secret: b827axxxxxxxxxxxcbe45c855c71389a2a5564920xxxxxxxxxxxxxxxxxxc4613260 api: host: api.wallarm.com port: 443 ca_verify: true syncnode: owner: root group: wallarm mode: 0640
-
Restart NGINX to apply updated settings to the synchronization process:
sudo systemctl restart nginx
sudo service nginx restart
sudo systemctl restart nginx
sudo systemctl restart nginx
Interval between filtering node and Wallarm Cloud synchronizations¶
By default, the filtering node synchronizes with the Wallarm Cloud every 120‑240 seconds (2‑4 minutes). You can change the synchronization interval via the system environment variable WALLARM_SYNCNODE_INTERVAL
.
To change the interval between regular filtering node and Wallarm Cloud synchronizations:
-
Open the file
/etc/environment
. -
Add the
WALLARM_SYNCNODE_INTERVAL
variable to the file and set a desired value to the variable in seconds. The value cannot be less than the default value (120
seconds). For example:WALLARM_SYNCNODE_INTERVAL=800
-
Save the changed file
/etc/environment
. New interval value will be applied to the synchronization process automatically.
Access rights to files needed for node operation¶
The wallarm-worker
and nginx
services are usually automatically provided with the permission to read the content of the files needed for the filtering node operation, such as proton.db and custom ruleset file. However, if testing shows no access, read the description below of how the permissions are provided and how they can be configured manually.
The file access parameters are:
Parameter | Description | Environment variable in /etc/wallarm/syncnode file (cloud node) | Parameter in node.yaml file (regular node) |
---|---|---|---|
owner | Owner for the files needed for the filtering node operation. | WALLARM_SYNCNODE_OWNER | syncnode.owner |
group | Group for the files needed for the filtering node operation. | WALLARM_SYNCNODE_GROUP | syncnode.group |
mode | Access rights to the files needed for the filtering node operation. | WALLARM_SYNCNODE_MODE | syncnode.mode |
The algorithm searches for the file permissions performing the following steps (goes to the next step only if the previous one did not give the result):
-
Explicitly configured variables/parameters:
- The
WALLARM_SYNCNODE_(OWNER,GROUP,MODE)
environment variables in the/etc/wallarm/syncnode
file.
-
The
syncnode.(TYPE).(user,group,mode)
parameters in thenode.yaml
file.(TYPE)
allows you to specify the particular file the parameter is set for. Possible values areproton.db
orlom
.lom
value meaningPay your attention that the
lom
value points to the custom ruleset file/etc/wallarm/custom_ruleset
. -
The
syncnode.(user,group,mode)
parameters in thenode.yaml
file.
- The
-
For NGINX-based installation, value of the
nginx_group
in the/usr/share/wallarm-common/engine/*
file.All installed engine packages provide the file
/usr/share/wallarm-common/engine/*
containingnginx_group=<VALUE>
.Each package with the module sets the value for the
group
parameter depending on the NGINX for which it was intended:- The modules for NGINX from nginx.org set
group
tonginx
. - The modules for NGINX distributives set
group
towww-data
. - The custom modules use values provided by a client.
- The modules for NGINX from nginx.org set
-
Defaults:
owner
:root
group
:wallarm
mode
:0640
Note that you only need to configure access rights explicitly if the result achieved by the algorithm automatically does not suit your needs. After configuring access rights, make sure that the wallarm-worker
and nginx
services can read the content of the files needed for the filtering node operation.