1. Виртуальная машина

Образ подходит для VirtualBox, VMWare ESXi 6.5 и выше.

Скачать OVA-файл.
Импортировать OVA:
- VMWare ESXi: Virtual Machines → Create/Register VM → Deploy a virtual machine from an OVF or OVA file
- VirtualBox: File → Import Appliance
Выбрать сети:
- Management network — сеть управления;
- External network — внешняя сеть с клиентами и атакующими;
- Internal network — внутренняя сеть с защищаемыми ресурсами.
После первого запуска и при обновлении (учетная запись: root:mitigator):
- Для VirtualBox: исполнить /usr/local/bin/virtual-box_prepare.sh, либо поменять адреса сетевых портов вручную (см. ниже).
- При обновлении:
  - перейти в рабочий каталог:
    cd /srv/mitigator
  - скачать актуальный Compose-файл:
    wget https://docs.mitigator.ru/dist/docker-compose.yml
  - скачать базовый файл переменных:
    wget https://docs.mitigator.ru/dist/env -O /srv/mitigator/.env
- docker login docker.mitigator.ru
- systemctl restart mitigator

Подробней о назначении файлов можно почитать в инструкции по ручной установке.

**Смена сетевых портов для VirtualBox**\ \ Гипервизоры дают разные PCI-адреса сетевым портам. Конфигурация в OVA рассчитана на VMWare, а для VirtualBox нужно изменить её:

for e in s/0b:00.0/00:09.0/ s/13:00.0/00:0a.0/; do
    for f in /etc/systemd/system/mitigator.service.d/nics.conf /srv/mitigator/data-plane.conf; do
        sed -e ${e} -i ${f}
    done
done

systemctl daemon-reload

2. Ansible

Playbook работает для Debian 9 и 10, Ubuntu 16.04+, CentOS 7.2. Необходим доступ от целевой машины к репозитариям дистрибутива

1. Установить Ansible (пример для Debian/Ubuntu):

sudo apt-get --yes install ansible tar wget

2. Установить Docker и Docker-Compose:

Следуя официальной документации по установке для вашей ОС:

Если в системе отсутствует /etc/docker/daemon.json, будет установлен следующий:

{
    "log-driver": "json-file",
    "log-opts": {
      "max-size": "50m",
      "max-file": "2"
    }
}

Существующий файл изменен не будет, в этом случае следует совместить конфигурации вручную.

3. Скачать и распаковать необходимые файлы:

wget https://docs.mitigator.ru/ansible/mitigator.tar -O- | tar -x
wget https://docs.mitigator.ru/ansible/config.yml -O mitigator/config.yml

4. Отредактировать mitigator/config.yml (параметры по умолчанию годятся для минимальной конфигурации):

---
mitigator_arch: "nehalem"
mitigator_nic_driver: uio_pci_generic
mitigator_nics:
- pci_address: "0000:0b:00.0"
  lcore: 1
- pci_address: "0000:13:00.0"
  lcore: 2
mitigator_cpus: "3"
mitigator_nr_addrs: 131072
mitigator_nr_conns: 1048576
mitigator_hugepage_size: "2M"
mitigator_hugepage_nr: 1536
mitigator_nr_policies: 100

#mitigator_version: latest

#mitigator_registry_user: guest
#mitigator_registry_pass: mitigator
#mitigator_pull_images: y

#mitigator_http_proxy: ""
#mitigator_https_proxy: ""
#mitigator_no_proxy: ""

#docker_http_proxy: ""
#docker_https_proxy: ""
#docker_no_proxy: ""

mitigator_arch: микроархитектура процессора, для которой будет загружена оптимизированная версия обработчика пакетов: nehalem, sandybridge или haswell (указания по выбору).
mitigator_nic_driver: драйвер сетевой карты для DPDK (подробнее о выборе).
Настройки обработчика пакетов:
- mitigator_nics: сетевые порты с указанием PCI-адресов и ядер процессора. Подразумевается, что они перечислены в порядке ext0, int0, ext1, int1 и т. д. Портов может быть нечетное количество и даже один.
- mitigator_cpus: список ядер, применяющих контрмеры (workers) (в формате python-/yaml-/json- списка строк, например: ["3-7", "12-19", "21-23"]).
- mitigator_nr_addrs, mitigator_nr_conns: размеры таблиц проверенных адресов и отслеживаемых соединений.
Настройки больших страниц:
- mitigator_hugepage_size: размер страницы (2M или 1G);
- mitigator_hugepage_nr: количество страниц.
mitigator_nr_policies: максимальное количество политик защиты.
Можно указать версию Mitigator´а (latest по умолчанию).
При первом запуске и при mitigator_pull_images: y будет выполнена загрузка образов Mitigator´а, для чего нужно задать логин и пароль: mitigator_registry_user и mitigator_registry_pass.
Можно настроить прокси для Docker´а и компонент Mitigator´а.

5. Развернуть Mitigator на целевую машину mitigator.local, куда есть доступ по SSH:

ansible-playbook --become --ask-become-pass \
    -i mitigator.local, mitigator/mitigator.yml

Запятая после имени хоста — не опечатка. Если имя пользователя SSH отличается от локального, например, login, добавляется параметр -u login.

--become и --ask-become-pass используются для повышения привилегий, когда подключение осуществляется не напрямую через пользователя root (необходимо для выполнения части задач в процессе инсталяции).

В конце установки машина перезагрузится.

Playbook безопасно исполнять повторно в случае проблем.

Дополнение

1. Задания в роли ансибла разделены на 4 «тега»: checks, system, hugepages, mitigator.

Задания под тегом, соответственно, предназначены для проверки конфигурации, настройки системы, настройки hugepages и настройки непосредственно Mitigator´а. При необходимости перезапустить роль и перенастроить установку только частично, можно запустить playbook с необходимым набором тегов, например:

ansible-playbook --become --ask-become-pass \
    --tags "system,hugepages" \
    -i mitigator.local, mitigator/mitigator.yml

2. Конфигурацию GRUB2 под UEFI на RHEL/CentOS необходимо дополнительно перегенерировать вручную:

grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg

Для CentOS redhat заменить на centos

3. Вручную

Установка вручную

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

Подготовка системы

Нужно обеспечить:

загрузку подходящего драйвера сетевой карты;
выделение больших страниц памяти (hugepages);
Docker и Docker Compose.

Настройка и запуск Mitigator

Разместить compose-файл и задать глобальные параметры системы.
Настроить использование сетевых портов и ядер ЦП обработчиком пакетов.
Автоматизировать привязку драйверов к сетевым портам и запуск Mitigator´а.
Скачать Docker-образы Mitigator´а.

4. Выбор версии

Новейшая: `v19.12.1`

Как выбрать версию по задаче?

Оценить последнюю стабильную версию

Выбор: latest или v19.12

latest означает последнюю мажорную версию со всеми исправлениями.

Мажорная версия соответствует последней минорной в своих рамках, то есть, если последняя версия v12.34.5, v12.34 тождественна ей.

Жестко зафиксировать версию

Выбор: v19.12.1

Например, если требуется проверить версию в тестовой среде, а затем развернуть точно такую же на production. Минорные версии не меняются. Первая мажорная версия обозначается нулем, например, v12.34.0.

Попробовать самые свежие функции

Выбор: nightly или develop

Ночные сборки публикуются в 06:00 MSK без проверки, без гарантий и без поддержки. Не рекомендуются для production. Ночные сборки за последний месяц доступны как nightly-20190222 и т. д.

Версия develop публикуется в особых случаях и обновляется без предупреждения. В отличие от nightly, она проверяется перед публикацией.

5. Обслуживание

Резервное копирование

Резервная копия (бэкап) хранит настройки, сделанные через web-интерфейс и API. В нее не входят данные графиков, по которым также строятся отчеты.

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

Создание резервной копии

При работающем Mitigator´е:

docker-compose exec postgres sh -c 'backup > /tmp/backup.sql'
docker cp mitigator_postgres_1:/tmp/backup.sql .

При остановленном Mitigator´е:

docker-compose up -d postgres
docker-compose exec postgres sh -c 'backup > /tmp/backup.sql'
docker cp mitigator_postgres_1:/tmp/backup.sql .
docker-compose down postgres

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

tail backup.sql

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

Остановить Mitigator:
```
docker-compose down
```
Удалить существующую базу:
```
docker volume rm mitigator_postgres
```

Запустить Postgres:

docker-compose up -d postgres && docker-compose logs -f postgres

Дождаться сообщения database system is ready to accept connections, нажать Ctrl+C.

Перенести бэкап в контейнер и восстановить данные:

docker cp backup.sql mitigator_postgres_1:/tmp
docker-compose exec postgres sh -c 'psql mitigator </tmp/backup.sql >/tmp/restore.log'

Запустить Mitigator:
```
docker-compose up -d
```

Если на этапе восстановления появились ошибки, технической поддержке будет нужен их текст и файл restore.log, который можно забрать из контейнера так:

docker cp mitigator_postgres_1:/tmp/restore.log .

Обновление

Перед обновлением настоятельно рекомендуется сделать резервную копию.

Записать в файл .env строку с версией (если файла нет, создать его):
```
VERSION=v19.12
```
Загрузить актуальный Compose-файл:
```
wget https://docs.mitigator.ru/dist/docker-compose.yml
```
Если в нем были сделаны правки для адаптеров Mellanox, воспроизвести их в новой версии файла.
Совершить вход в хранилище образов со своими учетными данными:
```
docker login docker.mitigator.ru
```
Скачать образы:
```
docker-compose pull
```
Перезапустить все компоненты Mitigator´а:
```
systemctl restart mitigator
```

Смена конфигурации

Применить правки любых файлов конфигурации в /srv/mitigator:

systemctl reload mitigator

При этом могут быть перезапущены релевантные компоненты Mitigator´а.

После смены сетевых портов, то есть после редактирования /etc/systemd/system/mitigator.service.d/nics.conf, необходимо:

systemctl daemon-reload
systemctl restart mitigator

При этом Mitigator будет полностью выключен и заново включен.

Скрипт получения и восстановления конфигурации Mitigator´а

Доступен скрипт MBackup для получения в формате JSON-файла основных настроек системы через API, а также для восстановления из полученного файла (только на чистую систему).

Такой файл не содержит настроек пользователей, сети, журналов и не может в полной мере заменить резерное бекапирование.

Возможные сценарии использования:

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

6. Расширенные настройки

Работа через прокси

Docker

Если доступ к https://docker.mitigator.ru ведется через прокси, необходимо настроить Docker.

В системах под управлением systemd предлагается:

Создать drop-in к службе Docker´а с указанием прокси в окружении (детали подключения к прокси заменить на актуальные):

mkdir -p /etc/systemd/system/docker.service.d
cat >/etc/systemd/system/docker.service.d/proxy.conf <<END
[Service]
Environment=HTTP_PROXY=http://user:password@proxy.local:1234
Environment=HTTPS_PROXY=http://user:password@proxy.local:1234
Environment=NO_PROXY=docker.local
END

Добавить сертификат прокси в доверенные для Docker´а (/path/to/proxy.crt заменить на путь к сертификату прокси):
```
mkdir -p /etc/docker/certs.d/docker.mitigator.ru
cp /path/to/proxy.crt /etc/docker/certs.d/docker.mitigator.ru
```
Обновить описание службы Docker и перезапустить её:
```
systemctl daemon-reload
systemctl restart docker
```

Mitigator

Если Mitigator будет сообщаться с сервером лицензий (ls.mitigator.ru), почтовым сервером и службой «Весточка» через прокси, нужно указать переменные окружения. Для этого нужно создать файл docker-compose.override.yml с таким содержимым:

version: "2.1"

services:
    backend:
        environment:
            HTTP_PROXY: "http://user:password@proxy.local:3128"
            HTTPS_PROXY: "http://user:password@proxy.local:3128"

При необходимости задать также NO_PROXY (адреса, к которым нужно обращаться без прокси), требуется включать в нее .mitigator и localhost:

NO_PROXY: "<новые серверы>,.mitigator,localhost"

После этого нужно перезапустить службу бэкенда:

docker-compose up -d backend

Собственный сертификат TLS

Для замены самоподписанного сертификата cert.crt с ключом cert.key на собственный, необходимо смонтировать сертификат и ключ через /srv/mitigator/docker-compose.override.yml:

version: "2.1"
services:
    nginx:
        volumes:
        - example.com.crt:/etc/nginx/cert.crt:ro
        - example.com.key:/etc/nginx/cert.key:ro

После этого нужно перезапустить службу Nginx:

docker-compose up -d nginx

7. Troubleshooting

Не загружаются драйверы (modprobe)

Симптомы:

при загрузке модуля:

modprobe: FATAL: Module igb_uio not found in directory /lib/modules/4.9.0-6-amd64

при установке пакета:

Module build for kernel 4.9.0-6-amd64 was skipped since the
kernel headers for this kernel does not seem to be installed.

Необходимо установить пакет linux-headers-amd64 (Debian) и убедиться, что загружена версия ядра, соответствующая версии этого пакета, после чего выполнить:

dkms autoinstall

Не работает docker и docker-compose

По умолчанию эти команды работают только для пользователей группы docker и для root. Это стандартная мера безопасности Docker. Решение:

sudo usermod -aG docker $USER
newgrp docker

Обработчик пакетов недоступен

Такое сообщение появляется в web-интерфейсе, если обработчик пакетов не запустился или остановился. Диагностика (из /srv/mitigator):

docker-compose logs data-plane

Ниже приводятся некоторые типовые проблемы и характерные сообщения.

`EAL: Cannot get hugepage information.`

Сообщение:

EAL: No free hugepages reported in hugepages-2048kB
EAL: No free hugepages reported in hugepages-1048576kB
EAL: FATAL: Cannot get hugepage information.
EAL: Cannot get hugepage information.
EAL: Error exiting with code: 1
  Cause: DPDK init error: 1

Причина: не выделены или полностью заняты hugepages.

Нужно проверить наличие свободных hugepages и убедиться, что значения HugePages_Total и Hugepagesize совпадают с настроенными, а HugePages_Free равно HugePages_Total (или отличается не более, чем на несколько страниц):

grep Huge /proc/meminfo

`no port found with PCI address BB:DD.F`

Сообщение:

/data-plane/config.click:12: While configuring 'ext0::PortDev':
  no port found with PCI address 04:00.0

Нужно убедиться, что адрес устройства 04:00.0 соответствует действительности и что устройство привязано к драйверу для DPDK точно так же, как при подготовке системы.

Аварийное завершение

При просмотре логов docker-compose logs data-plane сообщение:

Segmentation fault (core dumped)

Чтобы незамедлительно восстановить работу, можно дать команду:

docker-compose up -d data-plane

Далее рекомендуется связаться с разработчиками с целью точной диагностики и исправления, для чего им желательно иметь:

Описание ситуации, в которой произошла проблема (действий с Mitigator´ом, входящего трафика).
Описание аппаратной конфигурации сервера:
- модель ЦП и сетевых карт;
- размер памяти и конфигурация hugepages;
- версия ядра Linux, используемые драйвера для сетевых карт и их версии.
Файл /srv/mitigator/data-plane.conf.
Core dump (слепок памяти процесса), который по умолчанию сохраняется в /var/lib/docker/volumes/mitigator_coredumps/_data/core. Его размер — гигабайты, но он обычно хорошо сжимается.

В некоторых дистрибутивах (например, Ubuntu) файл core не появляется, потому что обработка сбоев настроена иначе. Проверить настройку можно так:
```
cat /proc/sys/kernel/core_pattern
```
По умолчанию в Linux значение core. Если оно другое:
1. Запомнить исходное значение:
```
cat /proc/sys/kernel/core_pattern > /tmp/old_core_pattern
```
2. Заменить его на core:
```
echo core | sudo tee /proc/sys/kernel/core_pattern
```
3. Воспроизвести проблему, получить файл core по указанному выше пути.
4. Восстановить оригинальное значение:
```
cat /tmp/old_core_pattern | sudo tee /proc/sys/kernel/core_pattern
```

Установка BIFIT Mitigator

Системные требования

Поддержка

1. Виртуальная машина

2. Ansible

Дополнение

3. Вручную

Установка вручную

Подготовка системы

Настройка и запуск Mitigator

4. Выбор версии

Новейшая: `v19.12.1`

Как выбрать версию по задаче?

5. Обслуживание

Резервное копирование

Создание резервной копии

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

Обновление

Смена конфигурации

Скрипт получения и восстановления конфигурации Mitigator´а

6. Расширенные настройки

Работа через прокси

Docker

Mitigator

Собственный сертификат TLS

7. Troubleshooting

Не загружаются драйверы (modprobe)

Не работает docker и docker-compose

Обработчик пакетов недоступен

`EAL: Cannot get hugepage information.`

`no port found with PCI address BB:DD.F`

Аварийное завершение

Системные требования

Поддержка

1. Виртуальная машина

2. Ansible

Дополнение

3. Вручную

Установка вручную

Подготовка системы

Настройка и запуск Mitigator

4. Выбор версии

Новейшая: v19.12.1

Как выбрать версию по задаче?

5. Обслуживание

Резервное копирование

Создание резервной копии

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

Обновление

Смена конфигурации

Скрипт получения и восстановления конфигурации Mitigator´а

6. Расширенные настройки

Работа через прокси

Docker

Mitigator

Собственный сертификат TLS

7. Troubleshooting

Не загружаются драйверы (modprobe)

Не работает docker и docker-compose

Обработчик пакетов недоступен

EAL: Cannot get hugepage information.

no port found with PCI address BB:DD.F

Аварийное завершение

Новейшая: `v19.12.1`

`EAL: Cannot get hugepage information.`

`no port found with PCI address BB:DD.F`