aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/umltesting.html
diff options
context:
space:
mode:
authorMartin Willi <martin@strongswan.org>2006-04-28 07:14:48 +0000
committerMartin Willi <martin@strongswan.org>2006-04-28 07:14:48 +0000
commit997358a6c475c8886cce388ab325184a1ff733c9 (patch)
tree27a15790e030fc186d00cd710d2a3540f4defe69 /doc/src/umltesting.html
parent52923c9acb349adec3d1cc039e7a74c2e822da6e (diff)
downloadstrongswan-997358a6c475c8886cce388ab325184a1ff733c9.tar.bz2
strongswan-997358a6c475c8886cce388ab325184a1ff733c9.tar.xz
- import of strongswan-2.7.0
- applied patch for charon
Diffstat (limited to 'doc/src/umltesting.html')
-rw-r--r--doc/src/umltesting.html478
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>
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-02 09:27:55 +0000