Ansible

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

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

apt-get install ansible tar wget

2. Install Docker and Docker Compose:

Following the official installation documentation for your OS:

You should install Docker Compose v1. MITIGATOR is not guaranteed to work with Docker Compose v2.

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

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

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/v22.08/ansible/mitigator.tar -O- | tar -x
wget https://docs.mitigator.ru/v22.08/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

#mitigator_version: latest

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 as an ansible 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.