Руководство по интеграции

В этом документе рассматривается процедура интеграции вашего веб сайта с сервисом BotGuard. В зависимости от используемого вами ПО и ваших потребностей, возможен выбор из нескольких представленных способов интеграции.

В случае возникновения затруднений при выборе необходимого варианта интеграции, обратитесь в поддержку — специалисты BotGuard подберут оптимальный вариант интеграции. Возможна полная настройка вашего сайта силами наших специалистов.

Разные способы интеграции обеспечивают немного разные возможности по обнаружению и блокировке ботов. Наилучший результат можно получить при интеграции на уровне веб-сервера или балансировщика нагрузки (в случае использования нескольких веб-серверов). Воспользуйтесь этим алгоритмом выбора наилучшего метода интеграции:

Вы являетесь хостинг провайдером и хотите предоставлять сервис BotGuard своим клиентам?
В случае, если используется панель управления разделяемым хостингом WHM / CPanel, следуйте инструкции по интеграции с WHM / CPanel.
Вы используете выделенный сервер, виртуальный сервер или разделяемый хостинг?
В случае если используется разделяемый (shared) хостинг, переходите к пункту 4, иначе проверьте тип используемого веб-сервера, пункт 3.
Как проверить?
Уточните у вашего поставщика услуг хостинга, какой тарифный план вы используете.
Какой веб-сервер используется?
В случае, если на сайте используется веб-сервер Apache, следуйте инструкции по интеграции с сервером Apache. Если на сайте используется веб-сервер Nginx, следуйте инструкции по интеграции с сервером Nginx.
Как проверить?
С помощью онлайн сервисов, например BrowserSpy, можно определить тип используемого веб-сервера вашего сайта (apache, nginx или другой).
На сайте используется система управления содержанием WordPress?
В случае, если вы используете WordPress, следуйте инструкции по интеграции с WordPress.
Как проверить?
Перейдите в административную панель вашего сайта. В случае, если вы используете WordPress, в левом верхнем углу вы увидите логотип этой системы:
Веб-сайт разработан с помощью языка программирования PHP?
BotGuard предоставляет модуль для интеграции сервиса с любым веб приложением, написанном на PHP. Следуйте инструкции по интеграции с PHP-приложениями.
Как проверить?
Зайдите в панель управления файлами вашего сайта через вашего поставщика услуг хостинга. Если в перечне файлов сайта есть файл index.php, то ваш сайт разработан с помощью PHP.
Требуется индивидуальное решение?
В прочих случаях у нас пока нет типовых вариантов интеграции. Обратитесь в поддержку и мы придумаем, что можно сделать.

Инструкции по интеграции с веб-сервером Apache

BotGuard предоставляет модуль для интеграции с веб-сервером Apache версии 2.2 и выше через репозиторий пакетов. Поддерживаются следующие операционные системы Linux:

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

Установка и обновление пакетов производится обычным в операционной системе способом. Мы предполагаем, что вы используете учётную запись root (используйте sudo -s при необходимости).

Debian, Ubuntu

Импортируйте ключ цифровой подписи пакетов BotGuard:

curl -L https://repo.botguard.net/botguard.gpg | apt-key add -

Добавьте репозиторий BotGuard в систему:

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

Установите модуль BotGuard для Apache Web Server:

apt-get install libapache2-mod-botguard

Файл конфигурации модуля будет установлен в /etc/apache2/mods-available/botguard.conf.

RHEL, CentOS

Импортируйте ключ цифровой подписи пакетов BotGuard:

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

Добавьте репозиторий BotGuard в систему:

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

Выполните очистку кэша пакетов:

yum clean all

Установите модуль BotGuard для Apache Web Server:

yum install mod_botguard

Файл конфигурации модуля будет установлен в /etc/httpd/conf.modules.d/10-botguard.conf.

Настройка параметров работы модуля

После установки модуль отключён, так как для его работы необходима предварительная настройка. Для настройки модуля, отредактируйте его конфигурационный файл, установленный по пути, указанном выше.

Найдите строку # BotguardPrimaryServer "xxx.botguard.net" и удалите символ "#" ("раскомментируйте"). Замените xxx.botguard.net на адрес основного сервера BotGuard, назначенный вашему сайту.
Найдите строку # BotguardSecondaryServer "yyy.botguard.net" и удалите символ "#" ("раскомментируйте"). Замените yyy.botguard.net на адрес дополнительного сервера.
Найдите строку # BotguardCheck on и удалите символ "#" ("раскомментируйте"). Сохраните изменения.
Перезапустите сервер Apache для того, чтобы настройки модуля вступили в силу:
```
service apache2 restart # Debian, Ubuntu
service httpd restart # RHEL, CentOS
```

Дигностические сообщения и сообщения об ошибках логируются в файл error.log, в зависимости от настроек Apache. После перезапуска сервера проверьте, что всё работает нормально, нажав кнопку «Проверить» в панели управления BotGuard.

Инструкции по интеграции с веб-сервером Nginx

BotGuard предоставляет модуль для интеграции с веб-сервером Nginx версий 1.10 и выше через репозиторий пакетов. Поддерживаются следующие операционные системы Linux:

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

Debian, Ubuntu

Импортируйте ключ цифровой подписи пакетов BotGuard:

curl -L https://repo.botguard.net/botguard.gpg | apt-key add -

Добавьте репозиторий BotGuard в систему:

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

Установите модуль BotGuard для Nginx:

apt-get install libnginx-mod-botguard

Файл конфигурации модуля будет установлен в /etc/nginx/conf.d/50-botguard.conf.

RHEL, CentOS

Импортируйте ключ цифровой подписи пакетов BotGuard:

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

Добавьте репозиторий BotGuard в систему:

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

Выполните очистку кэша пакетов:

yum clean all

Установите модуль BotGuard для Nginx:

yum install nginx-mod-botguard

Файл конфигурации модуля будет установлен в /etc/nginx/default.d/50-botguard.conf.

Настройка параметров работы модуля

Найдите строку # botguard_primary_server xxx.botguard.net; и удалите символ "#" ("раскомментируйте"). Замените xxx.botguard.net на адрес основного сервера BotGuard, назначенный вашему сайту.
Найдите строку # botguard_secondary_server yyy.botguard.net; и удалите символ "#" ("раскомментируйте"). Замените yyy.botguard.net на адрес дополнительного сервера.
Найдите строку # botguard_check on; и удалите символ "#" ("раскомментируйте"). Если вы используете многоядерный процессор, также найдите и раскомментируйте строку # aio threads;. Сохраните изменения.
Перезапустите сервер Nginx для того, чтобы настройки модуля вступили в силу:
```
service nginx restart
```

Дигностические сообщения и сообщения об ошибках логируются в файл error.log, в зависимости от настроек Nginx. После перезапуска сервера проверьте, что всё работает нормально, нажав кнопку «Проверить» в панели управления BotGuard.

Инструкции по интеграции с веб-сервером Nginx (альтернативный способ)

В случае, если используется собственная сборка сервера Nginx и модуль BotGuard для Nginx не подходит, используйте этот альтернативный способ интеграции. Для этой интеграции веб сервера Nginx с сервисом BotGuard не требуется устанавливать дополнительное ПО, необходимо только внести изменения в конфигурационные файлы Nginx.

Убедитесь, что Nginx скомпилирован с модулем http_auth_request_module, выполнив следующую команду:
```
2>&1 nginx -V | tr -- - '\n' | grep -q http_auth_request_module && echo 'Test successfull' || echo 'Test failed'
```
Если результатом выполнения этой команды будет «Test successfull», то всё в порядке. Если «Test failed», то попробуйте установить другую версию Nginx из системного репозитория или с официального сайта.
Уточните используемую версию Nginx. Для этого выполните следующую команду:
```
nginx -v
```
Загрузите архив с примером конфигурационного файла BotGuard для Nginx и распакуйте его. В случае, если вы используете Nginx версии 1.11.7 и старше, отредактируйте файл nginx/botguard/botguard.conf. Найдите строку:
```
# proxy_set_header
```
и удалите символ "#" ("раскомментируйте"), чтобы получилось:
```
 proxy_set_header
```
Всего в файле 4 таких строки, это нужно сделать с каждой из них.
Отредактируйте файл nginx/conf.d/botguard-upstream.conf. В текстовом фрагменте:
```
server xxx.botguard.net fail_timeout=1;
server yyy.botguard.net backup;
```
замените xxx.botguard.net на адрес основного сервера BotGuard, назначенный вашему сайту, а yyy.botguard.net на адрес дополнительного сервера.
Скопируйте папку botguard с файлом botguard.conf внутри на ваш сервер в каталог /etc/nginx/. Скопируйте файл botguard-upstream.conf на ваш сервер в каталог /etc/nginx/conf.d/.
Найдите на вашем сервере файл с конфигурацией вашего сайта, он должен содержать такой фрагмент:
```
server { 
...
server_name ваш_домен
```
Обычно он находится в каталоге /etc/nginx/sites-available/ или /etc/nginx/conf.d/ или /etc/nginx/vhosts/www-root/. В найденном файле после строки:
```
server_name ваш_домен
```
необходимо добавить строку:
```
include botguard/botguard.conf;
```
Далее, в файле необходимо найти строку
```
location / {
```
и после неё добавить:
```
auth_request /botguard_check;
```
В зависимости от вашей индивидуальной конфигурации Nginx, если существуют другие точки входа, может потребоваться добавить такую строку и в другие секции location ... { }, см в примере nginx/sites-available/default.conf.
Сохраните изменения в файле конфигурации на ваш сервер и проверьте, что настройка выполнена верно, выполнив команду:
```
nginx -t
```
В результате, вы должны получить сообщение:
```
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
```
Примените сделанные изменения, выполнив команду:
```
service nginx restart
```

После перезапуска сервера Nginx проверьте, что всё работает нормально, нажав кнопку «Проверить» в панели управления BotGuard.

Инструкции по интеграции с системой управления содержанием (CMS) WordPress

BotGuard предоставляет модуль («плагин») для WordPress. Исходный код модуля доступен на GitHub.

Установка модуля производится общепринятым в WordPress способом:

Загрузите файл модуля для WordPress.
Перейдите в панель управления WordPress. В панели управления перейдите в раздел «Плагины» и нажмите кнопку «Добавить новый»:
На странице добавление плагина нажмите кнопку «Загрузить плагин»:
Нажмите кнопку «Обзор», выберите файл botguard-1.0.4.zip, который был загружен на шаге 1. После этого нажмите кнопку «Установить сейчас»:
Через пару секунд плагин будет установлен. Нажмите кнопку «Активировать плагин»:
Перейдите на страницу настроек плагина. Для этого в меню выберите пункт «Настройки» → «BotGuard»:
Введите адрес главного и вспомогательного сервера BotGuard, установите флажок «Включить» и нажмите кнопку «Сохранить изменения»:
Необходимые значения адреса серверов BotGuard вы можете получить в панели управления BotGuard.

Прочие PHP приложения

Если вы являетесь веб-разработчиком, то воспользуйтесь нашей библиотекой для интеграции сервиса с любым веб приложением, написанном на PHP. Библиотека доступна на GitHub, там же вы найдёте инструкции по подключению к вашему проекту и примеры использования.

Если вы — не веб-разработчик, то следуйте этой простой инструкции:

Загрузите архив с необходимыми файлами и распакуйте его — он содержит 3 файла: index.php, BotGuard.php и Profile.php.
Отредактируйте файл index.php. Замените в тексте xxx.botguard.net на адрес основного сервера BotGuard, назначенный вашему сайту, а yyy.botguard.net на адрес дополнительного сервера.
С помощью средства доступа к файлам на хостинге (панель загрузки файлов хостинга или FTP-клиент) найдите файл index.php в корневом каталоге файлов вашего сайта. Переименуйте найденный файл в index.php.original.
Скопируйте новые файлы index.php, BotGuard.php и Profile.php в корневой каталог вашего сайта на сервере.

После того, как файлы скопированы, проверьте, что всё работает нормально, нажав кнопку «Проверить» в панели управления BotGuard.

Интеграция с WHM / CPanel (панель управления сайтами)

Для партнеров: BotGuard предоставляет модуль интеграции с помощью WHM / CPanel. При установке модуля активируется плагин защиты веб-сервера Apache, а в панели управления появляются опции настройки для администратора WHM и пользователя CPanel.

Модуль предоставляется в виде пакета для CentOS 7. Установка и обновление модуля производится стандартным для операционной системы способом, с помощью SSH-подключения к серверу WHM.

Импортируйте ключ цифровой подписи пакетов BotGuard:

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

Добавьте репозиторий BotGuard в систему:

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

Выполните очистку кэша пакетов:

yum clean all

Установите модуль BotGuard для WHM / CPanel:

yum install botguard-whm

В качестве зависимости также будет установлен модуль BotGuard для EasyApache — ea-apache24-mod_botguard. Перезапустите сервер Apache:

/usr/local/cpanel/scripts/restartsrv_httpd

Поддержка Nginx в WHM / CPanel

Панель управления веб-сайтами WHM / CPanel в качестве веб-сервера использует Apache. Некоторые пользователи предпочитают использование веб-сервера Nginx вместо Apache, который не входит в стандартную поставку панели управления. Существует проект с открытым исходным кодом Engintron, который обычно рекомендуется для решения этой задачи.

Модуль интеграции BotGuard поддерживает Engintron. Для интеграции модуля с Engintron необходимо выполнить дополнительные шаги после установки модуля BotGuard:

Установите модуль BotGuard для Nginx, согласно инструкции.
Отключите модуль BotGuard для Apache. Для этого в файле /etc/apache2/conf.modules.d/10-botguard.conf закомментируйте строку (добавьте символ # в начало) загрузки модуля, чтобы получилось так:
```
# LoadModule botguard_module modules/mod_botguard.so
```
Перезапустите веб-сервер Apache:
```
/usr/local/cpanel/scripts/restartsrv_httpd
```
Удалите задачу планировщика cron для Engintron, для чего в файле /etc/crontab закомментируйте соответствующую строку, чтобы получилось так:
```
# * * * * * root /etc/nginx/utilities/https_vhosts.sh >> /dev/null 2>&1
```
Перезапустите планировщик задач:
```
service crond restart
```
Завершите выполнение задач Engintron, которые могут остаться работающими:
```
killall -9 https_vhosts.sh
```
В начало файла /etc/nginx/nginx.conf добавьте строку загрузки модуля BotGuard для Nginx:
```
include /usr/share/nginx/modules/mod-botguard.conf;
```
и перезапустите веб-сервер Nginx:
```
service nginx restart
```
Запустите сервис для синхронизации файлов конфигурации Apache и Nginx:
```
service engintron-sync start
```

Настройка параметров работы модуля BotGuard для WHM / CPanel

Сразу после установки модуль будет отключен. Перед включением модуля необходимо выполнить его предварительную настройку. Для настройки модуля откройте веб-панель управления WHM и перейдите в раздел Home » Plugins » BotGuard Bot Management:

Далее, в окне параметров модуля заполните поля формы BotGuard Integration Settings и нажмите кнопку Apply:

Вы можете запросить и получить Ключ API («API Key») в разделе для партнеров на нашем сайте botguard.net. В качестве адресов основного («Primary Server») и дополнительного («Secondary Server») серверов следует указать адреса выделенных узлов BotGuard из числа зарезервированных за вами.

После установки модуля у каждого пользователя этого сервера WHM в веб-панели управления сайтами CPanel появится возможность настройки защиты сайтов и соответствующий раздел меню:

При выборе пункта BotGuard Bot Management пользователь CPanel имеет возможность включить или отключить защиту для своих сайтов:

После включения защиты, пользователь CPanel может настроить правила управления ботами:

Руководство по интеграции

Вы являетесь хостинг провайдером и хотите предоставлять сервис BotGuard своим клиентам?

Вы используете выделенный сервер, виртуальный сервер или разделяемый хостинг?

Как проверить?

Какой веб-сервер используется?

Как проверить?

На сайте используется система управления содержанием WordPress?

Как проверить?

Веб-сайт разработан с помощью языка программирования PHP?

Как проверить?

Требуется индивидуальное решение?

Инструкции по интеграции с веб-сервером Apache

Debian, Ubuntu

RHEL, CentOS

Настройка параметров работы модуля

Инструкции по интеграции с веб-сервером Nginx

Debian, Ubuntu

RHEL, CentOS

Настройка параметров работы модуля

Инструкции по интеграции с веб-сервером Nginx (альтернативный способ)

Инструкции по интеграции с системой управления содержанием (CMS) WordPress

Прочие PHP приложения

Интеграция с WHM / CPanel (панель управления сайтами)

Поддержка Nginx в WHM / CPanel

Настройка параметров работы модуля BotGuard для WHM / CPanel