DOCUMENTATION.md

Documentation

MITIK-MGMT is the tool used to start and sync the experiments.
It contains scripts and playbooks that can be ran with Ansible, which uses SSH to control fleets of devices remotely (nodes).

Ansible is a radically simple IT automation engine that automates cloud provisioning, configuration management, application deployment, intra-service orchestration, and many other IT needs.

Installation

It requires installing ansible on your controlling computer (master):

sudo apt install ansible -y

Then clone the MITIK-MGMT repository and enter that folder :

git clone https://gitlab.inria.fr/mitik/measurement-management/mitik-mgmt
cd mitik-mgmt

Folders structure

mitik-mgmt
├── config # Configuration files for Ansible. Run commands from here.
├── docs # Documentation for MITIK-MGMT
├── figures # Illustrations for documentation
├── files # Files sent to nodes for configuration
├── playbooks # Instruction lists to be used with ansible commands
└── results # Output of remote devices

Enter the config folder. When running ansible from this folder, it will read configuration files that are in that current directory.

inventory file

==This step is mandatory==. Devices (nodes) you'll control (your inventory) are described inside the inventory file. [Ansible documentation]

In order yo fill your inventory, you'll need to know your nodes' username and IP address. A static IP for each node is highly recommended.

In the following example, we create a group of devices ss1 with two nodes inside. They are locally nicknamed s1 and s2, and they are reachable using their respective IP addresses. Username is set to be user for s1. Inline variables set here override variables defined globally.

[ss1]
s1 ansible_host=192.168.1.184
s2 ansible_host=192.168.1.231

---

The following adds members of the ss1 and ss2 groups to the sniffers group. Upon creating new groups, you might want to add them to the sniffers. This will let you run commands on all of its children at once.

[sniffers:children]
ss1
ss2

---

The following sets variables for all devices listed. More variables are available and described in the Ansible documentation. These values override those of ansible.cfg.

[all:vars]
ansible_connection=ssh
ansible_ssh_user=tribe
ansible_python_interpreter=/usr/bin/python3

---

ansible.cfg file

This is more or less the default configuration file, generated running ansible-config init --disabled > ansible.cfg. The following option has been changed :

inventory=./inventory ; Inline comment.

This sets the location of our inventory file, relative to the config folder.

Usage

Please run your playbooks from the config folder. You can make sure you're at the right place by typing pwd in your terminal. By default, all playbooks target the group sniffers. View the setup instructions if you're unsure what this means. You can run simple bash commands to nodes and view their results using:

ansible sniffers -m command -a "echo hello"

First connection and ssh access

If you didn't configure it before, your master device isn't authorized to connect to your remote device yet. For this to be solved, we're going to transfer the master's ssh key to the nodes so that it lets us in without password. ++This is a one-time process.++

Run the ssh_setup.yml playbook from the config folder :

ansible-playbook ../playbooks/ssh_setup.yml

Fill in the prompt for nodes' ssh passord and your master's admin password, then wait for completion. From there on, you won't need to provide authentication.

Testing the connection to your nodes

Once your nodes are configured, test connections using:

ansible all -m ping

Green means good, red is bad. :::spoiler Sample output

$ ansible all -m ping

rp4 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
s4 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
s2 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
s1 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
s3 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
s6 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
s5 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

:::

If you're still skeptical about it working, run

ansible-playbook ./test_echo.yml

which will make stuff appear in your nodes' tty1 (the one you see when you plug in a screen).

Setting up nodes using ansible

In order for your sniffers to work correctly, they need some configuration (installing some packages, the driver for the network adapters, the network interface names, etc).
If you've just flashed your sniffers with the official Lite image, ++do not skip this step++.
Detailed description of what this script does is to be found inside Nodes setup and configuration

Simply run the sniffer-setup playbook :

ansible-playbook ../playbooks/sniffer_setup.yml

This can be ran just to make sure things are set up properly.

Planning a sniffing session with cron and sens

Detailed description of what this script does is to be found inside Starting and Stopping mitik-sens.
Run the start_sens_sniffer.yml playbook:

ansible-playbook ../playbooks/start_sens_sniffer.yml

And fill in the parameters to pass to the sniffer.py script.
When running this command, note that it expects all sniffers to have the same amount of external adapters plugged in the same interfaces

Cancelling a future or running sniffing session

Detailed description of what this script does is to be found inside Starting and Stopping mitik-sens.
Run the stop_sens_sniffer.yml playbook:

ansible-playbook ../playbooks/start_sens_sniffer.yml

Cancelling a future or running sniffing session

Detailed description of what this script does is to be found inside Starting and Stopping mitik-sens.
Run the stop_sens_sniffer.yml playbook:

ansible-playbook ../playbooks/stop_sens_sniffer.yml

Testing current nodes statuses

Detailed description of what this script does is to be found inside Starting and Stopping mitik-sens.
Run the test_meta.yml playbook:

ansible-playbook ../playbooks/test_meta.yml