From aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 Mon Sep 17 00:00:00 2001 From: Rene Mayrhofer Date: Mon, 22 May 2006 05:12:18 +0000 Subject: Import initial strongswan 2.7.0 version into SVN. --- doc/src/umltesting.html | 478 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 doc/src/umltesting.html (limited to 'doc/src/umltesting.html') diff --git a/doc/src/umltesting.html b/doc/src/umltesting.html new file mode 100644 index 000000000..df62a9ae2 --- /dev/null +++ b/doc/src/umltesting.html @@ -0,0 +1,478 @@ + + +FreeS/WAN User-Mode-Linux testing guide + + + + + + + + +

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. +

+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. +FreeS/WAN has its own copy of that in lib/liblwres. +

Steps to Install UML for FreeS/WAN

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. +
+ +

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-15.1.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: +
- +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"
+
+
```
  +
+

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. +

+ + + -- cgit v1.2.3