Test Suite - KVM

Libreswan comes with an extensive test suite, written mostly in python, that uses KVM virtual machines and virtual networks. It has replaced the old UML test suite. Apart from KVM, the test suite uses libvirtd and qemu. It is strongly recommended to run the test suite natively on the OS (not in a VM itself) on a machine that has a CPU wth virtualization instructions. The PLAN9 filesystem (9p) is used to mount host directories in the guests - NFS is avoided to prevent network lockups when an IPsec test case would cripple the guest's networking.

Test Frameworks

This page describes the make kvm framework.

Instead of using virtual machines, it is possible to use Docker instances.

More information is found in Test Suite - Docker in this Wiki

Preparing the host machine

In the following it is assumed that your account is called "build".

Add Yourself to sudo

Some of the test scrips need to be run as root. The test environment assumes this can be done using sudo without a password vis:

sudo pwd

XXX: Surely qemu can be driven without root?

This is done by creating a no-pasword rule to /etc/sudoers.d/.

To set this up, add your account to the wheel group:

sudo usermod -a -G wheel $(id -u -n)

and permit wheel to have no-password access:

echo '%wheel ALL=(ALL) NOPASSWD: ALL' | sudo dd of=/etc/sudoers.d/wheel
sudo chmod ug=r,o= /etc/sudoers.d/wheel
sudo chown root.root /etc/sudoers.d/wheel

Fight SELinux

SELinux blocks some actions that we need. We have not created any SELinux rules to avoid this. The options are:

• set SELinux to permissive (recommended)

sudo sed --in-place=.ORIG -e 's/^SELINUX=.*/SELINUX=permissive/' /etc/selinux/config
sudo setenforce Permissive

• disable SELinux

sudo sed --in-place=.ORIG -e 's/^SELINUX=.*/SELINUX=disabled/' /etc/selinux/config
sudo reboot

• (experimental) label source tree for SELinux

The source tree on the host is shared with the virtual machines. SELinux considers this a bug unless the tree is labelled with type svirt_image_t.

sudo dnf install policycoreutils-python-utils
sudo semanage fcontext -a -t svirt_image_t "$(pwd)"'(/.*)?'
sudo restorecon -vR /home/build/libreswan

There may be other things that SELinux objects to.

Install Required Dependencies

Now we are ready to install the various components of libvirtd, qemu and kvm and then start the libvirtd service.

Fedora

To get qemu working (while virt-manager isn't strictly required it's useful on a desktop):

sudo dnf install -y make git
sudo dnf install -y qemu virt-manager virt-install libvirt-daemon-kvm libvirt-daemon-qemu
sudo dnf install -y python3-pexpect

so web pages can be generated:

sudo dnf install -y jq nodejs-typescript

Once all is installed start libvirtd and then check it is running:

sudo systemctl enable libvirtd
sudo systemctl start libvirtd
sudo systemctl status libvirtd

There should be no errors and warnings.

On testing and F29, this failed with the error:

error : virQEMUCapsNewForBinaryInternal:4664 : internal error: Failed to probe QEMU binary with QMP: /usr/bin/qemu-system-xtensa: error while loading shared libraries: libbrlapi.so.0.6: cannot open shared object file: No such file or directory

and it was found that 'brlapi' needed to be manually installed.

Debian

Anyone?

Setting Users and Groups

You need to add yourself to the qemu group. For instance:

sudo usermod -a -G qemu $(id -u -n)

You will need to re-login for this to take effect.

The path to your build needs to be accessible (executable) by root:

chmod a+x ~

Fix /var/lib/libvirt/qemu

sudo chmod g+w /var/lib/libvirt/qemu

Create /etc/modules-load.d/virtio.conf

Several virtio modules need to be loaded into the host's kernel. This could be done by modprobe ahead of running any virtual machines but it is easier to install them whenever the host boots. This is arranged by listing the modules in a file within /etc/modules-load.d. The host must be rebooted for this to take effect.

sudo dd <<EOF of=/etc/modules-load.d/virtio.conf
virtio_blk
virtio-rng
virtio_console
virtio_net
virtio_scsi
virtio
virtio_balloon
virtio_input
virtio_pci
virtio_ring
9pnet_virtio
EOF

As of Fedora 28, several of these modules are now built into the kernel and will not show up in /proc/modules (virtio, virtio_rng, virtio_pci, virtio_ring).

Ensure that the host has enough entropy

Entropy matters

With KVM, a guest systems uses entropy from the host through the kernel module "virtio_rng" in the guest's kernel (set above). This has advantages:

• entropy only needs to be gathered on one machine (the host) rather than all machines (the host and the guests)
• the host is in the Real World and thus has more sources of real entropy
• any hacking to make entropy available need only be done on one machine

To ensure the host has enough randomness, run either jitterentropy-rngd or havegd.

Fedora commands for using jitterentropy-rngd (broken on F26, service file specifies /usr/local for path):

sudo dnf install jitterentropy-rngd
sudo systemctl enable jitterentropy-rngd
sudo systemctl start jitterentropy-rngd

Fedora commands for using havegd:

sudo dnf install haveged
sudo systemctl enable haveged
sudo systemctl start haveged

Download and configure libreswan

Fetch Libreswan

The libreswan source tree includes all the components that are used on the host and inside the test VMs. To get the latest source code using git:

git clone https://github.com/libreswan/libreswan
cd libreswan

Create the Pool directory for storing VM disk images - $(KVM_POOLDIR)

The pool directory is used used to store VM disk images and other configuration files. By default $(top_srcdir)/../pool is used (that is, adjacent to your source tree).

To change the location of the pool directory, set the KVM_POOLDIR make variable in Makefile.inc.local. For instance:

$ grep KVM_POOLDIR Makefile.inc.local
KVM_POOLDIR=/home/libreswan/pool

(optional) Use /tmp/pool (tmpfs) to store test VM disk images - $(KVM_LOCALDIR)

By default, all disk mages are stored in $(KVM_POOLDIR) (see above). That is both the base VM disk image, and the build VM and test VM disk images. Since only the base VM image needs long-term storage, $(KVM_LOCALDIR) can be used to specify that the build and test images are stored in /tmp:

$ grep KVM_LOCALDIR Makefile.inc.local
KVM_LOCALDIR=/tmp/pool

This has the advantage of eliminating physical disk I/O as a bottle neck when accessing VM disk images; but the disadvantage of needing to re-build the images after a reboot.

(optional) Run tests in parallel - $(KVM_PREFIXES)

By default only one test is run at a time. This can be changed using KVM_PREFIXES make variable which specifies the prefix to prepend to test domains. The default value is:

KVM_PREFIXES=''

which creates the domains east, west, et.al. (i.e., after expansion east, west, et.al.).

Multiple tests can be run in parallel by specifying more prefixes - a rule of thumb is one prefix per two CPU cores. For instance, on a 4-core machine, two prefixes can be specified using:

KVM_PREFIXES='' 1.

which creates, after expansion, the domains east, west, et.al. and 1.east, 1.west, et.al.

(very optional) Boot VMs in parallel - $(KVM_WORKERS)

By default one thread is dedicated to booting VMs. Since booting a VM is very CPU intensive, trying to boot multiple VMs can quickly boog down the machine causing tests being run in parallel to become so slow that they timeout.

So while not recommended, this can be changed using the make variable KVM_WORKERS:

KVM_WORKERS=2

(optional) Generate a web page of the test results

See the nightly test results for an example.

To create the web directory RESULTS/ and populate it with the current test results use:

make web

The files can the be viewed using http://file. To disable web page generation, delete the directory RESULTS/.

Alternatively, a web server can be installed and configured:

sudo dnf install httpd
sudo systemctl enable httpd
sudo systemctl start httpd
sudo mkdir /var/www/html/results/
sudo chown $(id -un) /var/www/html/results/
sudo chmod 755 /var/www/html/results/
sudo sh -c 'echo "AddType text/plain .diff" >/etc/httpd/conf.d/diff.conf'

and then $(WEB_SUMMARYDIR) used to specify that the web pages should be published under the server directory:

$ grep WEB_SUMMARYDIR Makefile.inc.local
WEB_SUMMARYDIR=/var/www/html/results

If you want it to be the main page of the website, you can create the file /var/www/html/index.html containing:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <head>
    <meta http-equiv="REFRESH" content="0;url=/results/">
  </head>
  <BODY>
  </BODY>
</HTML>

Running the testsuite

make kvm-install - build (update) and install libreswan

To build the VMs, and build (update) and install libreswan, use:

make kvm-install

To force a scratch build (re-constructing build and test domains, re-generating the certificates, and build/install libreswan from scratch), use:

make kvm-clean
make kvm-install

To also force an OS upgrade of the domains, use:

make kvm-purge
make kvm-install

(make kvm-demolish wipes out everything)

(optional) Generate the Certificates

The full testsuite requires a number of certificates. If not present, then make kvm-test (see below) will automatically generate them using the domain build.

Just note that the certificates have a limited lifetime.

Should the test system detects out-of-date certificates then make kvm-test will barf. When this happens, the commands:

make kvm-keys-clean
make kvm-keys

can be used to force the generation of new certificates.

make kvm-test - run the testsuite

To (re)run all test cases, use:

make kvm-test

(wehen a test is re-run the previous results are stored in the directory BACKUP/).

To just run tests that previously failed:

make kvm-retest

And to run a select group of tests, either:

make kvm-test KVM_TESTS+=testing/pluto/basic-pluto-01/

or:

./testing/utils/kvmtest.py testing/pluto/basic-pluto-01

make kvm-diffs -- inspect (and update) the test results

See kvmresults.py, the following make targets are useful (they can be run while the testsuite is still running):

make kvm-diffs
make kvm-results
<pre>

in addition, test runs can be limited to just the test files that have been modified (but not committed) using:

<pre>
kvm-modified
kvm-modified-check
kvm-modified-recheck
kvm-modified-results
kvm-modified-diffs

Stopping pluto tests (gracefully)

Type control-C; it will eventually stop (but may need to wait for all threads to become idle). If you grow impatient, just type control-C again.

To determine if the testsuite is running on a remote machine use:

make kvm-status

the running test suite can then be killed using:

make kvm-kill

Shell and Console Access (Logging In)

There are several different ways to gain shell access to the domains.

Each method, depending on the situation, has both advantages and disadvantages. For instance:

• while make kvmsh-host provide quick access to the console, it doesn't support file copy
• while SSH takes more to set up, it supports things like proper terminal configuration and file copy

Serial Console access using "make kvmsh-HOST" (kvmsh.py)

"kvmsh", is a wrapper around "virsh". It automatically handles things like booting the machine, logging in, and correctly configuring the terminal:

$ ./testing/utils/kvmsh.py east
[...]
Escape character is ^]
[root@east ~]# printenv TERM
xterm
[root@east ~]# stty -a
...; rows 52; columns 185; ... 
[root@east ~]#

"kvmsh.py" can also be used to script remote commands (for instance, it is used to run "make" on the build domain):

$ ./testing/utils/kvmsh.py east ls
[root@east ~]# ls
anaconda-ks.cfg

Finally, "make kvmsh-HOST" provides a short cut for the above; and if your using multiple build trees (see further down), it will connect to the DOMAIN that corresponds to HOST. For instance, notice how the domain "a.east" is passed to kvmsh.py in the below:

$ make kvmsh-east
/home/libreswan/pools/testing/utils/kvmsh.py --output ++compile-log.txt --chdir . a.east
Escape character is ^]
[root@east source]# 

Limitations:

• no file transfer but files can be accessed via /testing

Graphical Console access using virt-manager

"virt-manager", a gnome tool can be used to access individual domains.

While easy to use, it doesn't support cut/paste or mechanisms for copying files.

Shell access using SSH

While requiring slightly more effort to set up, it provides full shell access to the domains.

Since you will be using ssh a lot to login to these machines, it is recommended to either put their names in /etc/hosts:

# /etc/hosts entries for libreswan test suite
192.1.2.45 west
192.1.2.23 east
192.0.3.254 north
192.1.3.209 road
192.1.2.254 nic

or add entries to .ssh/config such as:

Host west
        Hostname 192.1.2.45

If you wish to be able to ssh into all the VMs created without using a password, add your ssh public key to testing/baseconfigs/all/etc/ssh/authorized_keys. This file is installed as /root/.ssh/authorized_keys on all VMs

Using ssh becomes easier if you are running ssh-agent (you probably are) and your public key is known to the virtual machine. This command, run on the host, installs your public key on the root account of the guest machines west. This assumes that west is up (it might not be, but you can put this off until you actually need ssh, at which time the machine would need to be up anyway). Remember that the root password on each guest machine is "swan".

ssh-copy-id root@west

You can use ssh-copy for any VM. Unfortunately, the key is forgotten when the VM is restarted.

How tests work

All the test cases involving VMs are located in the libreswan directory under testing/pluto/. The most basic test case is called basic-pluto-01. Each test case consists of a few files:

• description.txt to explain what this test case actually tests
• ipsec.conf files - for host west is called west.conf. This can also include configuration files for strongswan or racoon2 for interop testig
• ipsec.secret files - if non-default configurations are used. also uses the host syntax, eg west.secrets, east.secrets.
• An init.sh file for each VM that needs to start (eg westinit.sh, eastinit.sh, etc)
• One run.sh file for the host that is the initiator (eg westrun.sh)
• Known good (sanitized) output for each VM (eg west.console.txt, east.console.txt)
• testparams.sh if there are any non-default test parameters

Once the test run has completed, you will see an OUTPUT/ directory in the test case directory:

$ ls OUTPUT/
east.console.diff  east.console.verbose.txt  RESULT       west.console.txt          west.pluto.log
east.console.txt   east.pluto.log            swan12.pcap  west.console.diff  west.console.verbose.txt

• RESULT is a text file (whose format is sure to change in the next few months) stating whether the test succeeded or failed.
• The diff files show the differences between this testrun and the last known good output.
• Each VM's serial (sanitized) console log (eg west.console.txt)
• Each VM's unsanitized verbose console output (eg west.console.verbose.txt)
• A network capture from the bridge device (eg swan12.pcap)
• Each VM's pluto log, created with plutodebug=all (eg west.pluto.log)
• Any core dumps generated if a pluto daemon crashed

Debugging inside the VM

Debugging pluto on east

Terminal 1 - east: log into east, start pluto, and attach gdb

make kvmsh-east
east# cd /testing/pluto/basic-pluto-01
east# sh -x ./eastinit.sh
east# gdb /usr/local/libexec/ipsec/pluto $(pidof pluto)
(gdb) c

Terminal 2 - west: log into west, start pluto and the test

make kvmsh-west
west# sh -x ./westinit.sh ; sh -x westrun.sh

If pluto wasn't running, gdb would complain: --p requires an argument

When pluto crashes, gdb will show that and await commands. For example, the bt command will show a backtrace.

Debugging pluto on west

See above, but also use virt as a terminal.

/root/.gdbinit

If you want to get rid of the warning "warning: File "/testing/pluto/ikev2-dpd-01/.gdbinit" auto-loading has been declined by your `auto-load safe-path'"

echo "set auto-load safe-path /" >> /root/.gdbinit

Network Diagram (out-of-date)