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/umltesting.html | 313 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 doc/umltesting.html (limited to 'doc/umltesting.html') diff --git a/doc/umltesting.html b/doc/umltesting.html new file mode 100644 index 000000000..35bcef96d --- /dev/null +++ b/doc/umltesting.html @@ -0,0 +1,313 @@ + + + +Introduction to FreeS/WAN + + + + +Contents +Previous +Next +

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.

+Contents +Previous +Next + + -- cgit v1.2.3