Ansible

Playbook works for Debian 10+ and Ubuntu 20.04+. You need access to the distribution repositories from the target machine.

1. Install Ansible (example for Debian/Ubuntu):

apt install -y ansible tar wget
apt install -y ansible tar wget
dnf install -y ansible tar wget

2. Install Docker and Docker Compose:

Install Docker from the distributive repositories:

apt install -y docker.io
apt-get install -y docker-engine
dnf install -y docker-ce
Warning

Once installed, you need to start and enable Docker service:

systemctl enable --now docker

Install Docker Compose from the official repository and make the binary executable:

curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/bin/docker-compose
chmod +x /usr/bin/docker-compose
Warning

MITIGATOR is not guaranteed to work with Docker Compose v2.

Info

If https://docker.mitigator.ru is accessed through a proxy, you need to configure Docker.

If /etc/docker/daemon.json is not present on the system, this one will be installed: daemon.json.

The existing file will not be modified, in which case you must manually align the configurations.

3. Download and extract the necessary files:

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

4. Edit mitigator/config.yml (the default options are fine for minimal configuration):

---
mitigator_arch: "nehalem"
mitigator_nic_driver: vfio-pci
mitigator_nics:
- "0b:00.0"
- "13:00.0"
mitigator_hugepage_size: "2M"
mitigator_hugepage_nr: 1536
mitigator_nr_policies: 100

# https://docs.mitigator.ru/install/versions/#список-минорных-версий
mitigator_version: v23.06.6

mitigator_registry_user: guest
mitigator_registry_pass: mitigator
mitigator_pull_images: y

#mitigator_http_proxy: ""
#mitigator_https_proxy: ""
#mitigator_no_proxy: ""
  • mitigator_arch: CPU microarchitecture for which an optimized build of the packet processor will be loaded: nehalem or haswell (selection instructions).

  • mitigator_nic_driver: network card driver for DPDK (details on selection).

  • Packet processor settings:

    • mitigator_nics: network ports with PCI addresses and processor cores. They are assumed to be listed in the order ext0, int0, ext1, int1, etc. There can be an odd number of ports.
  • Huge Page Settings:

    • mitigator_hugepage_size: page size (2M or 1G);
    • mitigator_hugepage_nr: number of pages.
  • mitigator_nr_policies: the maximum number of protection policies.

  • You can specify version of MITIGATOR (latest by default).

  • At the first start and with mitigator_pull_images: y, the MITIGATOR images will be loaded, for which you need to set the login and password: mitigator_registry_user and mitigator_registry_pass.

  • You can set up a proxy for Docker and the MITIGATOR component.

5. Deploy MITIGATOR to a target machine mitigator.local that has SSH access:

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

The comma after the hostname is not a typo. If the SSH username is different from the local one, such as login, the -u login option is added.

--become and --ask-become-pass are used to elevate privileges when connection is established indirectly as the root user (required to perform part of the installation process).

At the end of the installation, the machine will reboot.

Playbook is safe to be re-executed in case of problems.

Addition

1. Tasks in the ansible role are divided into 4 «tags»: checks, system, hugepages, mitigator.

Tasks under the tag, respectively, are designed to check the configuration, configure the system, configure hugepages and configure the MITIGATOR itself. If you need to restart the role and reconfigure the installation only partially, you can run the playbook with the required set of tags, for example:

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

After installing and running configure system for its stable and safe operation.