Integration Guide

This document describes the procedure for integrating your web site with the BotGuard Cloud. Depending on the software you use and your needs, a choice of several ways of integration are possible.

In case of difficulties in choosing the required integration option, contact the support. BotGuard engineers can help you to select optimal integration option. It is also possible to fully configure your server by our engineers efforts.

Different integration methods provide slightly different capabilities for detecting and blocking bots. The best result can be obtained when integrating at the web server or load balancer level (in case of using multiple web servers). Use this algorithm for choosing the best integration method:

  1. Are you using a dedicated server, virtual server, or shared hosting?

    If shared hosting is used, go to step 3, otherwise check the type of web server you are using, step 2.
    How to find out?
    Check with your hosting service provider which tariff plan you are using.
  2. Are you using the Nginx web server?

    In case the site uses this web server, follow the instructions for integrating with the Nginx.
    How to find out?
    There are many online services, such as BrowserSpy, where you can determine the type of web server used by your site (apache, nginx or other).
  3. Does the site use WordPress content management system?

    In case you are using WordPress, follow the instructions for integrating with WordPress.
    How to find out?
    Visit the admin panel of your site. In case you are using WordPress, in the upper left corner you will see the logo of this system:
  4. Is the website designed using the PHP programming language?

    BotGuard provides a module for integrating a service with any web application written in PHP. Follow the instructions for integrating with PHP applications.
    How to find out?
    Log in to the file control panel of your site through your hosting provider. If there is an index.php file in the list of site files, then your site has been developed using PHP.
  5. Need an individual solution?

    In other cases, we do not have standard integration options yet. Contact support and we will figure out what can be done.


Nginx Web Server Integration Instructions

To integrate the Nginx web server with the BotGuard service, you do not 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 by 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 successfull", then everything is fine. If "Test failed", then try to install different Nginx version from system repository or official site.
  2. Find out what version of Nginx you are using. To do this, run the following command:
    nginx -v
  3. Download the example of BotGuard configuration file for Nginx. 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"):
    There are 4 such lines in the file, this should be done with each of them.
  4. Edit the nginx/conf.d/botguard-upstream.conf file, find the following fragment:
    server fail_timeout=1;
    server backup;
    Replace the by primary BotGuard server address assigned to your website, and by secondary one.
  5. Copy the botguard folder with the botguard.conf file inside to your server into the /etc/nginx/ directory. Copy the botguard-upstream.conf file to your server into the /etc/nginx/conf.d/ directory.
  6. Find a file with the configuration of your site on your server. It should contain the following fragment:
    server {
    server_name YOUR_DOMAIN
    It is usually located in the /etc/nginx/sites-available/, or /etc/nginx/conf.d/, or /etc/nginx/vhosts/www-root/ directory. In this file just after the line:
    server_name YOUR_DOMAIN
    Add this line:
    include botguard/botguard.conf;
    Next, in that file you need to find the line:
    location / {
    and after it, add:
    auth_request /botguard_check;
    Depending on your individual Nginx configuration, if there are other entry points, you may need to add such a line to other location ... { } sections, see the nginx/sites-available/default.conf example file.
  7. Save the changes in the configuration file into your server and verify that the setting is correct by running the command:
    nginx -t
    As a result, it should print the message:
    nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
    nginx: configuration file /etc/nginx/nginx.conf test is successful
  8. Apply changes by running the command:
    service nginx restart

After restarting the Nginx server, check that everything works fine by clicking the "Check" button in the BotGuard control panel.


WordPress Content Management System Integration Instructions

BotGuard provides plugin for WordPress CMS. Plugin source code is available on GitHub.

The installation of the plugin is done by the usual way in WordPress:

  1. Download the plugin file.
  2. Go to the WordPress control panel. In the control panel go to the "Plugins" section and click the "Add New" button:

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

  4. Click the "Browse" button, select the file, that was downloaded in step 1. Next, click the "Install Now" button:

  5. After a couple of seconds, the plugin will be installed. Click the "Activate Plugin" button:

  6. Go to the plug-in settings page. To do this, select "Settings" → "BotGuard" from the menu:

  7. Enter the address of the primary and secondary BotGuard server, check the "Enabled" checkbox, and click the "Save Changes" button.

    The necessary values for the addresses of BotGuard servers can be obtained on the BotGuard Dashboard.


Other PHP applications

If you are a web developer, please use our library to integrate the service with any web application written in PHP. The library is available on GitHub, where you will find instructions for connecting to your project and examples of use.

If you are not a web developer, then follow these simple instructions:

  1. Download the archive with the necessary files and unzip it. It contains 3 files: index.php, BotGuard.php и Profile.php.
  2. Edit the index.php file. Replace in the text with the address of the primary BotGuard server assigned to your site, and with the secondary one.
  3. Using the hosting file access tool (hosting file upload panel or FTP client), find the index.php file in the root directory of your site files. Rename the found file into index.php.original.
  4. Copy the new index.php, BotGuard.php, and Profile.php files into the root directory of your site on the server.

After the files are copied, check that everything works fine by clicking the "Check" button in the BotGuard control panel.