doc/umltesting.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Introduction to FreeS/WAN</TITLE>
   5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
   6 <STYLE TYPE="text/css"><!--
   7 BODY { font-family: serif }
   8 H1 { font-family: sans-serif }
   9 H2 { font-family: sans-serif }
  10 H3 { font-family: sans-serif }
  11 H4 { font-family: sans-serif }
  12 H5 { font-family: sans-serif }
  13 H6 { font-family: sans-serif }
  14 SUB { font-size: smaller }
  15 SUP { font-size: smaller }
  16 PRE { font-family: monospace }
  17 --></STYLE>
  18 </HEAD>
  19 <BODY>
  20 <A HREF="toc.html">Contents</A>
  21 <A HREF="roadmap.html">Previous</A>
  22 <A HREF="makecheck.html">Next</A>
  23 <HR>
  24 <H1><A name="umltesting">User-Mode-Linux Testing guide</A></H1>
  25 <P> User mode linux is a way to compile a linux kernel such that it can
  26  run as a process in another linux system (potentially as a *BSD or
  27  Windows process later). See<A HREF="http://user-mode-linux.sourceforge.net/">
  28  http://user-mode-linux.sourceforge.net/</A></P>
  29 <P> UML is a good platform for testing and experimenting with FreeS/WAN.
  30  It allows several network nodes to be simulated on a single machine.
  31  Creating, configuring, installing, monitoring, and controling these
  32  nodes is generally easier and easier to script with UML than real
  33  hardware.</P>
  34 <P> You'll need about 500Mb of disk space for a full
  35  sunrise-east-west-sunset setup. You can possibly get this down by 130Mb
  36  if you remove the sunrise/sunset kernel build. If you just want to run,
  37  then you can even remove the east/west kernel build.</P>
  38 <P> Nothing need be done as super user. In a couple of steps, we note
  39  where super user is required to install commands in system-wide
  40  directories, but ~/bin could be used instead. UML seems to use a
  41  system-wide /tmp/uml directory so different users may interfere with
  42  one another. Later UMLs use ~/.uml instead, so multiple users running
  43  UML tests should not be a problem, but note that a single user running
  44  the UML tests will only be able run one set. Further, UMLs sometimes
  45  get stuck and hang around. These &quot;zombies&quot; (most will actually be in
  46  the &quot;T&quot; state in the process table) will interfere with subsequent
  47  tests.</P>
  48 <H2><A NAME="34_1">Preliminary Notes on BIND</A></H2>
  49 <P> As of 2003/3/1, the Light-Weight Resolver is used by pluto. This
  50  requires that BIND9 be running. It also requires that BIND9 development
  51  libraries be present in the build environment. The DNSSEC code is only
  52  truly functional in BIND9 snapshots. The library code could be 9.2.2,
  53  we believe. We are using BIND9 20021115 snapshot code from<A HREF="ftp://ftp.isc.org/isc/bind9/snapshots">
  54  ftp://ftp.isc.org/isc/bind9/snapshots</A>.</P>
  55 <P> FreeS/WAN may well require a newer BIND than is on your system. Many
  56  distributions have moved to BIND9.2.2 recently due to a security
  57  advisory. BIND is five components.</P>
  58 <OL>
  59 <LI> named</LI>
  60 <LI> dnssec-*</LI>
  61 <LI> client side resolver libraries</LI>
  62 <LI> client side utility libraries I thought there were lib and named
  63  parts to dnsssec...</LI>
  64 <LI> dynamic DNS update utilities</LI>
  65 </OL>
  66 <P> The only piece that we need for *building* is #4. That's the only
  67  part that has to be on the build host. What is the difference between
  68  resolver and util libs? If you want to edit
  69  testing/baseconfigs/all/etc/bind, you'll need a snapshot version. The
  70  resolver library contains the resolver. FreeS/WAN has its own copy of
  71  that in lib/liblwres.</P>
  72 <H2><A NAME="34_2">Steps to Install UML for FreeS/WAN</A></H2>
  73 <OL>
  74 <LI> Get the following files:
  75 <OL type="a">
  76 <LI> from<A HREF="http://www.sandelman.ottawa.on.ca/freeswan/uml/">
  77  http://www.sandelman.ottawa.on.ca/freeswan/uml/</A>
  78  umlfreeroot-15.1.tar.gz (or highest numbered one). This is a debian
  79  potato root file system. You can use this even on a Redhat host, as it
  80  has the newer GLIBC2.2 libraries as well.
  81 <!-- If you are using
  82   Redhat 7.2 or newer as your development machine, you can create the
  83   image from your installation media. See <A HREF="uml-rhroot.html">Building a RedHat root"></A>.
  84   A future document will explain how to build this from .DEB files as well.
  85 -->
  86
  87 <!--
  88 <LI> umlfreesharemini.tar.gz    (or umlfreeshareall.tar.gz).
  89   If you are a Debian potato user, you don't need it you can use your
  90   native /usr/share.
  91 </UL>
  92 -->
  93 </LI>
  94 <LI> From<A HREF="ftp://ftp.xs4all.nl/pub/crypto/freeswan/">
  95  ftp://ftp.xs4all.nl/pub/crypto/freeswan/</A> a snapshot or release
  96  (1.92 or better)</LI>
  97 <LI> From a<A HREF="http://www.kernel.org/mirrors/">
  98  http://www.kernel.org mirror</A>, the virgin 2.4.19 kernel. Please
  99  realize that we have defaults in our tree for kernel configuration. We
 100  try to track the latest UML kernels. If you use a newer kernel, you may
 101  have faults in the kernel build process. You can see what the latest
 102  that is being regularly tested by visiting<A HREF="http://bugs.freeswan.org:81/regress/HEAD/lastgood/freeswan-regress-env.sh">
 103  freeswan-regress-env.sh</A>.</LI>
 104 <LI>
 105 <!-- Note: this step is refered to as "step 1d" below. -->
 106  Get<A HREF="http://ftp.nl.linux.org/uml/">
 107  http://ftp.nl.linux.org/uml/</A> uml-patch-2.4.19-47.bz2 or the one
 108  associated with your kernel. As of 2003/03/05, uml-patch-2.4.19-47.bz2
 109  works for us.<STRONG> More recent versions of the patch have not been
 110  tested by us.</STRONG></LI>
 111 <LI> You'll probably want to visit<A HREF="http://user-mode-linux.sourceforge.net">
 112  http://user-mode-linux.sourceforge.net</A> and get the UML utilities.
 113  These are not needed for the build or interactive use (but
 114  recommended). They are necessary for the regression testing procedures
 115  used by &quot;make check&quot;. We currently use uml_utilities_20020212.tar.bz2.</LI>
 116 <LI> You need tcpdump version 3.7.1 or better. This is newer than the
 117  version included in most LINUX distributions. You can check the version
 118  of an installed tcpdump with the --version flag. If you need a newer
 119  tcpdump fetch both tcpdump and libpcap source tar files from<A HREF="http://www.tcpdump.org/">
 120  http://www.tcpdump.org/</A> or a mirror.</LI>
 121 </OL>
 122 </LI>
 123 <LI> Pick a suitable place, and extract the following files:
 124 <OL type="a">
 125 <LI>
 126 <!-- Note: this step is refered to as "step 2a" later. -->
 127  2.4.19 kernel. For instance:
 128 <PRE>
 129  <CODE>           cd /c2/kernel
 130            tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.19.tar.gz
 131 </CODE>
 132 </PRE>
 133 </LI>
 134 <LI> extract the umlfreeroot file
 135 <!-- (unless you <A HREF="uml-rhroot.html">built your own from RPMs</A>) -->
 136
 137 <PRE>
 138  <CODE>           mkdir -p /c2/user-mode-linux/basic-root
 139            cd /c2/user-mode-linux/basic-root
 140            tar xzvf ../download/umlfreeroot-15.1.tar.gz
 141 </CODE>
 142 </PRE>
 143 </LI>
 144 <LI> FreeSWAN itself (or checkout &quot;all&quot; from CVS)
 145 <PRE>
 146  <CODE>           mkdir -p /c2/freeswan/sandbox
 147            cd /c2/freeswan/sandbox
 148            tar xzvf ../download/snapshot.tar.gz
 149 </CODE>
 150 </PRE>
 151 </LI>
 152 </OL>
 153 </LI>
 154 <LI> If you need to build a newer tcpdump:
 155 <UL>
 156 <LI> Make sure you have OpenSSL installed -- it is needed for
 157  cryptographic routines.</LI>
 158 <LI> Unpack libpcap and tcpdump source in parallel directories (the
 159  tcpdump build procedures look for libpcap next door).</LI>
 160 <LI> Change directory into the libpcap source directory and then build
 161  the library:
 162 <PRE>
 163  <CODE> ./configure
 164         make
 165 </CODE>
 166 </PRE>
 167 </LI>
 168 <LI> Change into the tcpdump source directory, build tcpdump, and
 169  install it.
 170 <PRE>
 171  <CODE> ./configure
 172         make
 173         # Need to be superuser to install in system directories.
 174         # Installing in ~/bin would be an alternative.
 175         su -c &quot;make install&quot;
 176 </CODE>
 177 </PRE>
 178 </LI>
 179 </UL>
 180 </LI>
 181 <LI> If you need the uml utilities, unpack them somewhere then build and
 182  install them:
 183 <PRE>
 184  <CODE> cd tools
 185         make all
 186         # Need to be superuser to install in system directories.
 187         # Installing in ~/bin would be an alternative.
 188         su -c &quot;make install BIN_DIR=/usr/local/bin&quot;
 189 </CODE>
 190 </PRE>
 191 </LI>
 192 <LI> set up the configuration file
 193 <UL>
 194 <LI> <CODE>cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils</CODE></LI>
 195 <LI> copy umlsetup-sample.sh to ../../umlsetup.sh: <CODE> cp
 196  umlsetup-sample.sh ../../umlsetup.sh</CODE></LI>
 197 <LI> open up ../../umlsetup.sh in your favorite editor.</LI>
 198 <LI> change POOLSPACE= to point to the place with at least 500Mb of
 199  disk. Best if it is on the same partition as the &quot;umlfreeroot&quot;
 200  extraction, as it will attempt to use hard links if possible to save
 201  disk space.</LI>
 202 <LI> Set TESTINGROOT if you intend to run the script outside of the
 203  sandbox/snapshot/release directory. Otherwise, it will configure
 204  itself.</LI>
 205 <LI> KERNPOOL should point to the directory with your 2.4.19 kernel
 206  tree. This tree should be unconfigured! This is the directory you used
 207  in step 2a.</LI>
 208 <LI> UMLPATCH should point at the bz2 file you downloaded at 1d. If
 209  using a kernel that already includes the patch, set this to /dev/null.</LI>
 210 <LI> FREESWANDIR should point at the directory where you unpacked the
 211  snapshot/release. Include the &quot;freeswan-snap2001sep16b&quot; or whatever in
 212  it. If you are running from CVS, then you point at the directory where
 213  top, klips, etc. are. The script will fix up the directory so that it
 214  can be used.</LI>
 215 <LI> BASICROOT should be set to the directory used in 2b, or to the
 216  directory that you created with RPMs.</LI>
 217 <LI> SHAREDIR should be set to the directory used in 2c, to /usr/share
 218  for Debian potato users, or to $BASICROOT/usr/share.</LI>
 219 </UL>
 220 </LI>
 221 <LI>
 222 <PRE> <CODE>cd $TESTINGROOT/utils
 223 sh make-uml.sh
 224 </CODE></PRE>
 225  It will grind for awhile. If there are errors it will bail. If so, run
 226  it under &quot;script&quot; and send the output to bugs@lists.freeswan.org.</LI>
 227 <LI> You will have a bunch of stuff under $POOLSPACE. Open four xterms:
 228 <PRE> <CODE>    for i in sunrise sunset east west
 229     do
 230         xterm -name $i -title $i -e $POOLSPACE/$i/start.sh     done
 231 </CODE></PRE>
 232 </LI>
 233 <LI> Login as root. Password is &quot;root&quot; (Note, these virtual machines are
 234  networked together, but are not configured to talk to the rest of the
 235  world.)</LI>
 236 <LI> verify that pluto started on east/west, run &quot;ipsec look&quot;</LI>
 237 <LI> login to sunrise. run &quot;ping sunset&quot;</LI>
 238 <LI> login to west. run &quot;tcpdump -p -i eth1 -n&quot; (tcpdump must be version
 239  3.7.1 or newer)</LI>
 240 <LI> Closing a console xterm will shut down that UML.</LI>
 241 <LI> You can &quot;make check&quot;, if you want to. It is run from
 242  /c2/freeswan/sandbox/freeswan-1.97.</LI>
 243 </OL>
 244 <H1><A NAME="35">Debugging the kernel with GDB</A></H1>
 245 <P> With User-Mode-Linux, you can debug the kernel using GDB. See
 246 <!--HREF="http://user-mode-linux.sourceforge.net/debugging.html"-->
 247
 248  http://user-mode-linux.sourceforge.net/debugging.html.</(null)></P>
 249 <P> Typically, one will want to address a test case for a failing
 250  situation. Running GDB from Emacs, or from other front ends is
 251  possible. First start GDB.</P>
 252 <P> Tell it to open the UMLPOOL/swan/linux program.</P>
 253 <P> Note the PID of GDB:</P>
 254 <PRE>
 255 marajade-[projects/freeswan/mgmt/planning] mcr 1029 %ps ax | grep gdb
 256  1659 pts/9    SN     0:00 /usr/bin/gdb -fullname -cd /mara4/freeswan/kernpatch/UMLPOOL/swan/ linux
 257 </PRE>
 258 <P> Set the following in the environment:</P>
 259 <PRE>
 260 UML_east_OPT=&quot;debug gdb-pid=1659&quot;
 261 </PRE>
 262 <P> Then start the user-mode-linux in the test scheme you wish:</P>
 263 <PRE>
 264 marajade-[kernpatch/testing/klips/east-icmp-02] mcr 1220 %../../utils/runme.sh
 265 </PRE>
 266  The user-mode-linux will stop on boot, giving you a chance to attach to
 267  the process:
 268 <PRE>
 269 (gdb) file linux
 270 Reading symbols from linux...done.
 271 (gdb) attach 1
 272 Attaching to program: /mara4/freeswan/kernpatch/UMLPOOL/swan/linux, process 1
 273 0xa0118bc1 in kill () at hostfs_kern.c:770
 274 </PRE>
 275 <P> At this point, break points should be created as appropriate.</P>
 276 <H2><A NAME="35_1">Other notes about debugging</A></H2>
 277 <P> If you are running a standard test, after all the packets are sent,
 278  the UML will be shutdown. This can cause problems, because the UML may
 279  get terminated while you are debugging.</P>
 280 <P> The environment variable <CODE>NETJIGWAITUSER</CODE> can be set to
 281  &quot;waituser&quot;. If so, then the testing system will prompt before exiting
 282  the test.</P>
 283 <H1><A NAME="36">User-Mode-Linux mysteries</A></H1>
 284 <UL>
 285 <LI> running more than one UML of the same name (e.g. &quot;west&quot;) can cause
 286  problems.</LI>
 287 <LI> running more than one UML from the same root file system is not a
 288  good idea.</LI>
 289 <LI> all this means that running &quot;make check&quot; twice on the same machine
 290  is probably not a good idea.</LI>
 291 <LI> occationally, UMLs will get stuck. This can happen like:
 292 <!--BLOCK-->
 293  15134 ? T
 294  0:00 /spare/hugh/uml/uml2.4.18-sept5/umlbuild/east/linux (east)
 295  [/bin/sh] 15138 ? T 0:00
 296  /spare/hugh/uml/uml2.4.18-sept5/umlbuild/east/linux (east) [halt]</(null)>
 297  these will need to be killed. Note that they are in &quot;T&quot;racing mode.</LI>
 298 <LI> UMLs can also hang, and will report &quot;Tracing myself and I can't get
 299  out&quot;. This is a bug in UML. There are ways to find out what is going on
 300  and report this to the UML people, but we don't know the magic right
 301  now.</LI>
 302 </UL>
 303 <H1><A NAME="37">Getting more info from uml_netjig</A></H1>
 304 <P> uml_netjig can be compiled with a built-in tcpdump. This uses
 305  not-yet-released code from<A HREF="http://www.tcpdump.org/">
 306  www.tcpdump.org</A>. Please see the instructions in <CODE>
 307 testing/utils/uml_netjig/Makefile</CODE>.</P>
 308 <HR>
 309 <A HREF="toc.html">Contents</A>
 310 <A HREF="roadmap.html">Previous</A>
 311 <A HREF="makecheck.html">Next</A>
 312 </BODY>
 313 </HTML>