Press enter to see results or esc to cancel.

NGINX web server

NGINX Web Server Integration Manual

BotGuard provides the integration module for Nginx web server via operating systems package repository. We support the following operating systems:

  • Debian 10 ("buster"), 9 ("stretch")
  • Ubuntu 20.04 ("focal"), 18.04 ("bionic"), 16.04 ("xenial")
  • RHEL/CentOS 8, 7, 6

The integration procedure depends on the type of operating system used:

Module installation

The version of the BotGuard Nginx extension module must match with the version of Nginx server installed. In addition to the versions from the system repository, which may be outdated, the Nginx assemblies with the current version of the web server from the nginx.org repository are often used. First of all, you should determine the version of Nginx installed on your system, and from which repository you got it. Depending on this, the installation procedure may differ slightly. Use the following command to get this information*:

apt policy nginx
*We assume you are using the root account (use sudo -s or su - if necessary).

As a result of executing this command, a list of Nginx versions available for installation will be displayed. Version installed at the moment, will be marked with asterisks:

 nginx:
   Installed: 1.14.2-2+deb10u2
   Candidate: 1.14.2-2+deb10u2
   Version table:
      1.18.0-5 90
          90 http://deb.debian.org/debian unstable/main amd64 Packages
  *** 1.14.2-2+deb10u2 500
         500 http://deb.debian.org/debian buster/main amd64 Packages
         100 /var/lib/dpkg/status
      1.14.2-2+deb10u1 500
         500 http://security.debian.org/debian-security buster/updates/main amd64 Packages
 

If the Nginx version source URL contains:

  • http://nginx.org/packages/debian, then use the nginx repository
  • http://nginx.org/packages/mainline/debian, then use the nginx-mainline repository
  • http://download.ispsystem.com/repo/debian, then use the nginx repository
  • http://ppa.launchpad.net/ondrej/nginx-mainline/ubuntu, then use the ondrej-mainline repository
  • Otherwise use the main repository

Import the BotGuard package digital signature key:

apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common
curl -fsSL https://repo.botguard.net/botguard.gpg | apt-key add -

Add the BotGuard repository to the system repositories:

add-apt-repository "deb https://repo.botguard.net/debian $(lsb_release -cs) main"

Import the BotGuard package digital signature key:

apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common
curl -fsSL https://repo.botguard.net/botguard.gpg | apt-key add -

Add the BotGuard repository to the system repositories:

add-apt-repository "deb https://repo.botguard.net/debian $(lsb_release -cs) main nginx"

Import the BotGuard package digital signature key:

apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common
curl -fsSL https://repo.botguard.net/botguard.gpg | apt-key add -

Add the BotGuard repository to the system repositories:

add-apt-repository "deb https://repo.botguard.net/debian $(lsb_release -cs) main nginx-mainline"

Import the BotGuard package digital signature key:

apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common
curl -fsSL https://repo.botguard.net/botguard.gpg | apt-key add -

Add the BotGuard repository to the system repositories:

add-apt-repository "deb https://repo.botguard.net/debian $(lsb_release -cs) main ondrej-mainline"

Install the BotGuard Nginx extension module:

apt update
apt install libnginx-mod-botguard

Make sure the Nginx configuration is ok:

nginx -t

Restart the Nginx service:

service nginx restart

Make sure BotGuard module is loaded successfully:

nginx -T 2>/dev/null | grep ngx_botguard_module.so

As a result of executing this command, the following text should be displayed:

load_module modules/ngx_botguard_module.so;

In case the command output is empty (for example when Nginx is installed from nginx.org), then you need to add the following line at the very beginning of the main Nginx configuration file /etc/nginx/nginx.conf:

load_module modules/ngx_botguard_module.so;

and restart the Nginx service:

service nginx restart

Setting the parameters of the module

After installation, the module will be disabled, as it requires preliminary configuration for its operation. To configure the module, run the command:

dpkg-reconfigure libnginx-mod-botguard

Using this command, you can configure the parameters necessary for the module to work in interactive mode:

Instead, you can change the settings of the module by editing its configuration file /etc/nginx/conf.d/50-botguard.conf:

  1. Find the line # botguard_primary_server xxx.botguard.net; and remove the "#" character (uncomment the line). Replace xxx.botguard.net with the address of the primary BotGuard server assigned to your web server.
  2. Find the line # botguard_secondary_server yyy.botguard.net; and remove the "#" character (uncomment the line). Replace yyy.botguard.net with the address of the secondary BotGuard server.
  3. To enable BotGuard protection for all the domains, find the line # botguard_check on; and remove the "#" character (uncomment the line).
  4. Reload Nginx config after saving changes:
    service nginx reload

Diagnostic messages and error messages are logged to the /var/log/nginx/error.log file, depending on Nginx settings.

Module installation

The version of the BotGuard Nginx extension module must match with the version of Nginx server installed. In addition to the versions from the system repository, which may be outdated, the Nginx assemblies with the current version of the web server from the nginx.org repository are often used. First of all, you should determine the version of Nginx installed on your system, and from which repository you got it. Depending on this, the installation procedure may differ slightly. Use the following command to get this information*:

LANG=C yum info nginx | grep -E 'Packages|Name|From repo'
*We assume you are using the root account (use sudo -s or su - if necessary).

As a result of executing this command, a list of Nginx versions installed and available for installation will be displayed:

Installed Packages
Name        : nginx
From repo   : AppStream

Next, depending on the source of the installed package, install the appropriate version of the BotGuard module:

Import the BotGuard package digital signature key:

rpm --import https://repo.botguard.net/botguard.gpg

Add the BotGuard repository to the system repositories:

yum install yum-utils yum-plugin-versionlock
yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo

Install the BotGuard Nginx extension module:

yum install nginx-mod-botguard

Lock installed module version:

yum versionlock nginx-mod-botguard

Import the BotGuard package digital signature key:

rpm --import https://repo.botguard.net/botguard.gpg

Add the BotGuard repository to the system repositories:

yum install yum-utils yum-plugin-versionlock
yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo

Install the BotGuard Nginx extension module:

yum install --disablerepo botguard --enablerepo botguard-nginx nginx-mod-botguard

Lock installed module version:

yum versionlock nginx-mod-botguard

Add a module load line to the config file /etc/nginx/nginx.conf as shown below.

Import the BotGuard package digital signature key:

rpm --import https://repo.botguard.net/botguard.gpg

Add the BotGuard repository to the system repositories:

yum install yum-utils yum-plugin-versionlock
yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo

Install the BotGuard Nginx extension module:

yum install --disablerepo botguard --disablerepo botguard-nginx --enablerepo botguard-nginx-mainline nginx-mod-botguard

Lock installed module version:

yum versionlock nginx-mod-botguard

Add a module load line to the config file /etc/nginx/nginx.conf as shown below.

Import the BotGuard package digital signature key:

rpm --import https://repo.botguard.net/botguard.gpg

Add the BotGuard repository to the system repositories:

yum install yum-utils yum-plugin-versionlock
yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo

Install the BotGuard Nginx extension module:

yum install --disablerepo botguard --enablerepo botguard-bitrix nginx-mod-botguard

Lock installed module version:

yum versionlock nginx-mod-botguard

Add a module load line to the config file /etc/nginx/nginx.conf as shown below.

Make sure the Nginx configuration is ok:

nginx -t

Restart the Nginx service:

service nginx restart

Make sure BotGuard module is loaded successfully:

nginx -T 2>/dev/null | grep ngx_botguard_module.so

As a result of executing this command, the following text should be displayed:

load_module /usr/lib64/nginx/modules/ngx_botguard_module.so;

In case the command output is empty (for example when Nginx is installed from nginx.org), then you need to add the following line at the very beginning of the main Nginx configuration file /etc/nginx/nginx.conf:

load_module /usr/lib64/nginx/modules/ngx_botguard_module.so;

and restart the Nginx service:

service nginx restart

Setting the parameters of the module

After installation, the module will be disabled, as it requires preliminary configuration for its operation. To configure the module, edit its config file /etc/nginx/conf.d/50-botguard.conf.

  1. Find the line # botguard_primary_server xxx.botguard.net; and remove the "#" character (uncomment the line). Replace xxx.botguard.net with the address of the primary BotGuard server assigned to your web server.
  2. Find the line # botguard_secondary_server yyy.botguard.net; and remove the "#" character (uncomment the line). Replace yyy.botguard.net with the address of the secondary BotGuard server.
  3. To enable BotGuard protection for all the domains, find the line # botguard_check on; and remove the "#" character (uncomment the line).
  4. Reload Nginx config after saving changes:
    service nginx reload

Diagnostic messages and error messages are logged to the /var/log/nginx/error.log, depending on Nginx settings.