Here's how to set up an environment to run our automated test suite. Alternatively, you way want to use the tails::tester class from the puppet-tails Puppet module.

Once you have a working environment, see usage.

Install dependencies

First of all, one needs a Debian Stretch system with:

  • the non-free APT component enabled;
  • the official backports repository configured.

The following packages are necessary on Debian Stretch:

sudo apt update && \
sudo apt install \
    cucumber \
    devscripts \
    dnsmasq-base \
    gawk \
    git \
    i18nspector \
    libav-tools \
    libcap2-bin \
    libsikulixapi-java \
    libvirt-clients \
    libvirt-daemon-system \
    libvirt-dev \
    libvirt0 \
    obfs4proxy \
    openssh-server \
    ovmf \
    pry \
    python-jabberbot \
    python-potr \
    qemu-kvm \
    qemu-system-common \
    qemu-system-x86 \
    qemu-utils \
    redir \
    ruby-guestfs \
    ruby-json \
    ruby-libvirt \
    ruby-net-irc \
    ruby-packetfu \
    ruby-rb-inotify \
    ruby-rjb \
    ruby-rspec \
    ruby-test-unit \
    seabios \
    tcpdump \
    tor \
    unclutter \
    virt-viewer \
    x11vnc \
    tigervnc-viewer \
    x264 \
    xvfb \
    && \
sudo service libvirtd restart

Other requirements

Synchronized clock

The system running the test suite needs an accurate clock since we sync the clock from the host to the Tails guest after a background snapshot restore to appease Tor.

You might want to install ntp or your favorite time synchronization tool for this.

File permissions

The user that runs QEMU (via libvirt) needs read-access at least to the content of features/misc_files/ in the Git checkout.

AppArmor tweaks

If libvirt has the apparmor security driver enabled:

  • you may need to add the /tmp/TailsToaster/TailsToasterStorage/* rw, line to /etc/apparmor.d/libvirt/TEMPLATE.qemu, in the profile LIBVIRT_TEMPLATE section;
  • you may hit various problems, such as denied access to /usr/share/ovmf/OVMF.fd; all such known problems are (as of 2015-08-12) on their way for being fixed upstream in libvirt. Running a recent libvirt may help.

Special use cases

Access the system under test with VNC

If you're running the test suite in a nested environnement, install tigervnc-viewer on the bare metal level-0 host. Then you can use vncviewer's -via option so that it automatically setup a ssh tunnel to your first level test suite domain for you and display the Tails VM. E.g. where $DISPLAY is the display given to you by run_test_suite (often 0):

vncviewer -viewonly -via user@level0 localhost:$DISPLAY

Running the test suite as a non-root user

This is entirely possible, but there's some additional configuration required. Run the following as root:

addgroup tcpdump
dpkg-statoverride --update --add root tcpdump 754 /usr/sbin/tcpdump
setcap CAP_NET_RAW+eip /usr/sbin/tcpdump
adduser $USER tcpdump
adduser $USER libvirt
adduser $USER libvirt-qemu

It's important to run setcap after dpkg-statoverride since the latter deletes all capabilities. Unfortunately the setcap command has to be rerun for that reason everytime the tcpdump package is updated until Debian bug #662845 is fixed.

Running these commands will add some interesting capabilities to $USER, so you may want to do this for a dedicated user separate from your normal user. In that case (and if you run the tests as root) the --view option won't work unless you grant $USER access to your display via xhost +SI:localhost:$USER. Alternatively you can use the --vnc-server-only option and manually connect to the VNC server with your normal user. Just make sure the VNC viewer is in view-only mode (e.g. xtigervncviewer --view-only ...) in order to not interfere with the testing session.