Nginx Web Server

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

• Debian 13 ("trixie"), 12 ("bookworm"), 11 ("bullseye")
• Ubuntu 26.04 ("resolute"), 24.04 ("noble"), 22.04 ("jammy"), 20.04 ("focal")
• RHEL/CentOS 10, 9, 8

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

We recommend managing Blackwall via GateKeeper directly or one of Blackwall's integration modules, not both.

Running them concurrently can cause configuration conflicts and complicate troubleshooting. Pick one interface and use it consistently for all changes. This matters especially in hosted environments, where service providers don't have access to customer integration module instances.

Debian and Ubuntu

Module Installation

Note

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

The version of the Blackwall 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.

1. Use the following command to get this information:

   apt policy nginx
   

2. As a result of executing the previous command, a list of Nginx versions available for installation display. The version installed currently is 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
   

3. If the Nginx version source URL contains:

   • http://nginx.org/packages/debian, then use the nginx repository.
   • http://nginx.org/packages/mainline/debian, use the nginx-mainline repository.
   • http://download.ispsystem.com/repo/debian, use the nginx repository.
   • Otherwise use the main repository.
4. mainnginxnginx-mainline

   a. Import the Blackwall package digital signature key:

   ```bash
   apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common sudo
   
   curl -fsSL https://repo.botguard.net/botguard.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/botguard.gpg >/dev/null
   ```
   

   b. Add the Blackwall repository to the system repositories:

   ```bash
   echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/botguard.list
   ```
   

   a. Import the Blackwall package digital signature key:

   apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common sudo
   
   curl -fsSL https://repo.botguard.net/botguard.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/botguard.gpg >/dev/null
   

   b. Add the Blackwall repository to the system repositories:

   echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian $(lsb_release -cs) main nginx" | sudo tee /etc/apt/sources.list.d/botguard.list
   

   a. Import the Blackwall package digital signature key:

   apt install curl gpg ca-certificates lsb-release apt-utils whiptail apt-transport-https software-properties-common sudo
   
   curl -fsSL https://repo.botguard.net/botguard.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/botguard.gpg >/dev/null
   

   b. Add the Blackwall repository to the system repositories:

   echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian $(lsb_release -cs) main nginx-mainline" | sudo tee /etc/apt/sources.list.d/botguard.list
   

5. Install the Blackwall Nginx extension module:

   apt update
   apt install libnginx-mod-botguard
   

6. Make sure the Nginx configuration is good:

   nginx -t
   

7. Restart the Nginx service:

   systemctl restart nginx
   

8. Make sure Blackwall module is loaded successfully:

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

9. After running the previous command, confirm that the following text displays:

   load_module modules/ngx_botguard_module.so;
   

10. Now restart the Nginx service:

    systemctl restart nginx
    

Setting module parameters

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 module settings parameters 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 Blackwall 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 Blackwall server.
3. To enable Blackwall 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:

   systemctl reload nginx
   

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

RHEL/CentOS

Module Installation

Note

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

The version of the Blackwall 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.

1. Use the following command to get this information:

   LANG=C yum info nginx | grep -E 'Packages|Name|From repo'
   

2. As a result of executing this command, a list of Nginx versions installed and available for installation display:

   Installed Packages
   Name        : nginx
   From repo   : AppStream
   

3. epel, AppStreamnginx-stable, ispsystem-basenginx-mainlinebitrix

   a. Import the Blackwall package digital signature key:

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

   b. Add the Blackwall repository to the system repositories:

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

   c. Install the Blackwall Nginx extension module:

   yum install nginx-mod-botguard
   

   d. Lock installed module version:

   yum versionlock nginx-mod-botguard
   

   a. Import the Blackwall package digital signature key:

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

   b. Add the Blackwall repository to the system repositories:

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

   c. Install the Blackwall Nginx extension module:

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

   d. Lock installed module version:

   yum versionlock nginx-mod-botguard
   

   a. Import the Blackwall package digital signature key:

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

   b. Add the Blackwall repository to the system repositories:

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

   c. Install the Blackwall Nginx extension module:

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

   d. Lock installed module version:

   yum versionlock nginx-mod-botguard
   

   a. Import the Blackwall package digital signature key:

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

   b. Add the Blackwall repository to the system repositories:

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

   c. Install the Blackwall Nginx extension module:

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

   d. Lock installed module version:

   yum versionlock nginx-mod-botguard
   

4. Make sure the Nginx configuration is good:

   nginx -t
   

5. Restart the Nginx service:

   systemctl restart nginx
   

6. Make sure that the Blackwall module loads successfully:

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

7. As a result of executing the previous command, check that the following text displays:

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

8. In the unlikely case that the command output is empty in the previous step (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 then restart the Nginx service:

   systemctl restart nginx
   

Setting module parameters

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

1. Open the config file /etc/nginx/conf.d/50-botguard.conf.
2. In the opened file, 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 Blackwall server assigned to your web server.
3. 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 Blackwall server.
4. To enable Blackwall protection for all the domains, find the line # botguard_check on; and remove the "#" character (uncomment the line).
5. Reload Nginx config after saving changes:

   systemctl reload nginx
   

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

Feedback