From 83cb0b0e8cc1e97efdbf53c4e0a14121aef08b42 Mon Sep 17 00:00:00 2001 From: Martin Willi Date: Fri, 28 Apr 2006 09:07:55 +0000 Subject: --- doc/src/umltesting.html | 478 ------------------------------------------------ 1 file changed, 478 deletions(-) delete mode 100644 doc/src/umltesting.html (limited to 'doc/src/umltesting.html') diff --git a/doc/src/umltesting.html b/doc/src/umltesting.html deleted file mode 100644 index df62a9ae2..000000000 --- a/doc/src/umltesting.html +++ /dev/null @@ -1,478 +0,0 @@ - - -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