-*- emacs-wiki -*-

                         User-Mode-Linux Testing guide

   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 http://user-mode-linux.sourceforge.net/

   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.

   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.

   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.

Preliminary Notes on BIND

   As of 2005/10/31, the Light-Weight Resolver is used by pluto. This
   requires that BIND9 be running. Since previous versions, the bind9.3
   has been released and is therefore far more likely to be available. To
   make sure that we have appropriate libraries, we have actually
   imported the relevant code from bind 9.3.

Steps to Install UML for Openswan

    1. Get the following files:

         a. from rsync://anoncvs.openswan.org/rootfstar/
            umlswanroot-26.tar.gz (or highest numbered one). This is
            originally a debian potato root file system, but has many
            upgrades and should work on any recent (debian sarge, FC4,
            etc.).

         b. From ftp://ftp.xs4all.nl/pub/crypto/freeswan/ a snapshot or
            release (1.92 or better)

         c. From a http://www.kernel.org mirror, 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 freeswan-regress-env.sh.

         d. Get http://ftp.nl.linux.org/uml/ uml-patch-2.4.30-1.bz2 or
            the one associated with your kernel. For 2.6 kernels after
            2.6.10, you do not need any patches. We have tested up to
            2.6.13. More recent versions of the patch have not been
            tested by us.

         e. You'll probably want to visit
            http://user-mode-linux.sourceforge.net 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.

         f. 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 http://www.tcpdump.org/ or a
            mirror.

    2. Pick a suitable place, and extract the following files:

         a. 2.4.31 kernel. For instance:

           cd /c2/kernel
           tar xzvf ../download/pub/linux/kernel/v2.4/linux-2.4.31.tar.gz

	   As of 2005-11-20, you can now use a torvalds GIT tree!

         b. extract the umlswanroot file

           mkdir -p /c2/user-mode-linux/basic-root
           cd /c2/user-mode-linux/basic-root
           tar xzvf ../download/umlswanroot-15.1.tar.gz

         c. Openswan itself (or checkout "openswan-2" from CVS)

           mkdir -p /c2/openswan/sandbox
           cd /c2/openswan/sandbox
           tar xzvf ../download/openswan-2.4.2dr2.tar.gz

    3. If you need to build a newer tcpdump:
          + Make sure you have OpenSSL installed -- it is needed for
            cryptographic routines.
          + Unpack libpcap and tcpdump source in parallel directories
            (the tcpdump build procedures look for libpcap next door).
          + Change directory into the libpcap source directory and then
            build the library:

        ./configure
        make

          + Change into the tcpdump source directory, build tcpdump, and
            install it.

        ./configure
        make
        # Need to be superuser to install in system directories.
        # Installing in ~/bin would be an alternative.
        su -c "make install"

    4. If you need the uml utilities, unpack them somewhere then build
       and install them:

        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"

    5. set up the configuration file
          + cd /c2/freeswan/sandbox/openswanswan-2.4.2dr2/testing/utils
          + copy umlsetup-sample.sh to ../../umlsetup.sh: cp
            umlsetup-sample.sh ../../umlsetup.sh
	
          + open up ../../umlsetup.sh in your favorite editor.
            See notes on [[UmlSetup]]

          + 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.
          + Set TESTINGROOT if you intend to run the script outside of
            the sandbox/snapshot/release directory. Otherwise, it will
            configure itself.
          + 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.
          + 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.
          + 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.
          + BASICROOT should be set to the directory used in 2b, or to
            the directory that you created with RPMs.
          + SHAREDIR should be set to the directory used in 2c, to
            /usr/share for Debian potato users, or to
            $BASICROOT/usr/share.

    6. make uml
       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.
    7. You will have a bunch of stuff under $POOLSPACE. Open four xterms:

    for i in sunrise sunset east west
    do
        xterm -name $i -title $i -e $POOLSPACE/$i/start.sh &
    done

    8. 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.)

    9. verify that pluto started on east/west, run "ipsec look"

   10. login to sunrise. run "ping sunset"

   11. login to west. run "tcpdump -p -i eth1 -n" (tcpdump must be
       version 3.7.1 or newer)

   12. Closing a console xterm will shut down that UML.

   13. You can "make check", if you want to. It is run from
       /c2/freeswan/sandbox/freeswan-1.97.

                         Debugging the kernel with GDB

   With User-Mode-Linux, you can debug the kernel using GDB. See
   http://user-mode-linux.sourceforge.net/debugging.html
   .

   Typically, one will want to address a test case for a failing
   situation. Running GDB from Emacs, or from other front ends is
   possible. 

   Start up your environment as you would normally.
   Start up GDB under Xemacs,etc. and give it the "linux" executable as the
 program to debug.

   Find out the primary PID of the UMLs that you want to debug:

   % cat ~/.uml/east/pid
   1659

   Attach to this PID with GDB:
   gdb> attach 1659

   UML users two signals to help it emulate a memory management unit,
and this will confuse gdb.  Tell gdb to ignore them:

   gdb> handle SIGUSR1 noprint nostop
   gdb> handle SIGSEGV noprint nostop

   (the above is good content for your .gdbinit file)

   At this point, break points should be created as appropriate.

Other notes about debugging

   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.

   The environment variable NETJIGWAITUSER can be set to "waituser". If
   so, then the testing system will prompt before exiting the test.

   The environment variable UML_GETTY if set, will cause each UML to
   spawn a getty on /dev/tty1, and will wait for it to exit before
   continuing.

   The environment variable UML_SLEEP can be set to some shell code. It
   will be invoked at the end of each UML run. In general, this is used
   in interactive UML use, so that the window in which the UML was
   running won't close immediately. While a good value should be: "echo
   press enter; read ans", something about the way the UML exits when it
   panics (oops) means that the tty is too broken for this to work, so
   use "sleep 180" instead.

                           User-Mode-Linux mysteries

     * running more than one UML of the same name (e.g. "west") can cause
       problems.
     * running more than one UML from the same root file system is not a
       good idea.
     * all this means that running "make check" twice on the same machine
       is probably not a good idea.
     * occationally, UMLs will get stuck. This can happen like: 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]
       these will need to be killed. Note that they are in "T"racing
       mode.
     * 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.

                       Getting more info from uml_netjig

   uml_netjig can be compiled with a built-in tcpdump. This uses
   not-yet-released code from www.tcpdump.org. Please see the
   instructions in testing/utils/uml_netjig/Makefile.
