diff options
Diffstat (limited to 'doc/src/umltesting.html')
| -rw-r--r-- | doc/src/umltesting.html | 478 |
1 files changed, 0 insertions, 478 deletions
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 @@ -<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> |