Skip to content

Installing dynamic WAF module for NGINX from Debian/CentOS repositories

These instructions describe the steps to install Wallarm WAF as a dynamic module for the open source version of NGINX installed from the Debian/CentOS repositories.

If Wallarm WAF is already installed in your environment

If you install Wallarm WAF instead of already existing Wallarm WAF or need to duplicate the installation in the same environment, please keep the same WAF version as currently used or update the version of all installations to the latest. For the postanalytics installed separately, versions of substite or duplicate installations must be the same as already installed postanalytics too.

To check the installed version if WAF node and postanalytics are installed on the same server:

apt list wallarm-node
apt list wallarm-node
yum list wallarm-node

To check the versions of WAF node and postanalytics installed on different servers:

# run from the server with installed WAF node
apt list wallarm-node-nginx
# run from the server with installed postanalytics
apt list wallarm-node-tarantool
# run from the server with installed WAF node
apt list wallarm-node-nginx
# run from the server with installed postanalytics
apt list wallarm-node-tarantool
# run from the server with installed WAF node
yum list wallarm-node-nginx
# run from the server with installed postanalytics
yum list wallarm-node-tarantool

More information about version support is available in the WAF node versioning policy.

Requirements

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

  • SELinux disabled or configured upon the instruction

  • Executing all commands as a superuser (e.g. root)

  • For the request processing and postanalytics on different servers: postanalytics installed on the separate server upon the instruction

  • Access to https://repo.wallarm.com to download packages. Ensure the access is not blocked by a firewall

  • 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. If access can be configured only via the proxy server, use the instruction

  • Installed text editor vim, nano or any other. In the instruction, vim is used

Installation options

The processing of requests in the WAF 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. Installation commands for both options are described in the further instructions.

Installation

1. Add Debian/CentOS repositories

sudo apt install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
echo 'Acquire::Check-Valid-Until "false";' | sudo tee /etc/apt/apt.conf.d/ignore-release-date
echo 'deb http://archive.debian.org/debian jessie-backports/ main' | sudo tee /etc/apt/sources.list.d/jessie-backports.list
echo 'deb http://repo.wallarm.com/debian/wallarm-node jessie/2.14/' | sudo tee /etc/apt/sources.list.d/wallarm.list
echo 'deb http://repo.wallarm.com/debian/wallarm-node jessie-backports/2.14/' | sudo tee --append /etc/apt/sources.list.d/wallarm.list
sudo apt update
sudo apt 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 stretch/2.14/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
sudo apt 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 stretch/2.14/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node stretch-backports/2.14/' | sudo tee --append /etc/apt/sources.list.d/wallarm.list"
# for correct WAF operation, uncomment the following line in /etc/apt/sources.list`:
# deb http://deb.debian.org/debian stretch-backports main contrib non-free
sudo apt update
sudo apt 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/2.14/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update
sudo yum install --enablerepo=extras -y epel-release centos-release-SCL
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/6/2.14/x86_64/Packages/wallarm-node-repo-1-5.el6.noarch.rpm
sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm

2. Install NGINX with Wallarm WAF packages

Request processing and postanalytics on the same server

The command installs the following packages:

  • nginx for NGINX

  • libnginx-mod-http-wallarm or nginx-mod-http-wallarm for the NGINX-Wallarm module

  • wallarm-node for the postanalytics module, Tarantool database, and additional NGINX-Wallarm packages

sudo apt install --no-install-recommends nginx wallarm-node libnginx-mod-http-wallarm -t jessie-backports
sudo apt install --no-install-recommends nginx wallarm-node libnginx-mod-http-wallarm
sudo apt install --no-install-recommends nginx wallarm-node libnginx-mod-http-wallarm -t stretch-backports
sudo apt install --no-install-recommends nginx wallarm-node libnginx-mod-http-wallarm
sudo yum install nginx wallarm-node nginx-mod-http-wallarm
sudo yum install nginx wallarm-node nginx-mod-http-wallarm

Request processing and postanalytics on different servers

To run postanalytics and process the requests on different servers, the following packages are required:

  • wallarm-node-tarantool on the separate server for the postanalytics module and Tarantool database (installation steps are described in the instructions)

  • wallarm-node-nginx and libnginx-mod-http-wallarm/nginx-mod-http-wallarm for the NGINX-Wallarm module

The commands install packages for NGINX and for the NGINX-Wallarm module:

sudo apt install --no-install-recommends nginx wallarm-node-nginx libnginx-mod-http-wallarm -t jessie-backports
sudo apt install --no-install-recommends nginx wallarm-node-nginx libnginx-mod-http-wallarm
sudo apt install --no-install-recommends nginx wallarm-node-nginx libnginx-mod-http-wallarm -t stretch-backports
sudo apt install --no-install-recommends nginx wallarm-node-nginx libnginx-mod-http-wallarm
sudo yum install nginx wallarm-node-nginx nginx-mod-http-wallarm
sudo yum install nginx wallarm-node-nginx nginx-mod-http-wallarm

3. Connect the Wallarm WAF module

Copy the configuration files for the system setup:

sudo cp /usr/share/doc/libnginx-mod-http-wallarm/examples/*conf /etc/nginx/conf.d/
sudo cp /usr/share/doc/nginx-mod-http-wallarm/examples/*conf /etc/nginx/conf.d/

4. Connect the WAF node to Wallarm Cloud

The WAF node interacts with the Wallarm Cloud. To connect the WAF node to the Cloud, proceed with the following steps:

  1. Make sure that your Wallarm account has the Administrator role enabled and two-factor authentication disabled in Wallarm Console.

    You can check mentioned settings by navigating to the users list in the EU Cloud or US Cloud.

    User list in Wallarm console

  2. Run the addnode script in a system with the installed WAF node:

    sudo /usr/share/wallarm-common/addnode
    
    sudo /usr/share/wallarm-common/addnode -H us1.api.wallarm.com
    
  3. Input an email and password of you account in Wallarm Console.

  4. Input the WAF node name or click Enter to use automatically generated name.

  5. Open Wallarm Console → Node section in the EU Cloud or US Cloud and ensure a new WAF node is added to the list.

5. Update Wallarm WAF configuration

Main configuration files of NGINX and Wallarm WAF node are located in the directories:

  • /etc/nginx/conf.d/default.conf with NGINX settings

  • /etc/nginx/conf.d/wallarm.conf with global WAF node settings

    The file is used for settings applied to all domains. To apply different settings to different domain groups, use the file default.conf or create new configuration files for each domain group (for example, example.com.conf and test.com.conf). More detailed information about NGINX configuration files is available in the official NGINX documentation.

  • /etc/nginx/conf.d/wallarm‑status.conf with WAF node monitoring settings. Detailed description is available by the link

  • /etc/default/wallarm-tarantool or /etc/sysconfig/wallarm-tarantool with the Tarantool database settings

Request filtering mode

By default, WAF node is in the status off and does not filter requests. Change the filtering mode on the NGINX settings level to block requests with attacks:

  1. Open the file /etc/nginx/conf.d/default.conf:

    sudo vim /etc/nginx/conf.d/default.conf
    
  2. Add the line wallarm_mode block; to the server block:

Example of /etc/nginx/conf.d/default.conf
server {
    # port for which requests are filtered
    listen       80;
    # domain for which requests are filtered
    server_name  localhost;
    # WAF node mode
    wallarm_mode block;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

Memory

Postanalytics on the separate server

If you installed postanalytics on a separate server, skip this step as you already have your postanalytics configured.

The WAF node uses the in-memory storage Tarantool. The recommended memory size for Tarantool is 75% of the total server memory. To allocate memory for Tarantool:

  1. Open the Tarantool configuration file in the editing mode:

    sudo vim /etc/default/wallarm-tarantool
    
    sudo vim /etc/sysconfig/wallarm-tarantool
    
  2. Specify memory size in GB in the SLAB_ALLOC_ARENA directive. For example, 24 GB:

    SLAB_ALLOC_ARENA=24
    

    Detailed recommendations about allocating memory for Tarantool are described in the instruction.

  3. To apply changes, restart Tarantool:

    sudo systemctl restart wallarm-tarantool
    
    sudo service wallarm-tarantool restart
    
    sudo systemctl restart wallarm-tarantool
    

Address of the separate postanalytics server

NGINX-Wallarm and postanalytics on the same server

If the NGINX-Wallarm and postanalytics modules are installed on the same server, skip this step.

Add postanalytics server addresses to the file /etc/nginx/conf.d/wallarm.conf:

upstream wallarm_tarantool {
    server <ip1>:3313 max_fails=0 fail_timeout=0 max_conns=1;
    server <ip2>:3313 max_fails=0 fail_timeout=0 max_conns=1;

    keepalive 2;
    }

    # omitted

wallarm_tarantool_upstream wallarm_tarantool;
  • max_conns value must be specified for each of the upstream Tarantool servers to prevent the creation of excessive connections.

  • keepalive value must not be lower than the number of the Tarantool servers.

Other configurations

To update other NGINX and Wallarm WAF configurations, use the NGINX documentation and the list of available Wallarm WAF directives.

6. Restart NGINX

Providing user with root permission

If you are running NGINX as a user that does not have root permission, add this user to the wallarm group using the following command:

usermod -aG wallarm <user_name>;

where <user_name> is the name of the user without root permission.

sudo systemctl restart nginx
sudo service nginx restart
sudo systemctl restart nginx

7. Test Wallarm WAF operation

  1. Get the WAF node statistics:

    curl http://127.0.0.8/wallarm-status
    

    The request will return statistics about analyzed requests. Response format is provided below, more detailed description of parameters is available by the link.

    { "requests":0,"attacks":0,"blocked":0,"abnormal":0,"tnt_errors":0,"api_errors":0,
    "requests_lost":0,"segfaults":0,"memfaults":0,"softmemfaults":0,"time_detect":0,"db_id":46,
    "lom_id":16767,"proton_instances": { "total":1,"success":1,"fallback":0,"failed":0 },
    "stalled_workers_count":0,"stalled_workers":[] }
    

  2. Send the request with test SQLI and XSS attacks to the application address:

    curl http://localhost/?id='or+1=1--a-<script>prompt(1)</script>'
    

    WAF node will block the request and the code 403 Forbidden will be returned in the response to the request.

  3. Send the request to wallarm-status and ensure the values of parameters requests and attacks increased:

    curl http://127.0.0.8/wallarm-status
    
  4. Open Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.

    Attacks in the interface

Settings customization

Dynamic Wallarm WAF module with default settings is installed for NGINX from the Debian/CentOS repositories. To customize Wallarm WAF settings, use the available directives.

Common customization options: