diff options
| author | Rene Mayrhofer <rene@mayrhofer.eu.org> | 2006-05-22 05:12:18 +0000 |
|---|---|---|
| committer | Rene Mayrhofer <rene@mayrhofer.eu.org> | 2006-05-22 05:12:18 +0000 |
| commit | aa0f5b38aec14428b4b80e06f90ff781f8bca5f1 (patch) | |
| tree | 95f3d0c8cb0d59d88900dbbd72110d7ab6e15b2a /doc/src/umltesting.html | |
| parent | 7c383bc22113b23718be89fe18eeb251942d7356 (diff) | |
| download | vyos-strongswan-aa0f5b38aec14428b4b80e06f90ff781f8bca5f1.tar.gz vyos-strongswan-aa0f5b38aec14428b4b80e06f90ff781f8bca5f1.zip | |
Import initial strongswan 2.7.0 version into SVN.
Diffstat (limited to 'doc/src/umltesting.html')
| -rw-r--r-- | doc/src/umltesting.html | 478 |
1 files changed, 478 insertions, 0 deletions
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 @@ +<html> +<head> +<title>FreeS/WAN User-Mode-Linux testing guide</title> +<!-- Changed by: Michael Richardson, 05-Mar-2003 --> +<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing, User-Mode-Linux, UML"> + +<!-- + +Written by Michael Richardson for the Linux FreeS/WAN project +Freely distributable under the GNU General Public License + +More information at www.freeswan.org +Feedback to users@lists.freeswan.org + +$Id: umltesting.html,v 1.1 2004/03/15 20:35:24 as Exp $ + +$Log: umltesting.html,v $ +Revision 1.1 2004/03/15 20:35:24 as +added files from freeswan-2.04-x509-1.5.3 + +Revision 1.23 2003/09/18 15:12:11 dhr + +fix link to kernel.org mirrors page + +Revision 1.22 2003/03/07 03:49:25 dhr + +fix recommended version of uml-patch + +Revision 1.21 2003/03/06 08:37:03 dhr + +capture more of MCR's knowledge about BIND + +Revision 1.20 2003/03/06 02:15:44 mcr + added note about need for bind9. + +Revision 1.19 2003/03/05 23:20:39 mcr + updates from -47 to -53. + +Revision 1.18 2003/02/27 08:25:48 dhr + +update to reflect newer umlfreeroot + +Revision 1.17 2003/02/27 08:16:45 dhr + +make clear what is the latest version of the UML patch that we've used + +Revision 1.16 2003/02/21 01:35:31 mcr + updated latest umlfreeroot to 15.1. + +Revision 1.15 2003/01/21 03:26:34 mcr + updated documentation on UML state. + +Revision 1.14 2002/11/11 16:43:35 mcr + adjusted formatting of uml_netjig notes. + +Revision 1.13 2002/11/08 10:13:05 mcr + updated documentation for 2.4.19 + +Revision 1.12 2002/11/03 23:44:23 mcr + fixed some formatting in umltesting.html + added some notes about NETJIGWAITUSER re: having tests + prompt before they exit. Helps with debugging. + +Revision 1.11 2002/10/31 19:01:31 mcr + documentation for RUN_*_SCRIPT. + +Revision 1.10 2002/09/15 23:57:59 dhr + +update suggested umlfreeroot + +Revision 1.9 2002/09/15 19:28:05 mcr + added some comments about problems with UMLs. + +Revision 1.8 2002/09/11 20:00:25 mcr + updated umlroot rev to 8.0. + +Revision 1.7 2002/09/09 21:37:43 mcr + updated document to reference currently working kernel+UML. + +Revision 1.6 2002/08/02 22:43:35 mcr + added section on debugging with UMLs. + +Revision 1.5 2002/05/30 18:47:57 dhr + +Update from experience: +- fixed HTML bugs +- restructure slightly +- added another intro paragraph +- mentioned lack of Super User requirements +- added tcpdump build and install procedure +- added uml utils build procedure +- added invitation to try "make check" +- fixed minor typos and mistakes + +Revision 1.4 2002/03/12 21:10:37 mcr + removed instruction on downloading umlminishare, as this is + now simply included in umlrootXXX. reformated some other text. + +Revision 1.3 2002/01/29 02:21:21 mcr + updated instructions for 2.4.17, and for newest UMLroot. + +Revision 1.2 2001/11/27 05:24:09 mcr + added reference to uml-rhroot, but commented out. + This proceedure is not yet ready for prime time. + +Revision 1.1 2001/11/05 04:35:57 mcr + adapted text from design list posting into HTML for Sandy. + + +--> +</head> + +<body> + +<h1><a name="umltesting">User-Mode-Linux Testing guide</a></h1> + +<p> +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 <A HREF="http://user-mode-linux.sourceforge.net/">http://user-mode-linux.sourceforge.net/</A> +</P> + +<p> +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. +</p> + +<p> +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. +</p> +<p> +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. +</P> +<H2>Preliminary Notes on BIND</H2> + +<P> +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 +<A HREF="ftp://ftp.isc.org/isc/bind9/snapshots">ftp://ftp.isc.org/isc/bind9/snapshots</A>. +</P> +<P> +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. +</P> +<OL> +<LI> +named +</LI> +<LI> +dnssec-* +</LI> +<LI> +client side resolver libraries +</LI> +<LI> +client side utility libraries +I thought there were lib and named parts to dnsssec... +</LI> +<LI> +dynamic DNS update utilities +</LI> +</OL> +<P> +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. +</P> +<H2>Steps to Install UML for FreeS/WAN</H2> +<OL> +<LI> Get the following files: +<OL type="a"> +<LI> from <A HREF="http://www.sandelman.ottawa.on.ca/freeswan/uml/">http://www.sandelman.ottawa.on.ca/freeswan/uml/</A> +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. + + +<!-- If you are using + Redhat 7.2 or newer as your development machine, you can create the + image from your installation media. See <A HREF="uml-rhroot.html">Building a RedHat root"></A>. + A future document will explain how to build this from .DEB files as well. +--> + +<!-- +<LI> umlfreesharemini.tar.gz (or umlfreeshareall.tar.gz). + If you are a Debian potato user, you don't need it you can use your + native /usr/share. +</UL> +--> + +<LI> From <A HREF="ftp://ftp.xs4all.nl/pub/crypto/freeswan/">ftp://ftp.xs4all.nl/pub/crypto/freeswan/</A> +a snapshot or release (1.92 or better) + +<LI> From a + <A HREF="http://www.kernel.org/mirrors/">http://www.kernel.org mirror</A>, + 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 <A HREF="http://bugs.freeswan.org:81/regress/HEAD/lastgood/freeswan-regress-env.sh">freeswan-regress-env.sh</A>. + +<LI> +<!-- Note: this step is refered to as "step 1d" below. --> +Get + <A HREF="http://ftp.nl.linux.org/uml/">http://ftp.nl.linux.org/uml/</A> + 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. +<STRONG>More recent versions of the patch have not been tested by us.</STRONG> +<LI> You'll probably want to visit +<A + HREF="http://user-mode-linux.sourceforge.net">http://user-mode-linux.sourceforge.net</A> +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. +<LI> +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 +<A HREF="http://www.tcpdump.org/">http://www.tcpdump.org/</A> or a mirror. +</OL> + +<LI> Pick a suitable place, and extract the following files: +<OL type="a"> +<LI> +<!-- Note: this step is refered to as "step 2a" later. --> +2.4.19 kernel. For instance: +<PRE> +<CODE> + cd /c2/kernel + tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz +</CODE> +</PRE> + +<LI> extract the umlfreeroot file +<!-- (unless you <A HREF="uml-rhroot.html">built your own from RPMs</A>) --> +<PRE> +<CODE> + mkdir -p /c2/user-mode-linux/basic-root + cd /c2/user-mode-linux/basic-root + tar xzvf ../download/umlfreeroot-15.1.tar.gz +</CODE> +</PRE> + +<LI> FreeSWAN itself (or checkout "all" from CVS) +<PRE> +<CODE> + mkdir -p /c2/freeswan/sandbox + cd /c2/freeswan/sandbox + tar xzvf ../download/snapshot.tar.gz +</CODE> +</PRE> +</OL> + +<LI> If you need to build a newer tcpdump: +<UL> +<LI> +Make sure you have OpenSSL installed -- it is needed for cryptographic routines. +<LI> +Unpack libpcap and tcpdump source in parallel directories (the tcpdump +build procedures look for libpcap next door). +<LI> +Change directory into the libpcap source directory and then build the library: +<PRE> +<CODE> + ./configure + make +</CODE> +</PRE> +<LI> +Change into the tcpdump source directory, build tcpdump, and install it. +<PRE> +<CODE> + ./configure + make + # Need to be superuser to install in system directories. + # Installing in ~/bin would be an alternative. + su -c "make install" +</CODE> +</PRE> +</UL> +<LI> If you need the uml utilities, unpack them somewhere then build and install +them: +<PRE> +<CODE> + 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" +</CODE> +</PRE> +<LI> set up the configuration file +<UL> +<LI> +<CODE> +cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils +</CODE> +<LI> copy umlsetup-sample.sh to ../../umlsetup.sh: +<CODE> + cp umlsetup-sample.sh ../../umlsetup.sh +</CODE> + +<LI> open up ../../umlsetup.sh in your favorite editor. +<LI> 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. + +<LI> Set TESTINGROOT if you intend to run the script outside of the + sandbox/snapshot/release directory. Otherwise, it will configure itself. + +<LI> 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. + +<LI> 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. + +<LI> 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. + +<LI> BASICROOT should be set to the directory used in 2b, or to the directory + that you created with RPMs. + +<LI> SHAREDIR should be set to the directory used in 2c, to /usr/share + for Debian potato users, or to $BASICROOT/usr/share. +</UL> + +<LI> <PRE><CODE> +cd $TESTINGROOT/utils +sh make-uml.sh +</CODE></PRE> + 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. + +<LI> You will have a bunch of stuff under $POOLSPACE. + Open four xterms: + +<PRE><CODE> + for i in sunrise sunset east west + do + xterm -name $i -title $i -e $POOLSPACE/$i/start.sh & + done +</CODE></PRE> + +<LI> 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.) + +<LI> verify that pluto started on east/west, run "ipsec look" + +<LI> login to sunrise. run "ping sunset" + +<LI> login to west. run "tcpdump -p -i eth1 -n" + (tcpdump must be version 3.7.1 or newer) + +<LI> Closing a console xterm will shut down that UML. + +<LI> You can "make check", if you want to. +It is run from /c2/freeswan/sandbox/freeswan-1.97.</LI> + +</OL> + +<H1>Debugging the kernel with GDB</H1> + +<P> +With User-Mode-Linux, you can debug the kernel using GDB. +See <HREF="http://user-mode-linux.sourceforge.net/debugging.html">http://user-mode-linux.sourceforge.net/debugging.html</A>. +</P> + +<P> +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. +</P> +<P> +Tell it to open the UMLPOOL/swan/linux program. +</P> +<P> +Note the PID of GDB: +<PRE> +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 +</PRE> +</P> + +<P> +Set the following in the environment: +<PRE> +UML_east_OPT="debug gdb-pid=1659" +</PRE> +</P> + +<P> +Then start the user-mode-linux in the test scheme you wish: +<PRE> +marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh +</PRE> + +The user-mode-linux will stop on boot, giving you a chance to attach to the process: + +<PRE> +(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 +</PRE> + +<P> +At this point, break points should be created as appropriate. +</P> + +<H2>Other notes about debugging</H2> + +<P> +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. +</P> +<P> +The environment variable <CODE>NETJIGWAITUSER</CODE> can be set to "waituser". +If so, then the testing system will prompt before exiting the test. +</P> + +<H1>User-Mode-Linux mysteries</H1> + +<UL> +<LI> running more than one UML of the same name (e.g. "west") can cause + problems. +<LI> running more than one UML from the same root file system is not + a good idea. +<LI> all this means that running "make check" twice on the same machine + is probably not a good idea. +<LI> occationally, UMLs will get stuck. This can happen like: +<BLOCK> +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] + </BLOCK> + +these will need to be killed. Note that they are in "T"racing mode. +<LI> 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. +</UL> + +<H1>Getting more info from uml_netjig</H1> + +<P> +uml_netjig can be compiled with a built-in tcpdump. This uses not-yet-released +code from <A HREF="http://www.tcpdump.org/">www.tcpdump.org</A>. +Please see the instructions in <CODE>testing/utils/uml_netjig/Makefile</CODE>. +</P> + +</body> +</html> |