To get started, you will need a Raspberry Pi running Linux. The recommended distribution is Raspbian stretch lite. Your Raspberry Pi needs to be equipped with two network cards. The recommended set-up is using the built-in network interface card in combination with a USB dongle.

This guide assumes that your Raspberry Pi is set up as outlined above and that we are starting from a new operating system installation. All commands in this guide are intended to be run as the root user.

Znail requires that a couple of system tools are available, along with a Python interpreter and its dependencies.

Let's start with the tools that we will need:

apt update
apt install bridge-utils ebtables dnsmasq python3 python3-pip git
pip3 install pipenv

Next, let's configure the system to load the required kernel modules at boot:

cat <<EOF >/etc/modules
# /etc/modules: kernel modules to load at boot time.
#
# This file contains the names of kernel modules that should be loaded
# at boot time, one per line. Lines beginning with "#" are ignored.

sch_netem
br_netfilter
EOF

Let's configure the systems network settings:

cat <<EOF >/etc/network/interfaces
# interfaces(5) file used by ifup(8) and ifdown(8)

# Please note that this file is written to be used with dhcpcd
# For static IP, consult /etc/dhcpcd.conf and 'man dhcpcd.conf'

# Include files from /etc/network/interfaces.d:
source-directory /etc/network/interfaces.d

auto lo
        iface lo inet loopback

auto eth0
        iface eth0 inet manual

auth eth1
        iface eth1 inet manual

auto br0
        iface br0 inet dhcp
        bridge_ports eth0 eth1
        bridge_stp off
        post-up /bin/echo -n 1 > /sys/devices/virtual/net/br0/bridge/multicast_querier
        bridge_hw ETH0_MAC_ADDRESS_HERE
EOF

The above network configuration makes a few assumptions. eth0 is assumed to be connected to the network while eth1 is assumed to be connected to the system that you want to test. It is further assumed that the Raspberry Pi will be using DHCP to acquire its IP address.

Now that the system has been set up, we will need a copy of Znail. For this guide, we will be using the latest and greatest version from the master branch.

cd opt
git clone https://github.com/Zenterio/znail.git
cd znail && rm Pipfile Pipfile.lock && mv Pipfile-armhf Pipfile
ln -s /opt/znail/znail/netem/data/hub-ctrl /usr/bin/hub-ctrl
pipenv update

Next, we can start Znail:

pipenv run python3 -m znail.ui.__main__

You should now be able to navigate a browser to the IP address of your Raspberry Pi and can start using Znail, congratulations!

Having to manually start the Znail process is not ideal.

Let's create a service that starts it automatically:

cat <<EOF >/etc/systemd/system/znail.service
[Unit]
Description=Znail server.

[Service]
WorkingDirectory=/opt/znail
ExecStart=/usr/local/bin/pipenv run python3 -m znail.ui.__main__
Restart=always
RestartSec=10
User=root
Group=root
StartLimitBurst=10

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable znail
systemctl start znail

Znail will now start automatically when your Raspberry Pi does.

This process is rather involved, laborious and uses some questionable methodology. It could be improved greatly by automation, packaging or perhaps even providing a pre-build Raspbian image that comes with Znail pre-installed.

Contributions in this area are most welcome.