User-Mode-Linux Testing guide

User mode linux 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/

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

You'll need about 500Mb of disk space for a full sunrise-east-west-sunset setup. You can possibly get this down by 130Mb if you remove the sunrise/sunset kernel build. If you just want to run, 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.

FreeS/WAN 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.

  1. named
  2. dnssec-*
  3. client side resolver libraries
  4. client side utility libraries I thought there were lib and named parts to dnsssec...
  5. 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. FreeS/WAN has its own copy of that in lib/liblwres.

Steps to Install UML for FreeS/WAN

  1. Get the following files:
    1. from http://www.sandelman.ottawa.on.ca/freeswan/uml/ umlfreeroot-15.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.
    2. From ftp://ftp.xs4all.nl/pub/crypto/freeswan/ a snapshot or release (1.92 or better)
    3. From a http://www.kernel.org mirror, the virgin 2.4.19 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 freeswan-regress-env.sh.
    4. Get http://ftp.nl.linux.org/uml/ uml-patch-2.4.19-47.bz2 or the one associated with your kernel. As of 2003/03/05, uml-patch-2.4.19-47.bz2 works for us. More recent versions of the patch have not been tested by us.
    5. You'll probably want to visit http://user-mode-linux.sourceforge.net and get the 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_20020212.tar.bz2.
    6. You need tcpdump version 3.7.1 or better. This is newer than the version included in most 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 from http://www.tcpdump.org/ or a mirror.
  2. Pick a suitable place, and extract the following files:
    1. 2.4.19 kernel. For instance: 
      
           cd /c2/kernel
           tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
    2. extract the umlfreeroot file 
      
           mkdir -p /c2/user-mode-linux/basic-root
           cd /c2/user-mode-linux/basic-root
           tar xzvf ../download/umlfreeroot-15.1.tar.gz
    3. FreeSWAN itself (or checkout "all" from CVS) 
      
           mkdir -p /c2/freeswan/sandbox
           cd /c2/freeswan/sandbox
           tar xzvf ../download/snapshot.tar.gz
  3. If you need to build a newer tcpdump:
  4. If you need the uml utilities, unpack them somewhere then build and install them: 
    
	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"
  5. set up the configuration file 
  6. 
cd $TESTINGROOT/utils
sh make-uml.sh
    It will grind for awhile. If there are errors it will bail. If so, run it under "script" and send the output to bugs@lists.freeswan.org.
  7. You will have a bunch of stuff under $POOLSPACE. Open four xterms: 
    
    for i in sunrise sunset east west
    do
        xterm -name $i -title $i -e $POOLSPACE/$i/start.sh &
    done
  8. Login as root. Password is "root" (Note, these virtual machines are networked together, but are not configured to talk to the rest of the world.)
  9. verify that pluto started on east/west, run "ipsec look"
  10. login to sunrise. run "ping sunset"
  11. login to west. run "tcpdump -p -i eth1 -n" (tcpdump must be version 3.7.1 or newer)
  12. Closing a console xterm will shut down that UML.
  13. You can "make check", if you want to. It is run from /c2/freeswan/sandbox/freeswan-1.97.

Debugging the kernel with GDB

With User-Mode-Linux, you can debug the kernel using GDB. See http://user-mode-linux.sourceforge.net/debugging.html.

Typically, one will want to address a test case for a failing situation. Running GDB from Emacs, or from other front ends is possible. First start GDB.

Tell it to open the UMLPOOL/swan/linux program.

Note the PID of GDB: 

marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb
 1659 pts/9    SN     0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux

Set the following in the environment: 

UML_east_OPT="debug gdb-pid=1659"

Then start the user-mode-linux in the test scheme you wish: 

marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh
The user-mode-linux will stop on boot, giving you a chance to attach to the process: 
(gdb) file linux
Reading symbols from linux...done.
(gdb) attach 1
Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1
0xa0118bc1 in kill () at hostfs_kern.c:770

At this point, break points should be created as appropriate.

Other notes about debugging

If you are running a standard test, after all the packets are sent, the UML will be shutdown. This can cause problems, because the UML may get terminated while you are debugging.

The environment variable NETJIGWAITUSER can be set to "waituser". If so, then the testing system will prompt before exiting the test.

User-Mode-Linux mysteries

Getting more info from uml_netjig

uml_netjig can be compiled with a built-in tcpdump. This uses not-yet-released code from www.tcpdump.org. Please see the instructions in testing/utils/uml_netjig/Makefile.