Separate postanalytics module installation¶
The processing of requests in the Wallarm node is divided into two stages:
-
Primary processing in the NGINX-Wallarm module. The processing is not memory demanding and can be put on frontend servers without changing the server requirements.
-
Statistical analysis of the processed requests in the postanalytics module. Postanalytics is memory demanding, which may require changes in the server configuration or installation of postanalytics on a separate server.
Depending on the system architecture, the NGINX-Wallarm and postanalytics modules can be installed on the same server or on different servers.
These instructions provide the steps to install the postanalytics module on a separate server.
Requirements¶
-
NGINX-Wallarm module installed with NGINX stable from NGINX repository, NGINX from Debian/CentOS repositories or NGINX Plus
The NGINX-Wallarm package must be of the same or a lower version than the postanalytics module you install separately. Please check this requirement during the postanalytics package installation.
-
Access to the account with the Administrator role in Wallarm Console for the US Cloud or EU Cloud
-
SELinux disabled or configured upon the instructions
-
Executing all commands as a superuser (e.g.
root
) -
Access to
https://repo.wallarm.com
to download packages. Ensure the access is not blocked by a firewall -
Access to
https://us1.api.wallarm.com
if working with US Wallarm Cloud or tohttps://api.wallarm.com
if working with EU Wallarm Cloud. If access can be configured only via the proxy server, then use the instructions -
Access to GCP storage addresses to download an actual list of IP addresses registered in allowlisted, denylisted, or graylisted countries, regions or data centers
-
Installed text editor vim, nano, or any other. In the instruction, vim is used
Installation¶
1. Add Wallarm repositories¶
The postanalytics module, like the other Wallarm modules, is installed and updated from the Wallarm repositories. To add repositories, use the commands for your platform:
sudo apt -y install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node buster/4.4/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
sudo apt -y install dirmngr
curl -fSsL https://repo.wallarm.com/wallarm.gpg | sudo gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/wallarm.gpg --import
sudo chmod 644 /etc/apt/trusted.gpg.d/wallarm.gpg
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node bullseye/4.4/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node bionic/4.4/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node focal/4.4/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node jammy/4.4/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/4.4/x86_64/wallarm-node-repo-4.4-0.el7.noarch.rpm
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/4.4/x86_64/wallarm-node-repo-4.4-0.el7.noarch.rpm
sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/8/4.4/x86_64/wallarm-node-repo-4.4-0.el8.noarch.rpm
2. Install packages for the postanalytics module¶
Install the wallarm-node-tarantool
package from the Wallarm repository for the postanalytics module and Tarantool database:
sudo apt -y install --no-install-recommends wallarm-node-tarantool
sudo apt -y install --no-install-recommends wallarm-node-tarantool
sudo yum install -y wallarm-node-tarantool
sudo yum install -y wallarm-node-tarantool
The wallarm-node-tarantool
package version
The wallarm-node-tarantool
package must be of the same or a higher version than the primary NGINX-Wallarm module packages installed on a separate server.
To check versions:
# run from the server with primary NGINX-Wallarm module
apt list wallarm-node-nginx
# run from the server with the postanalytics module
apt list wallarm-node-tarantool
# run from the server with primary NGINX-Wallarm module
apt list wallarm-node-nginx
# run from the server with the postanalytics module
apt list wallarm-node-tarantool
# run from the server with primary NGINX-Wallarm module
yum list wallarm-node-nginx
# run from the server with the postanalytics module
yum list wallarm-node-tarantool
# run from the server with primary NGINX-Wallarm module
yum list wallarm-node-nginx
# run from the server with the postanalytics module
yum list wallarm-node-tarantool
3. Connect the postanalytics module to Wallarm Cloud¶
The postanalytics module interacts with the Wallarm Cloud. To connect the postanalytics module to the Cloud, it is required to create the Wallarm node for the postanalytics module. Created node will get the security rules from the Cloud and upload attacks data to the Cloud.
To create the filtering node and connect the postanalytics module to the Cloud:
-
Make sure that your Wallarm account has the Administrator role enabled in Wallarm Console.
You can check mentioned settings by navigating to the users list in the US Cloud or EU Cloud.
-
Open Wallarm Console → Nodes in the US Cloud or EU Cloud and create the node of the Wallarm node type.
-
Copy the generated token.
-
Run the
register-node
script in a system with the installed postanalytics module packages:sudo /usr/share/wallarm-common/register-node -t <NODE_TOKEN> -H us1.api.wallarm.com --no-sync --no-sync-acl
sudo /usr/share/wallarm-common/register-node -t <NODE_TOKEN> --no-sync --no-sync-acl
<NODE_TOKEN>
is the copied token value.- You may add
-n <HOST_NAME>
parameter to set a custom name for your postanalytics node instance. Final node instance name will be:HOST_NAME_NodeUUID
.
4. Update postanalytics module configuration¶
The configuration files of the postanalytics module are located in the paths:
-
/etc/default/wallarm-tarantool
for Debian and Ubuntu operating systems -
/etc/sysconfig/wallarm-tarantool
for CentOS and Amazon Linux 2.0.2021x and lower operating systems
To open the file in the editing mode, please use the command:
sudo vim /etc/default/wallarm-tarantool
sudo vim /etc/default/wallarm-tarantool
sudo vim /etc/sysconfig/wallarm-tarantool
sudo vim /etc/sysconfig/wallarm-tarantool
Memory¶
The postanalytics module uses the in-memory storage Tarantool. For production environments, the recommended amount of RAM allocated for Tarantool is 75% of the total server memory. If testing the Wallarm node or having a small server size, the lower amount can be enough (e.g. 25% of the total memory).
The allocated memory size is set in GB via the SLAB_ALLOC_ARENA
directive in the /etc/default/wallarm-tarantool
or /etc/sysconfig/wallarm-tarantool
configuration file. The value can be an integer or a float (a dot .
is a decimal separator). For example:
SLAB_ALLOC_ARENA=0.5
SLAB_ALLOC_ARENA=24
Detailed recommendations about allocating memory for Tarantool are described in these instructions.
Address of the separate postanalytics server¶
To set the address of the separate postanalytics server:
-
Open the Tarantool file in the editing mode:
sudo vim /etc/default/wallarm-tarantool
sudo vim /etc/default/wallarm-tarantool
sudo vim /etc/sysconfig/wallarm-tarantool
sudo vim /etc/sysconfig/wallarm-tarantool
-
Uncomment the
HOST
andPORT
variables and set them the following values:# address and port for bind HOST='0.0.0.0' PORT=3313
-
If the configuration file of Tarantool is set up to accept connections on the IP addresses different from
0.0.0.0
or127.0.0.1
, then please provide the addresses in/etc/wallarm/node.yaml
:hostname: <name of postanalytics node> uuid: <UUID of postanalytics node> secret: <secret key of postanalytics node> tarantool: host: '<IP address of Tarantool>' port: 3313
-
Add the address of the postanalytics module server to the configuration files on the server with the NGINX‑Wallarm package as described in the instructions for proper installation forms:
5. Restart Wallarm services¶
To apply the settings to the postanalytics and the NGINX‑Wallarm modules:
-
Restart the
wallarm-tarantool
service on the server with separate postanalytics module:sudo systemctl restart wallarm-tarantool
sudo systemctl restart wallarm-tarantool
sudo systemctl restart wallarm-tarantool
sudo systemctl restart wallarm-tarantool
-
Restart the NGINX service on the server with the NGINX‑Wallarm module:
sudo systemctl restart nginx
sudo service nginx restart
sudo systemctl restart nginx
sudo systemctl restart nginx
6. Check the NGINX‑Wallarm and separate postanalytics modules interaction¶
To check the NGINX‑Wallarm and separate postanalytics modules interaction, you can send the request with test attack to the address of the protected application:
curl http://localhost/etc/passwd
If the NGINX‑Wallarm and separate postanalytics modules are configured properly, the attack will be uploaded to the Wallarm Cloud and displayed in the Events section of Wallarm Console:
If the attack was not uploaded to the Cloud, please check that there are no errors in the services operation:
-
Make sure that the postanalytics service
wallarm-tarantool
is in the statusactive
sudo systemctl status wallarm-tarantool
-
Analyze the postanalytics module logs
sudo cat /var/log/wallarm/tarantool.log
If there is the record like
SystemError binary: failed to bind: Cannot assign requested address
, make sure that the server accepts connection on specified address and port. -
On the server with the NGINX‑Wallarm module, analyze the NGINX logs:
sudo cat /var/log/nginx/error.log
If there is the record like
[error] wallarm: <address> connect() failed
, make sure that the address of separate postanalytics module is specified correctly in the NGINX‑Wallarm module configuration files and separate postanalytics server accepts connection on specified address and port. -
On the server with the NGINX‑Wallarm module, get the statistics on processed requests using the command below and make sure that the value of
tnt_errors
is 0curl http://127.0.0.8/wallarm-status
Description of all parameters returned by the statistics service →
Postanalytics module protection¶
Protect installed postanalytics module
We highly recommend to protect a newly installed Wallarm postanalytics module with a firewall. Otherwise, there is a risk of getting unauthorized access to the service that may result in:
- Disclosure of information about processed requests
- Possibility of executing arbitrary Lua code and operating system commands
Please note that no such risk exists if you are deploying the postanalytics module alongside with the NGINX-Wallarm module on the same server. This holds true because the postanalytics module will listen to the port 3313
.
Here are the firewall settings that should be applied to the separately installed postanalytics module:
- Allow the HTTPS traffic to and from the Wallarm API servers, so the postanalytics module can interact with these servers:
us1.api.wallarm.com
is the API server in the US Wallarm Cloudapi.wallarm.com
is the API server in the EU Wallarm Cloud
- Restrict the access to the
3313
Tarantool port via TCP and UDP protocols by allowing connections only from the IP addresses of the Wallarm filtering nodes.