diff options
Diffstat (limited to 'doc/umltesting.html')
| -rw-r--r-- | doc/umltesting.html | 313 |
1 files changed, 313 insertions, 0 deletions
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 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> +<HEAD> +<TITLE>Introduction to FreeS/WAN</TITLE> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1"> +<STYLE TYPE="text/css"><!-- +BODY { font-family: serif } +H1 { font-family: sans-serif } +H2 { font-family: sans-serif } +H3 { font-family: sans-serif } +H4 { font-family: sans-serif } +H5 { font-family: sans-serif } +H6 { font-family: sans-serif } +SUB { font-size: smaller } +SUP { font-size: smaller } +PRE { font-family: monospace } +--></STYLE> +</HEAD> +<BODY> +<A HREF="toc.html">Contents</A> +<A HREF="roadmap.html">Previous</A> +<A HREF="makecheck.html">Next</A> +<HR> +<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><A NAME="34_1">Preliminary Notes on BIND</A></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><A NAME="34_2">Steps to Install UML for FreeS/WAN</A></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> +<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> +<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> +<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> +<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> +<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.</LI> +</OL> +</LI> +<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> +<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> +<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> +</LI> +</OL> +</LI> +<LI> If you need to build a newer tcpdump: +<UL> +<LI> Make sure you have OpenSSL installed -- it is needed for + cryptographic routines.</LI> +<LI> Unpack libpcap and tcpdump source in parallel directories (the + tcpdump build procedures look for libpcap next door).</LI> +<LI> Change directory into the libpcap source directory and then build + the library: +<PRE> + <CODE> ./configure + make +</CODE> +</PRE> +</LI> +<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> +</LI> +</UL> +</LI> +<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> +<LI> set up the configuration file +<UL> +<LI> <CODE>cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils</CODE></LI> +<LI> copy umlsetup-sample.sh to ../../umlsetup.sh: <CODE> cp + umlsetup-sample.sh ../../umlsetup.sh</CODE></LI> +<LI> open up ../../umlsetup.sh in your favorite editor.</LI> +<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> +<LI> Set TESTINGROOT if you intend to run the script outside of the + sandbox/snapshot/release directory. Otherwise, it will configure + itself.</LI> +<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> +<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> +<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> +<LI> BASICROOT should be set to the directory used in 2b, or to the + directory that you created with RPMs.</LI> +<LI> SHAREDIR should be set to the directory used in 2c, to /usr/share + for Debian potato users, or to $BASICROOT/usr/share.</LI> +</UL> +</LI> +<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> +<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> +<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> +<LI> verify that pluto started on east/west, run "ipsec look"</LI> +<LI> login to sunrise. run "ping sunset"</LI> +<LI> login to west. run "tcpdump -p -i eth1 -n" (tcpdump must be version + 3.7.1 or newer)</LI> +<LI> Closing a console xterm will shut down that UML.</LI> +<LI> You can "make check", if you want to. It is run from + /c2/freeswan/sandbox/freeswan-1.97.</LI> +</OL> +<H1><A NAME="35">Debugging the kernel with GDB</A></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.</(null)></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:</P> +<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> Set the following in the environment:</P> +<PRE> +UML_east_OPT="debug gdb-pid=1659" +</PRE> +<P> Then start the user-mode-linux in the test scheme you wish:</P> +<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><A NAME="35_1">Other notes about debugging</A></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><A NAME="36">User-Mode-Linux mysteries</A></H1> +<UL> +<LI> running more than one UML of the same name (e.g. "west") can cause + problems.</LI> +<LI> running more than one UML from the same root file system is not a + good idea.</LI> +<LI> all this means that running "make check" twice on the same machine + is probably not a good idea.</LI> +<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]</(null)> + these will need to be killed. Note that they are in "T"racing mode.</LI> +<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.</LI> +</UL> +<H1><A NAME="37">Getting more info from uml_netjig</A></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> +<HR> +<A HREF="toc.html">Contents</A> +<A HREF="roadmap.html">Previous</A> +<A HREF="makecheck.html">Next</A> +</BODY> +</HTML> |