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.

Operating system

For Wayland users: at the moment the --view and --vnc-server-only options only work on X11.

If you usually run another operating system than Debian Stretch, Buster, Bullseye or Sid, then you need to:

  1. Enable nested virtualization on your host system.

    For example, if the host system has an Intel CPU:

      if [ "$(cat /sys/module/kvm_intel/parameters/nested)" != Y ]; then
         echo "options kvm_intel nested=Y" | \
              sudo tee /etc/modprobe.d/kvm.conf
  2. Prepare a Debian virtual machine; we recommend the stable release, Debian Buster.

  3. And then, every step below applies to this virtual machine, instead of to the host system.

Install dependencies

To install the dependencies on our test suite:

  1. Enable the non-free APT component.

  2. Install the following packages:

     dist=$(lsb_release --short --codename)
     if [ "${dist}" != stretch -o "${dist}" != buster ]; then
         # For python-jabberbot and python-potr, that were removed after Buster
         echo 'deb buster main' \
             | sudo tee /etc/apt/sources.list.d/buster.list
         # For unversioned python packages, needed by the above
         echo 'deb isotester-bullseye main' \
             | sudo tee /etc/apt/sources.list.d/isotester-bullseye.list
     if [ "${dist}" = buster ]; then
         echo 'deb buster-backports main' \
             | sudo tee /etc/apt/sources.list.d/buster-backports.list
         echo -e "Package: qemu*\nPin: release n=buster-backports, o=Debian Backports\nPin-Priority: 990" \
             | sudo tee /etc/apt/preferences.d/qemu
     sudo apt update && \
     sudo apt install \
         cucumber \
         devscripts \
         dnsmasq-base \
         gawk \
         git \
         i18nspector \
         imagemagick \
         libcap2-bin \
         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-packetfu \
         ruby-rb-inotify \
         ruby-rspec \
         ruby-test-unit \
         seabios \
         tcpdump \
         tcplay \
         tor \
         unclutter \
         virt-viewer \
         x11vnc \
         tigervnc-viewer \
         x264 \
         xdotool \
         xvfb \
             if [ "${dist}" = stretch ]; then
                 echo "libav-tools
                 echo "ffmpeg
         ) \
         && \
     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 enable systemd-timesyncd.service 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 you have AppArmor enabled:

  • You need to add the /tmp/TailsToaster/** rwk, line to /etc/apparmor.d/libvirt/TEMPLATE.qemu, in the profile LIBVIRT_TEMPLATE section; then delete /etc/apparmor.d/libvirt/libvirt-* and restart the test suite. On Debian Stretch, if you use a custom TMPDIR to run the test suite, replace /tmp/TailsToaster with the value of that $TMPDIR.

Patched QEMU

Due to #12142 aka. Debian bug #851694, any test scenario that creates a persistent volume will fail. To work around this problem, rebuild qemu locally with the upstream fix applied. For example, the qemu source package in this APT suite has the fix:

    deb-src isotester-stretch main

This problem does not affect host systems that run Debian Buster or newer.

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