-*- emacs-wiki -*-
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 2005/10/31, the Light-Weight Resolver is used by pluto. This
requires that BIND9 be running. Since previous versions, the bind9.3
has been released and is therefore far more likely to be available. To
make sure that we have appropriate libraries, we have actually
imported the relevant code from bind 9.3.
Steps to Install UML for FreeS/WAN
1. Get the following files:
a. from rsync://anoncvs.openswan.org/rootfstar/
umlswanroot-26.tar.gz (or highest numbered one). This is
originally a debian potato root file system, but has many
upgrades and should work on any recent (debian sarge, FC4,
etc.).
b. From ftp://ftp.xs4all.nl/pub/crypto/freeswan/ a snapshot or
release (1.92 or better)
c. 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.
d. Get http://ftp.nl.linux.org/uml/ uml-patch-2.4.30-1.bz2 or
the one associated with your kernel. For 2.6 kernels after
2.6.10, you do not need any patches. We have tested up to
2.6.13. More recent versions of the patch have not been
tested by us.
e. 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.
f. 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:
a. 2.4.31 kernel. For instance:
cd /c2/kernel
tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.31.tar.gz
b. extract the umlswanroot file
mkdir -p /c2/user-mode-linux/basic-root
cd /c2/user-mode-linux/basic-root
tar xzvf ../download/umlswanroot-15.1.tar.gz
c. Openswan itself (or checkout "openswan-2" from CVS)
mkdir -p /c2/openswan/sandbox
cd /c2/openswan/sandbox
tar xzvf ../download/openswan-2.4.2dr2.tar.gz
3. If you need to build a newer tcpdump:
+ Make sure you have OpenSSL installed -- it is needed for
cryptographic routines.
+ Unpack libpcap and tcpdump source in parallel directories
(the tcpdump build procedures look for libpcap next door).
+ Change directory into the libpcap source directory and then
build the library:
./configure
make
+ Change into the tcpdump source directory, build tcpdump, and
install it.
./configure
make
# Need to be superuser to install in system directories.
# Installing in ~/bin would be an alternative.
su -c "make install"
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
+ cd /c2/freeswan/sandbox/openswanswan-2.4.2dr2/testing/utils
+ copy umlsetup-sample.sh to ../../umlsetup.sh: cp
umlsetup-sample.sh ../../umlsetup.sh
+ open up ../../umlsetup.sh in your favorite editor.
+ 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.
+ Set TESTINGROOT if you intend to run the script outside of
the sandbox/snapshot/release directory. Otherwise, it will
configure itself.
+ KERNPOOL should point to the directory with your 2.4.19
kernel tree. This tree should be unconfigured! This is the
directory you used in step 2a.
+ UMLPATCH should point at the bz2 file you downloaded at 1d.
If using a kernel that already includes the patch, set this
to /dev/null.
+ FREESWANDIR should point at the directory where you unpacked
the snapshot/release. Include the "freeswan-snap2001sep16b"
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 in 2b, or to
the directory that you created with RPMs.
+ SHAREDIR should be set to the directory used in 2c, to
/usr/share for Debian potato users, or to
$BASICROOT/usr/share.
6. make uml
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.
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.
Also see [[DebuggingKernel]], [[UMLMysteries]]
