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 11 ("bullseye"), 10 ("buster"), 9 ("stretch")
- Ubuntu 22.04 ("jammy"), 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 thenginx
repositoryhttp://nginx.org/packages/mainline/debian
, then use thenginx-mainline
repositoryhttp://download.ispsystem.com/repo/debian
, then use thenginx
repositoryhttp://ppa.launchpad.net/ondrej/nginx-mainline/ubuntu
, then use theondrej-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 sudo curl -fsSL https://repo.botguard.net/botguard.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/botguard.gpg >/dev/null
Add the BotGuard repository to the system repositories:
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
Import the BotGuard 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
Add the BotGuard 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
Import the BotGuard 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
Add the BotGuard 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
Import the BotGuard 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
Add the BotGuard repository to the system repositories:
echo "deb [signed-by=/usr/share/keyrings/botguard.gpg] https://repo.botguard.net/debian $(lsb_release -cs) main ondrej-mainline" | sudo tee /etc/apt/sources.list.d/botguard.list
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
:
- Find the line
# botguard_primary_server xxx.botguard.net;
and remove the "#" character (uncomment the line). Replacexxx.botguard.net
with the address of the primary BotGuard server assigned to your web server. - Find the line
# botguard_secondary_server yyy.botguard.net;
and remove the "#" character (uncomment the line). Replaceyyy.botguard.net
with the address of the secondary BotGuard server. - To enable BotGuard protection for all the domains, find the line
# botguard_check on;
and remove the "#" character (uncomment the line). - 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
.
- Find the line
# botguard_primary_server xxx.botguard.net;
and remove the "#" character (uncomment the line). Replacexxx.botguard.net
with the address of the primary BotGuard server assigned to your web server. - Find the line
# botguard_secondary_server yyy.botguard.net;
and remove the "#" character (uncomment the line). Replaceyyy.botguard.net
with the address of the secondary BotGuard server. - To enable BotGuard protection for all the domains, find the line
# botguard_check on;
and remove the "#" character (uncomment the line). - 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.
Comments
Comments for this post are closed.