Перейти к содержанию

Установка динамически подключаемого модуля NGINX

Коммерческий NGINX Plus и бесплатный NGINX

В данном разделе приведены инструкции по установке WAF‑ноды как динамически подключаемого модуля к бесплатной версии NGINX stable.
Модуль Валарм для NGINX не работает с версией NGINX mainline.

Если вы используете коммерческую версию NGINX Plus, вам понадобятся другие инструкции. Обратитесь к разделу Установка с использованием NGINX Plus.

Если в вашей системе уже установлен NGINX, то вы можете подключить динамический модуль Валарм.

Официальная сборка NGINX и специальная сборка NGINX

Валарм совместим со сборкой NGINX, установленной из официальных репозиториев.

Если вы собираете NGINX самостоятельно, то динамический модуль из репозитория Валарм может не подойти и не загрузиться. Для пересборки динамического модуля обратитесь в техническую поддержку. При обращении предоставьте результаты выполнения команд:

  • Версия ядра Linux: uname -a

  • Версия операционной системы Linux: cat /etc/*release

  • Версия установленного NGINX:

  • официальная сборка NGINX: /usr/sbin/nginx -V

  • специальная сборка NGINX: <путь к nginx>/nginx -V

  • Сигнатура совместимости:

  • официальная сборка NGINX: egrep -ao '.,.,.,[01]{33}' /usr/sbin/nginx

  • специальная сборка NGINX: egrep -ao '.,.,.,[01]{33}' <путь к nginx>/nginx

  • Пользователь (и его группа), от имени которого запускаются worker-процессы NGINX: grep -w 'user' <путь к конфигурационным файлам NGINX/nginx.conf>

Варианты установки

Обработка запросов в WAF‑ноде делится на две фазы:

  • Первичная обработка в модуле NGINX-Wallarm;

  • Постаналитика. Статистический анализ обработанных запросов.

Первичная обработка не требует большого объема оперативной памяти, поэтому может быть размещена на текущих frontend-серверах без изменения требований к ним.

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

Установка постаналитики на отдельный сервер

Если вы планируете установить модуль постаналитики на отдельный сервер, необходимо сначала установить его. Подробнее в Установка постаналитики на отдельный сервер.

Для установки динамически подключаемого модуля для NGINX вам потребуется
выполнить следующие действия:

  1. Установить NGINX.

  2. Добавить репозитории Валарм, из которых вы загрузите пакеты.

  3. Установить пакеты Валарм.

  4. Настроить модуль постаналитики.

  5. Подключить модуль Валарм.

  6. Настроить WAF‑ноду для использования прокси‑сервера.

  7. Подключить WAF‑ноду к облаку Валарм.

  8. Настроить адреса сервера постаналитики.

  9. Настроить режим фильтрации.

  10. Настроить логирование.

  11. Перезапустить NGINX.

Необходимые условия

  • Перед установкой отключите или настройте SELinux, если он установлен в операционной системе.
  • Убедитесь, что вы выполняете все команды, приведенные ниже, от имени суперпользователя (например, root).

1. Установите NGINX

Версия NGINX stable

Обратите внимание, что необходимо установить версию NGINX stable, версия mainline несовместима с модулем Валарм для NGINX.

Вы можете:

  • Использовать официальную сборку.

    Инструкции по установке NGINX stable для поддерживаемых Валарм дистрибутивов приведены ниже:

    apt install curl gnupg2 ca-certificates lsb-release
    echo "deb http://nginx.org/packages/debian `lsb_release -cs` nginx" | tee /etc/apt/sources.list.d/nginx.list
    curl -fsSL https://nginx.org/keys/nginx_signing.key | apt-key add -
    apt update
    apt install nginx
    
    apt install curl gnupg2 ca-certificates lsb-release
    echo "deb http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" | tee /etc/apt/sources.list.d/nginx.list
    curl -fsSL https://nginx.org/keys/nginx_signing.key | apt-key add -
    apt update
    apt install nginx
    
    echo '[nginx-stable] name=nginx stable repo baseurl=http://nginx.org/packages/centos/$releasever/$basearch/ gpgcheck=1 enabled=1 gpgkey=https://nginx.org/keys/nginx_signing.key module_hotfixes=true' > /etc/yum.repos.d/nginx.repo
    yum install nginx
    
  • Собрать самостоятельно с аналогичными опциями компиляции. Для этого используйте исходный код из ветки stable репозитория NGINX.

Дополнительная информация доступна в официальной инструкции по установке NGINX.

Установка на Amazon Linux 2

Для установки NGINX на Amazon Linux 2 используйте инструкцию для CentOS 7.

2. Добавьте репозитории Валарм

Установка и обновление модуля Валарм происходит из репозиториев Валарм.

В зависимости от вашей операционной системы, выполните одну из следующих команд:

apt-get install dirmngr
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node jessie/2.14/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-get install dirmngr
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node stretch/2.14/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-get install dirmngr
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node buster/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node trusty/2.14/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node xenial/2.14/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-key adv --keyserver keys.gnupg.net --recv-keys 72B865FD
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node bionic/2.14/' >/etc/apt/sources.list.d/wallarm.list"
apt-get update
yum install --enablerepo=extras -y epel-release centos-release-SCL
rpm -i https://repo.wallarm.com/centos/wallarm-node/6/2.14/x86_64/Packages/wallarm-node-repo-1-5.el6.noarch.rpm
yum install -y epel-release
rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm
yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm

Доступ к репозиториям

У системы должна быть возможность обратиться к https://repo.wallarm.com для загрузки пакетов. Убедитесь, что доступ не ограничен настройками файервола.

Ошибка с ключом CentOS GPG

Если у вас уже добавлен репозиторий Валарм и вы получили ошибку, связанную с ключами CentOS GPG, следуйте инструкциям:

  1. Удалите предыдущий добавленный репозиторий, используя команду yum remove wallarm‑node‑repo.
  2. Добавьте репозиторий, используя команду с подходящей вкладки выше.

Возможные сообщения об ошибках:

  • http://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/repodata/repomd.xml: [Errno -1] repomd.xml signature could not be verified for wallarm-node_2.14
  • One of the configured repositories failed (Wallarm Node for CentOS 7 - 2.14), and yum doesn't have enough cached data to continue.

3. Установите пакеты Валарм

Установите обработку запросов и постаналитику на один сервер

Для выполнения обработки запросов и постаналитики на одном сервере необходимо установить следующие пакеты:

  • модуль Валарм;

  • располагающееся в памяти хранилище Tarantool;

  • модуль постаналитики.

Для установки требуемых пакетов выполните следующую команду:

apt-get install --no-install-recommends wallarm-node nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node nginx-module-wallarm
yum install wallarm-node nginx-module-wallarm
yum install wallarm-node nginx-module-wallarm
yum install wallarm-node nginx-module-wallarm

Установите только обработку запросов на сервер

Для выполнения только обработки запросов на сервере необходимо
установить только модуль Валарм.

Для установки требуемых пакетов выполните следующую команду:

apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
apt-get install --no-install-recommends wallarm-node-nginx nginx-module-wallarm
yum install wallarm-node-nginx nginx-module-wallarm
yum install wallarm-node-nginx nginx-module-wallarm
yum install wallarm-node-nginx nginx-module-wallarm

4. Настройте модуль постаналитики

Info

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

Модуль постаналитики использует находящееся в памяти хранилище Tarantool. База данных Tarantool используется для хранения в локальном буфере копии трафика, который обрабатывает WAF‑нода, в том числе заголовки запросов и ответов, тело запросов. Тело ответа не записывается в базу данных.

Рекомендуемое количество памяти для Tarantool — 75% от общей памяти сервера. Чтобы оценить требуемое количество памяти более точно используется следующая формула:

Скорость обработки запросов в байтах в минуту * 15 * 2

Для оценки используется данная формула, так как для эффективной работы WAF‑ноды необходимо хранить данные не менее чем за 15 минут обработки запросов с учетом двойных издержек на сериализацию данных.

Например, если WAF‑нода на пике обрабатывает запросы со скоростью 50 Мбит/сек, для Tarantool требуется выделить следующее количество памяти:

50 Мбит/сек / 8 (бит в байте) * 60 (секунд в минуте) * 15 * 2 = 11,250,000,000 байт (или ~ 10.4 Гбит)

Настройка памяти для Tarantool выполняется в файле /etc/default/wallarm-tarantool > атрибут SLAB_ALLOC_ARENA. Чтобы указать количество памяти:

  1. Откройте конфигурационный файл Tarantool:
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
  1. Укажите размер памяти в атрибуте SLAB_ALLOC_ARENA. Например:
SLAB_ALLOC_ARENA=10.4
  1. Перезапустите Tarantool:
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool

Чтобы получить количество времени, на протяжении которого Tarantool может хранить данные о трафике с текущим уровнем нагрузки на WAF‑ноду, вы можете использовать метрику wallarm-tarantool/gauge-timeframe_size.

Более подробная информация о выделении ресурсов доступна по ссылке.

5. Подключите модуль Валарм

Откройте файл /etc/nginx/nginx.conf.

Проверьте, что в файле есть строка include /etc/nginx/conf.d/*. Если такой строки нет, добавьте ее.

Добавьте следующую директиву сразу под директивой worker_processes:

load_module modules/ngx_http_wallarm_module.so;

Пример файла с добавленной директивой:

user  nginx;
worker_processes  auto;
load_module modules/ngx_http_wallarm_module.so;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

Скопируйте конфигурационные файлы для настройки системы:

cp /usr/share/doc/nginx-module-wallarm/examples/*.conf /etc/nginx/conf.d/

6. Настройте WAF‑ноду для использования прокси‑сервера

Info

Данный этап настройки предназначен для пользователей, использующих свой прокси‑сервер для работы защищаемых веб‑приложений.

Если Вы не используете прокси‑сервер, пропустите этот этап настройки.

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

Добавьте в файл /etc/environment новые значения переменных окружения:

  • https_proxy — прокси для протокола HTTPS;

  • http_proxy — прокси для протокола HTTP;

  • no_proxy — ресурсы, для запросов к которым необходимо отключить проксирование.

Присвойте переменным https_proxy и http_proxy строки вида <scheme>://<proxy_user>:<proxy_pass>@<host>:<port>, где:

  • <scheme> — используемый протокол (должен совпадать с протоколом, для которого настраивается прокси в текущей переменной окружения);

  • <proxy_user> — имя пользователя для авторизации на прокси‑сервере;

  • <proxy_pass> — пароль для авторизации на прокси‑сервере;

  • <host> — хост используемого прокси‑сервера;

  • <port> — порт используемого прокси‑сервера.

Присвойте переменной no_proxy значение в виде массива IP‑адресов и/или доменов, к которым нужно обращаться без использования прокси: "<res_1>, <res_2>, <res_3>, <res_4>, ...", где <res_1>, <res_2>, <res_3> и <res_4> — IP‑адреса и/или домены.

Ресурсы, к которым нужно обращаться без использования прокси

Для корректной работы системы в список ресурсов, к которым нужно обращаться без прокси, необходимо добавить следующие IP‑адреса и домен: 127.0.0.1, 127.0.0.8, 127.0.0.9 и localhost.

IP‑адреса 127.0.0.8 и 127.0.0.9 используются для работы WAF‑ноды Валарм.

Пример корректного содержимого файла /etc/environment ниже демонстрирует следующую конфигурацию:

  • HTTPS‑ и HTTP‑запросы проксируются на хост 1.2.3.4 с портом 1234, используя для авторизации на прокси‑сервере имя пользователя admin и пароль 01234.

  • для запросов к 127.0.0.1, 127.0.0.8, 127.0.0.9 и localhost проксирование отключено.

https_proxy=http://admin:01234@1.2.3.4:1234
http_proxy=http://admin:01234@1.2.3.4:1234
no_proxy="127.0.0.1, 127.0.0.8, 127.0.0.9, localhost"

7. Подключите WAF‑ноду к облаку Валарм

Доступ к API

Перед подключением в облаку Валарм убедитесь, что виртуальная машина с WAF‑нодой имеет доступ к:

  • https://api.wallarm.com:444 для работы с EU‑облаком
  • https://api.wallarm.ru:444 для работы с RU‑облаком

В случае проблем убедитесь, что доступ не ограничен файерволом.

В процессе работы WAF‑нода взаимодействует с облаком Валарм. Чтобы подключить WAF‑ноду к облаку, выполните следующие действия:

  1. Убедитесь, что роль вашего пользователя в Личном кабинете Валарм — Администратор и для пользователя отключена двухэтапная аутентификация.

    Для этого перейдите к списку пользователей в RU‑облаке или EU‑облаке и проверьте столбцы Роль и Auth:

    Список пользователей в консоли Валарм

  2. В системе с установленной WAF‑нодой запустите скрипт addnode:

    /usr/share/wallarm-common/addnode
    
    /usr/share/wallarm-common/addnode -H api.wallarm.ru
    

    При необходимости укажите имя создаваемой ноды, используя опцию ‑n <имя ноды>.

  3. Введите email и пароль от вашего аккаунта Валарм.

8. Настройте адреса сервера постаналитики

Info

  • Пропустите данный шаг, если постаналитика и WAF‑нода установлены на один сервер.
  • Выполните данный шаг, если постаналитика и WAF‑нода установлены на разные серверы.

Добавьте в /etc/nginx/conf.d/wallarm.conf адреса серверов постаналитики:

     upstream wallarm_tarantool {
         server <ip1>:3313 max_fails=0 fail_timeout=0 max_conns=1;
         server <ip2>:3313 max_fails=0 fail_timeout=0 max_conns=1;

         keepalive 2;
    }

    ...

    wallarm_tarantool_upstream wallarm_tarantool;

Необходимые условия

Для параметров max_conns и keepalive необходимо соблюдать следующие условия:

  • Значение keepalive должно быть не меньше, чем количество серверов tarantool.
  • Значение max_conns должно быть указано для каждого сервера, чтобы предотвратить создание лишних соединений.

9. Настройте режим фильтрации

Для обработки HTTP‑запросов Валарм использует веб‑ и прокси‑сервер NGINX
с дополнительными модулями анализа трафика.

Для настройки правил проксирования и фильтрации необходимо отредактировать файлы конфигурации NGINX и WAF‑ноды Валарм, которые содержатся в директории etc/nginx/conf.d:

  • Файл default.conf содержит настройки NGINX;

  • Файл wallarm.conf содержит глобальные настройки WAF‑ноды Валарм;

  • Файл wallarm‑status.conf содержит настройки мониторинга работы Валарм.

Вы можете создавать свои файлы конфигурации для настройки работы NGINX и Валарм. Для каждой группы доменов, которые должны обрабатываться однотипно, принято создавать отдельный файл конфигурации, в котором присутствует блок server.

Подробную информацию о работе с конфигурационными файлами NGINX вы можете найти в официальной документации NGINX.

Логика работы WAF‑ноды Валарм настраивается при помощи директив Валарм. Список доступных директив Валарм доступен на странице «Тонкая настройка».

Пример файла конфигурации

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

  • обработка HTTPS‑трафика не настроена;

  • запросы осуществляются к двум доменам: example.com и www.example.com;

  • все запросы нужно передавать на сервер 10.80.0.5;

  • все входящие запросы меньше 1 МБ (значение по умолчанию);

  • нет запросов, которые обрабатываются дольше 60 секунд (значение по умолчанию);

  • система должна работать в режиме мониторинга;

  • клиенты обращаются к WAF‑ноде напрямую, не через промежуточный
    HTTP‑балансировщик.

Создание файла конфигурации

Вы можете создать свой файл конфигурации NGINX (например, example.com.conf), или модифицировать файл конфигурации NGINX, который используется по умолчанию (default.conf).

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

Файл конфигурации в этом случае будет выглядеть следующим образом:

    server {
      listen 80;
      listen [::]:80 ipv6only=on;

      # the domains for which traffic is processed
      server_name example.com; 
      server_name www.example.com;

      # turn on the monitoring mode of traffic processing
      wallarm_mode monitoring; 

      location / {
        # setting the address for request forwarding
        proxy_pass http://10.80.0.5; 
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      }
    }

10. Настройте логирование

Настройте логирование переменных WAF‑ноды с помощью NGINX. Это позволит провести быструю диагностику состояния WAF‑ноды в случае необходимости, основываясь на содержимом лог‑файла NGINX.

11. Перезапустите NGINX

Предоставление пользователю прав root

Если вы запускаете NGINX под пользователем, который не имеет прав root, добавьте пользователя в группу wallarm при помощи следующей команды:

usermod -aG wallarm <user_name>

где <user_name> — это имя пользователя, который не имеет прав root.

systemctl restart nginx
systemctl restart nginx
systemctl restart nginx
service nginx restart
service nginx restart
service nginx restart
service nginx restart
systemctl restart nginx
systemctl restart nginx

Установка завершена

На этом установка завершена.

Проверьте, что WAF‑нода работает и пропускает через себя трафик. Подробнее в Проверка работоспособности WAF‑ноды.

Настройки по умолчанию

Только что установленная WAF‑нода будет находиться в режиме блокировки (см. описание директивы wallarm_mode) в соответствии с настройками по умолчанию.

Это может привести к неработоспособности сканера Валарм. Если вы используете сканер, выполните дополнительные действия, чтобы он работал.

Дополнительные настройки

После установки WAF‑нода может потребовать дополнительной настройки.

Далее приводится несколько типовых настроек, которые вы можете выполнить, если это требуется.

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

Настройка отображения реального IP‑адреса клиента

Если WAF‑нода развернута за прокси‑сервером или балансировщиком нагрузки, то при такой схеме развертывания без дополнительной настройки адрес источника на WAF‑ноде может совпадать с одним из IP‑адресов прокси‑сервера или балансировщика нагрузки, а не с IP‑адресом клиента.

В этом случае, если вы хотите, чтобы на WAF‑ноду передавался IP‑адрес клиента в качестве адреса источника, то требуется дополнительная настройка прокси‑сервера или балансировщика.

Добавление адресов сканера Валарм в белый список

Сканер Валарм позволяет сканировать ресурсы вашей компании на уязвимости. Сканирование происходит с IP‑адресов из этих списков:

Если вы используете сканер Валарм, то для его корректной работы нужно настроить на средствах защиты вашего периметра (файерволы, системы предотвращения вторжений и т. д.) белые списки, содержащие в себе IP‑адреса сканера.

Например, WAF‑нода Валарм с настройками по умолчанию находится в режиме блокировки, что приводит к невозможности сканирования защищаемых нодой ресурсов с помощью сканера.

Чтобы сканировать такие ресурсы, добавьте адреса сканера Валарм в белый список этой WAF‑ноды.

Ограничение времени обработки единичного запроса

Используйте директиву Валарм wallarm_process_time_limit, чтобы задать ограничение времени обработки единичного запроса WAF‑нодой.

Если запрос обрабатывается за большее время, чем указано в директиве, то в лог‑файл заносится информация об ошибке, а запрос помечается как атака overlimit_res.

Ограничение времени ожидания ответа сервера

Используйте директиву NGINX proxy_read_timeout, чтобы задать таймаут чтения ответа проксированного сервера.

Если за это время сервер ничего не передаст, то соединение будет закрыто.

Ограничение максимального размера запроса

Используйте директиву NGINX client_max_body_size, чтобы задать ограничение на максимальный размер тела запроса клиента.

В случае превышения этого ограничения NGINX вернет клиенту ответ с кодом 413 (Payload Too Large, также известный как Request Entity Too Large).