User-Mode-Linux Testing guide

User mode linux (UML) is a way to compile a linux kernel such that it can run as a process in another linux system (potentially as a *BSD or Windows process later). See http://user-mode-linux.sourceforge.net for more information about UML.

UML is a good platform for testing and experimenting with Openswan. It allows several network nodes to be simulated on a single machine. Creating, configuring, installing, monitoring, and controling these nodes is generally simpler and easier to script with UML than with real hardware.

You'll need about 2 Gig of disk space for a full setup (7-9 UMLs). You can possibly get this down by 130Mb if you remove the sunrise/sunset kernel build. If you just want to play around, then you can even remove the east/west kernel build.

Nothing need be done as super user. In a couple of steps, we note where super user is required to install commands in system-wide directories, but ~/bin could be used instead. UML seems to use a system-wide /tmp/uml directory so different users may interfere with one another. Later UMLs use ~/.uml instead, so multiple users running UML tests should not be a problem, but note that a single user running the UML tests will only be able run one set. Further, UMLs sometimes get stuck and hang around. These "zombies" (most will actually be in the "T" state in the process table) will interfere with subsequent tests.

Preliminary Notes on BIND

As of 2003/3/1, the Light-Weight Resolver is used by pluto. This requires that BIND9 be running. It also requires that BIND9 development libraries be present in the build environment. The DNSSEC code is only truly functional in BIND9 snapshots. The library code could be 9.2.2, we believe. We are using BIND9 20021115 snapshot code from ftp://ftp.isc.org/isc/bind9/snapshots .

A bind 9.3 beta/rc ought to work, but we have yet to upgrade our infrastructure to it yet. We will do this very soon.

Openswan may well require a newer BIND than is on your system. Many distributions have moved to BIND9.2.2 recently due to a security advisory. BIND is five components.

named
dnssec-*
client side resolver libraries
client side utility libraries I thought there were lib and named parts to dnsssec...
dynamic DNS update utilities

The only piece that we need for building is #4. That's the only part that has to be on the build host. What is the difference between resolver and util libs? If you want to edit testing/baseconfigs/all/etc/bind, you'll need a snapshot version. The resolver library contains the resolver. Openswan has its own copy of that in lib/liblwres.

If don't want to deal with all of this, just make sure USE_LWRES=false in your Makefile.inc file in the Openswan distribution you are using.

Steps to Install and Setup UMLs for Openswan

Get the following software

http://www.openswan.org/code a snapshot or release (2.0.0 or better)
http://www.openswan.org/code - umlfreeroot-16.1.tar.gz (or highest numbered one). This is a debian potato root file system. You can use this even on a Redhat host, as it has the newer GLIBC2.2 libraries as well.
http://www.kernel.org mirror, a virgin 2.4.## kernel. Please realize that we have defaults in our tree for kernel configuration. We try to track the latest UML kernels. If you use a newer kernel, you may have faults in the kernel build process. You can see what the latest that is being regularly tested by visiting http://hulk.toronto.xelerance.com/xelerance/HEAD/2004/$month/2004_$month_$day/openswan-regress-env.sh
http://user-mode-linux.sourceforge.net - uml-patch-2.4.##-#.bz2 - the latest version to make your kernel from the previous item.
http://user-mode-linux.sourceforge.net - UML Utilities. These are not needed for the build or interactive use (but recommended). They are necessary for the regression testing procedures used by "make check". We currently use uml_utilities_20040114.tar.bz2.
http://www.tcpdump.org/ - You need tcpdump version 3.8.3 or better. This is newer than the version included in some LINUX distributions. You can check the version of an installed tcpdump with the --version flag. If you need a newer tcpdump fetch both tcpdump and libpcap source tar files see the directions at the bottom of this file to build a new version.

In addition, you will need normal GNU software development tools (gcc, ld, as, etc...), as well as expect (http://expect.nist.gov/) which is included, but not usually installed by default by most vendors.

Setup your UML Testing Directory tree.

You will need about 500MB of free space to build and run the full regression testing suite.

subdir
     |--kernel (extract your kernel source here)
     |       |--linux-2.4.##
     |       \--uml-patch-2.4.##-#.bz2
     |
     |--umlrootfs (extract your umlfreeroot here)
     |          \--root-##.1
     |
     |--openswan (extract your openswan release or do a CVS checkout here
     |         \--openswan-2
     |
     \--tools (for building umlutilities and other related tools)
            |--uml_utilities-#########.tar.bz2
            \--tools (unpack uml_utilities to create this dir)

If you need the uml utilities, unpack them somewhere then build and install them:

 	cd tools
        tar -xjvf uml_utilities_20040114.tar.bz2
        cd tools
	make all
	# Need to be superuser to install in system directories.
	# Installing in ~/bin would be an alternative.
	su -c "make install BIN_DIR=/usr/local/bin"

Set up the UML configuration file

The configuration file (umlsetup.sh) requires a number of parameters be set for it to run.

cd openswan/openswan-#.#.#
cp testing/utils/umlsetup-sample.sh umlsetup.sh

In umlsetup.sh:

change POOLSPACE= to point to the place with at least 500Mb of disk. Best if it is on the same partition as the "umlfreeroot" extraction, as it will attempt to use hard links if possible to save disk space.
KERNPOOL should point to the directory with your 2.4.## kernel tree. This tree should be unconfigured! This is the directory you put the kernel in above - eg: subdir/kernel/linux-2.4.##
UMLPATCH should point at the bz2 file you downloaded and put into subdir/kernel. If using a kernel that already includes the patch, set this to /dev/null.
OPENSWANDIR should point at the directory where you unpacked the snapshot/release. Include the "openswan-#.#.#" or whatever in it. If you are running from CVS, then you point at the directory where top, klips, etc. are. The script will fix up the directory so that it can be used.
BASICROOT should be set to the directory used for umlfreeroot (eg: subdir/umlrootfs/root-##.#
SHAREDIR should be set to /usr/share for Debian potato users, or to $BASICROOT/usr/share (everyone else).
TCPDUMP should be set to the location of your tcpdump binary - /usr/sbin/tcpdump or similar
REGRESSRESULTS (optional) should be set to the location where you want the results (pass/fail) of each test stored.

Here is a sample umlsetup.sh:

#!/bin/sh
# Root for regression testing setup
UMLPREFIX=/openswan/regression
# Our pool (built on demand)
POOLSPACE=$UMLPREFIX/umlbuild
# Virgin Kernel Source Directory
KERNPOOL=$UMLPREFIX/kernel/linux-2.4.24
# Use NATT support
NATTPATCH=true
# Usually $KERNPOOL
KERNEL_LINUS2_4_SRC=$KERNPOOL
# Location of the UML Patchfile for the kernel
UMLPATCH=$UMLPREFIX/kernel/uml-patch-2.4.24-1.bz2
# Where you unpacked umlfreeroot to
BASICROOT=$UMLPREFIX/umlrootfs/root-16.1
SHAREDIR=$UMLPREFIX/umlrootfs/root-16.1/usr/share
# Which UML 'hosts' to create.  All of these are needed for 'make check'
REGULARHOSTS='sunrise sunset nic carrot beet sec pole'
OPENSWANHOSTS='east west japan road north'
# Where is the tcpdump binary, if not in $PATH already.
TCPDUMP=/usr/sbin/tcpdump
# Where all the results go - usefull for using testing/utils/regress-summarize-results.pl on
REGRESSRESULTS=$UMLPREFIX/results

Build your initial UMLs

 cd subdir/openswan/openswan-#.#.#/testing/utils
 sh make-uml.sh