Installing as a dynamic module for NGINX

Commercial NGINX Plus and Open Source NGINX

The instructions in this section address the filter node installation as a dynamic module for the free open-source NGINX.

If you are running the commercial NGINX Plus, you need a different set of instructions. See Installing with NGINX Plus.

If you have a running NGINX installed in your network infrastructure, you can install Wallarm as a dynamic module for NGINX.

The official and custom builds of NGINX

Wallarm is compatible with NGINX installed from the official NGINX repositories.

If you are planning to install a custom build of NGINX, the dynamic module from the Wallarm repository might be incompatible and will not load. To rebuild the dynamic module, contact Wallarm Support.

With your support request, provide the output of the following commands:

  • Linux kernel version: uname -a
  • Linux distributive: cat /etc/*release
  • NGINX version:

  • Compatibility signature:

    • NGINX official build: egrep -ao '.,.,.,[01]{33}' /usr/sbin/nginx
    • NGINX custom build: egrep -ao '.,.,.,[01]{33}' <path to nginx>/nginx

Installation options

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

  • Processing in NGINX-Module-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 as a dynamic module for NGINX, you must:

  1. Install NGINX.
  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. Connect the filter node to the Wallarm cloud.
  7. Configure the server addresses of postanalytics.
  8. Configure the filtration mode.
  9. Restart NGINX.

1. Install NGINX

You can:

See the official NGINX installation instructions.

2. Add the Wallarm repositories

The installation and updating of the filter node is done from the Wallarm repositories.

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

Debian 7.x (wheezy)
Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
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 wheezy/' >/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/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
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
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:

  • Wallarm module
  • In-memory storage Tarantool.
  • Postanalytics.

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

  • Wallarm module

Install the requests processing and postanalytics on the same server

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

Install only the requests processing

Debian 7.x (wheezy)
Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
CentOS 6.x
CentOS 7.x
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
yum install wallarm-node-nginx nginx-module-wallarm
yum install wallarm-node-nginx nginx-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 7.x (wheezy)
Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
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 7.x (wheezy)
Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
CentOS 6.x
CentOS 7.x
service wallarm-tarantool restart
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
systemctl restart wallarm-tarantool

5. Connect the Wallarm module

Open the /etc/nginx/nginx.conf file.

Ensure that you have the include /etc/nginx/conf.d/* line in the file. If you do not, add it.

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-module-wallarm/examples/*.conf /etc/nginx/conf.d/


6. Connect the filter node to the Wallarm cloud

The filter node interacts with the Wallarm cloud located on a remote server.

The addnode script connects the filter node to the Wallarm cloud.

  1. Run the script addnode: /usr/share/wallarm-common/addnode

  2. Enter the login and password. This is the same login and password that you use to access your Wallarm profile at https://my.wallarm.com. The profile must have the Administrator role and 2FA should be disabled. If the profile has the Analyst role or has 2FA enabled, the script will error out.

API Access

To interact with the Wallarm cloud, the filter node must have access to https://api.wallarm.com:444. Ensure the access is not blocked by a firewall.

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

8. Configure the filtration mode

Uncomment the wallarm_mode string in the file /etc/nginx/conf.d/wallarm.conf.

To uncomment, remove the # character at the beginning of the string.

By default, the directive is set to offwallarm_mode off.

Set it to monitoring.

File contents example:

#
# Wallarm module specific parameters
#

wallarm_mode monitoring;
# wallarm_mode_allow_override on;

9. Restart NGINX

Starting NGINX not under root

If you are running NGINX as a user that is not root, add the user to the wallarm group:

usermod -aG wallarm user_name

where user_name is the user that you use to run NGINX and that is not root.

Debian 7.x (wheezy)
Debian 8.x (jessie)
Debian 9.x (stretch)
Ubuntu 14.04 LTS (trusty)
Ubuntu 16.04 LTS (xenial)
CentOS 6.x
CentOS 7.x
service nginx restart
systemctl restart nginx
systemctl restart nginx
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 ""