Installing with NGINX Plus

Installation Options

The processing of requests in the filter node is done in two stages:

  • Processing in NGINX-Wallarm.
  • Postanalytics – statistical analysis of the processed requests.

The processing is not memory demanding and can be put on front end servers without changing the server requirements.

Postanalytics is memory demanding, which may require changes in the server configuration or installation of postanalytics on a separate server.

Wallarm also has the option of installing postanalytics in a separate server pool.

Installation of postanalytics on a separate server

If you are planning to install postanalytics on a separate server, you must install postanalytics first. See details in Separate postanalytics installation.

To install the filter node with NGINX Plus, you must:

  1. Install NGINX Plus.
  2. Add the Wallarm repositories, from which you will download packages.
  3. Install the Wallarm packages.
  4. Configure postanalytics.
  5. Connect the Wallarm module.
  6. Set up the filter node for using a proxy server.
  7. Connect the filter node to the Wallarm cloud.
  8. Configure the server addresses of postanalytics.
  9. Configure the filtration mode.
  10. Restart NGINX Plus.

1. Install NGINX Plus

See the official NGINX installation instructions.

2. Add the Wallarm Repositories

The installation and updating of NGINX Plus with the Wallarm module is done from the Wallarm repositories.

Depending on your operating system, run one of the commands:

Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
Ubuntu 18.04 LTS (bionic)
CentOS 6.x
CentOS 7.x
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
echo 'deb http://repo.wallarm.com/debian/wallarm-node jessie/' >/etc/apt/sources.list.d/wallarm.list
apt-get update
apt-get install dirmngr
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sudo sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node stretch/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node trusty/' >/etc/apt/sources.list.d/wallarm.list
apt-get update
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node xenial/' >/etc/apt/sources.list.d/wallarm.list
apt-get update
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sudo sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node bionic/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
yum install --enablerepo=extras -y epel-release centos-release-SCL
rpm -i https://repo.wallarm.com/centos/wallarm-node/6/x86_64/Packages/wallarm-node-repo-1-2.el6.noarch.rpm
yum install -y epel-release
rpm -i https://repo.wallarm.com/centos/wallarm-node/7/x86_64/Packages/wallarm-node-repo-1-2.el7.centos.noarch.rpm

Repository access

Your system must have access to https://repo.wallarm.com to download the packages. Ensure the access is not blocked by a firewall.

3. Install the Wallarm Packages

To run postanalytics and process the requests on the same server, you must install the following packages:

  • NGINX Plus with the Wallarm module.
  • Postanalytics.

To only process the requests on the server, you must install the following package:

  • nginx-plus-module-wallarm.

Install the Requests Processing and Postanalytics on the Same Server

Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
Ubuntu 18.04 LTS (bionic)
CentOS 6.x
CentOS 7.x
apt-get install --no-install-recommends wallarm-node nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-plus-module-wallarm
yum install yum install wallarm-node nginx-plus-module-wallarm
yum install yum install wallarm-node nginx-plus-module-wallarm

Install Only the Requests Processing

Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
Ubuntu 18.04 LTS (bionic)
CentOS 6.x
CentOS 7.x
apt-get install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-plus-module-wallarm
yum install wallarm-node-nginx nginx-plus-module-wallarm
yum install wallarm-node-nginx nginx-plus-module-wallarm

4. Configure Postanalytics

Skip this step if you installed postanalytics on a separate server as you already have your postanalytics configured.

Postanalytics uses the in-memory storage Tarantool.

You must set the amount of server RAM allocated to Tarantool.

The amount of memory determines the quality of work of the statistical algorithms. The recommended value is 75% of the total server memory. For example, if the server has 32 GB of memory, the recommended allocation size is 24 GB.

Allocate the operating memory size for Tarantool:

Open for editing the configuration file of Tarantool:

Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
Ubuntu 18.04 LTS (bionic)
CentOS 6.x
CentOS 7.x
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool

Set the allocated memory size in the configuration file of Tarantool via the SLAB_ALLOC_ARENA directive.

For example:

SLAB_ALLOC_ARENA=24

Restart Tarantool:

Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
Ubuntu 18.04 LTS (bionic)
CentOS 6.x
CentOS 7.x
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
systemctl restart wallarm-tarantool

5. Connect the Wallarm Module

In the file /etc/nginx/nginx.conf, add the following directive right after the worker_processes directive:

load_module modules/ngx_http_wallarm_module.so;

Confguration example with the added directive:

user  nginx;
worker_processes  auto;
load_module modules/ngx_http_wallarm_module.so;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

Copy the configuration files for the system setup:

cp /usr/share/doc/nginx-plus-module-wallarm/examples/*.conf /etc/nginx/conf.d/


6. Set up the Filter Node for Using a Proxy Server

This setup step is intended for users who use their own proxy server for the operation of the protected web applications.

If you do not use a proxy server, skip this step of the setup.

You need to assign new values to the environment variables, which define the proxy server used, to configure Wallarm node for using your proxy server.

Add the following exports of the new values of the environment variables to the /etc/environment file:

  • Add export https_proxy to define a proxy for the https protocol.
  • Add export http_proxy to define a proxy for the http protocol.
  • Add export no_proxy to define the list of the resources proxy should not be used for.

Assign the <scheme>://<proxy_user>:<proxy_pass>@<host>:<port> string values to the https_proxy and http_proxy variables.

  • <scheme> defines the protocol used. It should match the protocol that the current environment variable sets up proxy for.
  • <proxy_user> defines the username for proxy authorization.
  • <proxy_pass> defines the password for proxy authorization.
  • <host> defines a host of the proxy server.
  • <port> defines a port of the proxy server.

Assign a "<res_1>, <res_2>, <res_3>, <res_4>, ..." array value, where <res_1>, <res_2>, <res_3>, and <res_4> are the IP addresses and/or domains, to the no_proxy variable to define a list of the resources which proxy should not be used for. This array should consist of IP addresses and/or domains.

Resources that need to be addressed without a proxy

Add the following IP addresses and domain to the list of the resources that have to be addressed without a proxy for the system to operate correctly: 127.0.0.1, 127.0.0.8, 127.0.0.9, and localhost.

The 127.0.0.8 and 127.0.0.9 IP addresses are used for the operation of the Wallarm filter node.

The example of the correct /etc/environment file contents below demonstrates the following configuration:

  • The https and http protocols use the 1.2.3.4 host and the 1234 port for request proxying.
  • The https and http protocols use the admin username and the 01234 password for proxy authorization.
  • Proxying is disabled for the requests sent to 127.0.0.1, 127.0.0.8, 127.0.0.9, and localhost.
export https_proxy=http://admin:01234@1.2.3.4:1234
export http_proxy=http://admin:01234@1.2.3.4:1234
export no_proxy="127.0.0.1, 127.0.0.8, 127.0.0.9, localhost"

7. Connect the Filter Node to the Wallarm Cloud

API Access

The API choice for your filter node depends on the Cloud you are using. Please, select the API accordingly:

Ensure the access is not blocked by a firewall.

The filter node interacts with the Wallarm cloud.

To connect the node to the cloud using your cloud account requisites, proceed with the following steps:

  1. Make sure that your Wallarm account has the Administrator role enabled and two-factor authentication disabled, therefore allowing you to connect a filter node to the cloud.

    You can check the aforementioned parameters by navigating to the user account list in the Wallarm console.

    User list in Wallarm console

  2. On the virtual machine run the addnode script:

    You have to pick the script to run depending on the Cloud you are using.

    EU Cloud
    US Cloud
    sudo /usr/share/wallarm-common/addnode
    sudo /usr/share/wallarm-common/addnode -H us1.api.wallarm.com

  3. Provide your Wallarm account’s login and password when prompted.

    8. Configure the Server Addresses of Postanalytics

  • Skip this step if you installed postanalytics and the filter node on the same server.
  • Do this step if you installed postanalytics and the filter node on separate servers.

Add the server address of postanalytics to /etc/nginx/conf.d/wallarm.conf:


     upstream wallarm_tarantool {
        server <ip1>:3313;
        server <ip2>:3313;
        ...
        server <ipN>:3313;
    }

    ...

    wallarm_tarantool_upstream wallarm_tarantool;

9. Configure the Filtration Mode

The etc/nginx/conf.d directory contains NGINX and Wallarm filter node configuration files.

By default, this directory contains the following configuration files:

  • The default.conf file defines the configuration of NGINX.
  • The wallarm.conf file defines the global configuration of Wallarm filter node.
  • The wallarm-status.conf file defines the Wallarm monitoring configuration.

You can create your own configuration files to define the operation of NGINX and Wallarm. It is recommended to create a separate configuration file with the server block for each group of the domains that should be processed in the same way.

To see detailed information about working with NGINX configuration files, proceed to the official NGINX documentation.

Wallarm directives define the operation logic of the Wallarm filter node. To see the list of Wallarm directives available, proceed to the Wallarm configuration options page.

A Configuration File Example

Let us suppose that you need to configure the server to work in the following conditions:

  • Only HTTP traffic is processed. There are no HTTPS requests processed.
  • The following domains receive the requests: example.com and www.example.com.
  • All requests must be passed to the server 10.80.0.5.
  • All incoming requests are considered less than 1MB in size (default setting).
  • The processing of a request takes no more than 60 seconds (default setting).
  • Wallarm must operate in the monitor mode.
  • Clients access the filter node directly, without an intermediate HTTP load balancer.

Creating a configuration file

You can create a custom NGINX configuration file (e.g. example.com.conf) or modify the default NGINX configuration file (default.conf).

When creating a custom configuration file, make sure that NGINX listens to the incoming connections on the free port.

To meet the listed conditions, the contents of the configuration file must be the following:


    server {
      listen 80;
      listen [::]:80 ipv6only=on;

      # the domains for which traffic is processed
      server_name example.com; 
      server_name www.example.com;

      # turn on the monitoring mode of traffic processing
      wallarm_mode monitoring; 
      # wallarm_instance 1;

      location / {
        # setting the address for request forwarding
        proxy_pass http://10.80.0.5; 
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      }
    }

10. 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.

Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
Ubuntu 18.04 LTS (bionic)
CentOS 6.x
CentOS 7.x
systemctl restart nginx
systemctl restart nginx
service nginx restart
service nginx restart
service nginx restart
service nginx restart
systemctl restart nginx


The Installation Is Complete

Check that the filter node runs and filters the traffic. See Check the filter node operation.

results matching ""

    No results matching ""