BotGuard Integration Guide

The purpose of this document is to provide BotGuard clients with key information related to integration method choice so that integration implementation takes as little time as possible. If you're having trouble deciding which method to choose, please contact our support team at support@botguard.net. Our specialists will help you to choose the most suitable integration option.

The different integration methods provide different capabilities to detect and block bad bots. The best result is obtained when implementing integration at the web server level, or load balancer level in case of using multiple web servers.

We advise you to utilize the following algorithm to choose the best integration method.

  1. Which type of server do you use?

    How to check: take a look at the features of the tariff plan provided by your hosting provider.
    If shared hosting is used, go to step 3, otherwise check the type of web server you are using, step 2.
  2. What type of web server do you use?

    How to check: use an online service like BrowserSpy to determine the type of web server used.
    In case the site uses the Apache web server, follow the instructions for integrating with the Apache. If the site uses the Nginx web server, follow the instructions for integrating with the Nginx.
  3. Do you use a WordPress content management system?

    How to check: go to the website admin panel and find a WordPress logo in the top left corner of the screen:
    In case you are using WordPress, follow the instructions for integrating with WordPress.
  4. Is your website based on PHP language?

    How to check: go to your hosting provider control panel and open your website file manager. If there is an index.php file in the files list, then your website is PHP-based.
    BotGuard provides a module for integrating a service with any web application written in PHP. Follow the instructions for integrating with PHP applications.
  5. Do you need an individual solution?

    Please contact our support team at support@botguard.net.



 

Apache Web Server Integration Instructions

BotGuard provides the integration module for Apache web server version 2.2 and above from own package repository. Supported operating systems are:

  • Debian 10 ("buster")
  • Debian 9 ("stretch")
  • Ubuntu 18.04 ("bionic")
  • RHEL 6 / CentOS 6
  • RHEL 7 / CentOS 7
  • RHEL 8 / CentOS 8

Installation and updating of packages is done in a standard way. We assume you are operating under root account (use sudo -s if needed).

Debian, Ubuntu

Import the BotGuard digital signature key:

wget -qO - https://repo.botguard.net/botguard.gpg | apt-key add -

Add the BotGuard repository to the operating system:

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

Install the BotGuard module for Apache Web Server:

apt-get install libapache2-mod-botguard

The configuration file will be installed to /etc/apache2/mods-available/botguard.conf.

RHEL, CentOS

Import the BotGuard digital signature key:

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

Add the BotGuard repository to the operating system:

yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo

Clean packages cache:

yum clean all

Install the BotGuard module for Apache Web Server:

yum install mod_botguard

The configuration file will be installed to /etc/httpd/conf.modules.d/10-botguard.conf.

Configure the module

The module is disabled by default when installed, because it should be configured before use. To configure the module, edit the above mentioned configuration file.

  1. Find the following text # BotguardPrimaryServer "xxx.botguard.net" and remove the "#" character ("uncomment"). Replace xxx.botguard.net with the address of the primary BotGuard server assigned to your website.
  2. Find the following text # BotguardSecondaryServer "yyy.botguard.net" and remove the "#" character ("uncomment"). Replace yyy.botguard.net with the address of the secondary server.
  3. Find the following text # BotguardCheck on and remove the "#" character ("uncomment"). Save your changes.
  4. Restart the Apache to apply changes:
    service apache2 restart # Debian, Ubuntu
    service httpd restart # RHEL, CentOS

Go to the BotGuard control panel and press the "Check" button to verify that everything is working properly. If not, please contact our support team at support@botguard.net.

Diagnostic and error messages are logged to error.log according your Apache configuration.




 

Nginx Web Server Integration Instructions

BotGuard provides the integration module for Nginx web server version 1.10 and above from own package repository. Supported operating systems are:

  • Debian 10 ("buster")
  • Debian 9 ("stretch")
  • Ubuntu 18.04 ("bionic")
  • RHEL 7 / CentOS 7
  • RHEL 8 / CentOS 8

Installation and updating of packages is done in a standard way. We assume you are operating under root account (use sudo -s if needed).

Debian, Ubuntu

Import the BotGuard digital signature key:

wget -qO - https://repo.botguard.net/botguard.gpg | apt-key add -

Add the BotGuard repository to the operating system:

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

Install the BotGuard module for Nginx:

apt-get install libnginx-mod-botguard

The configuration file will be installed to /etc/nginx/conf.d/50-botguard.conf.

RHEL, CentOS

Import the BotGuard digital signature key:

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

Add the BotGuard repository to the operating system:

yum-config-manager --add-repo https://repo.botguard.net/BotGuard.repo

Clean packages cache:

yum clean all

Install the BotGuard module for Nginx:

yum install nginx-mod-botguard

The configuration file will be installed to /etc/nginx/default.d/50-botguard.conf.

Configure the module

The module is disabled by default when installed, because it should be configured before use. To configure the module, edit the above mentioned configuration file.

  1. Find the following text # botguard_primary_server xxx.botguard.net; and remove the "#" character ("uncomment"). Replace xxx.botguard.net with the address of the primary BotGuard server assigned to your website.
  2. Find the following text # botguard_secondary_server yyy.botguard.net; and remove the "#" character ("uncomment"). Replace yyy.botguard.net with the address of the secondary server.
  3. Find the following text # botguard_check on; and remove the "#" character ("uncomment"). If you are using the multicore CPU, find and uncomment the text # aio threads; too. Save your changes.
  4. Restart the Nginx to apply changes:
    service nginx restart

Go to the BotGuard control panel and press the "Check" button to verify that everything is working properly. If not, please contact our support team at support@botguard.net.

Diagnostic and error messages are logged to error.log according your Nginx configuration.




 

Nginx Web Server Integration — Alternate Way

If you use your own Nginx server build, or the BotGuard module for Nginx is not suitable, use this alternative integration method. To integrate the Nginx web server with this method, you don’t need to install additional software, you only need to make changes to the Nginx configuration files.

  1. Make sure that nginx is compiled with the http_auth_request_module module running the following command:
    2>&1 nginx -V | tr -- - '\n' | grep -q http_auth_request_module && echo 'Test successfull' || echo 'Test failed'
    If the result of this command is "Test successful", then everything is fine. Otherwise, try installing another version of Nginx from the system repository or from the official site.
  2. Specify the nginx version you are using. To do this, run the following command:
    nginx -v
  3. Download the archive with the sample BotGuard Nginx configuration file and unpack it. In case you are using Nginx version 1.11.7 or later, edit the nginx/botguard/botguard.conf file. Find the line:
    # proxy_set_header
    and remove the "#" character ("uncomment") to make it:
     proxy_set_header
    There are 4 such lines in the file. Do uncomment all of them.
  4. Edit the file nginx/conf.d/botguard-upstream.conf. Find the following text:
    server xxx.botguard.net fail_timeout=1;
    server yyy.botguard.net backup;
    Replace xxx.botguard.net with the address of the primary BotGuard server assigned to your website. Replace yyy.botguard.net with the address of the secondary server.
  5. Copy the botguard folder with the botguard.conf file to your server to the /etc/nginx/ directory.
  6. Copy the botguard-upstream.conf file to your server to the /etc/nginx/conf.d/ directory.
  7. Find on your server a file with the website configuration settings. It should contain the following piece of code:
    server {
    ...
    server_name YOUR_DOMAIN
    It is usually located in /etc/nginx/sites-available/, or /etc/nginx/conf.d/, or /etc/nginx/vhosts/www-root/. Open this file and find the following line:
    server_name YOUR_DOMAIN
    After this line add the line:
    include botguard/botguard.conf;
    Next, find the line:
    location / {
    After this line add the line:
    auth_request /botguard_check;
    Depending on your Nginx configuration, if there are other entry points, you may need to add similar line to other location ... { } sections, see an example at nginx/sites-available/default.conf.
  8. Save the changes in the configuration file to your server and verify that the configuration is correct by running the command:
    nginx -t
    As a result, you should receive a message:
    nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
    nginx: configuration file /etc/nginx/nginx.conf test is successful
  9. Apply these changes by running the command:
    service nginx restart
  10. Go to the BotGuard control panel and press the "Check" button to verify that everything is working properly. If not, please contact our support team at support@botguard.net.



 

Integration with WordPress CMS (Content Management System)

BotGuard provides a special WordPress module ("plugin"). The module source code is available on GitHub.

Installing the module is simple and standard:

  1. Download the WordPress module file.
  2. Open the WordPress control panel and go to the "Plugins" section. Click the "Add New" button:

  3. On the Add plugin page, click the "Upload Plugin" button:

  4. Click the Browse button, select the botguard-1.0.4.zip file downloaded on the first step, and click the "Install Now" button:

  5. Wait a couple of seconds for the plugin installation completion. Click the "Activate Plugin" button:

  6. Open the menu and select "Settings" → "BotGuard" to open the Plugin settings page:

  7. Enter the addresses of the primary and secondary BotGuard servers. Get the server addresses from the BotGuard control panel. Click the "Save Changes" button.

  8. Go to the BotGuard control panel and press the "Check" button to verify that everything is working properly. If not, please contact our support team at support@botguard.net.



 

Other PHP applications

Are you a web developer? Please use our PHP library to integrate the BotGuard service with any web application written in PHP. The library is available on GitHub along with a quick-start guide and examples of use.

Not a developer? Please follow these simple steps:

  1. Download the archive with the necessary files and unzip it. It contains 3 files: index.php, BotGuard.php, and Profile.php.
  2. Edit the index.php file:
    • Replace xxx.botguard.net with the address of the primary BotGuard server assigned to your site. Get the server address from the BotGuard control panel.
    • Replace yyy.botguard.net with the address of the secondary BotGuard server assigned to your site. Get the server address from the BotGuard control panel.
  3. Open your hosting provider file management tool (file upload panel or FTP client), and find the index.php file in the root directory of your website. Rename this index.php file to index.php.original.
  4. Upload the new index.php, BotGuard.php, and Profile.php files to the root directory of your website.
  5. Go to the BotGuard control panel and press the "Check" button to verify that everything is working properly. If not, please contact our support team at support@botguard.net.