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.
- Get the following files:
- from http://www.sandelman.ottawa.on.ca/freeswan/uml/
umlfreeroot-8.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.
- From ftp://ftp.xs4all.nl/pub/crypto/freeswan/
a snapshot or release (1.92 or better)
- From
http://linux.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.
-
Get
http://ftp.nl.linux.org/uml/
uml-patch-2.4.19-27.bz2 or the one associated with your kernel.
More recent versions of the patch have not been tested by us.
- 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.
-
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.
- Pick a suitable place, and extract the following files:
-
2.4.19 kernel. For instance:
cd /c2/kernel
tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
- extract the umlfreeroot file
mkdir -p /c2/user-mode-linux/basic-root
cd /c2/user-mode-linux/basic-root
tar xzvf ../download/umlfreeroot-14.0.tar.gz
- FreeSWAN itself (or checkout "all" from CVS)
mkdir -p /c2/freeswan/sandbox
cd /c2/freeswan/sandbox
tar xzvf ../download/snapshot.tar.gz
- If you need to build a newer tcpdump:
- 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"
- set up the configuration file
-
cd /c2/freeswan/sandbox/freeswan-1.97/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.
-
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.
- 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
- 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.)
- verify that pluto started on east/west, run "ipsec look"
- login to sunrise. run "ping sunset"
- login to west. run "tcpdump -p -i eth1 -n"
(tcpdump must be version 3.7.1 or newer)
- Closing a console xterm will shut down that UML.
- 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
- running more than one UML of the same name (e.g. "west") can cause
problems.
- running more than one UML from the same root file system is not
a good idea.
- all this means that running "make check" twice on the same machine
is probably not a good idea.
- occationally, UMLs will get stuck. This can happen like:
15134 ? T 0:00 /spare/hugh/uml/uml2.4.18-sept5/umlbuild/east/linux (east) [/bin/sh]
15138 ? T 0:00 /spare/hugh/uml/uml2.4.18-sept5/umlbuild/east/linux (east) [halt]
these will need to be killed. Note that they are in "T"racing mode.
- UMLs can also hang, and will report "Tracing myself and I can't get out".
This is a bug in UML. There are ways to find out what is going on and
report this to the UML people, but we don't know the magic right now.
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
.