314 lines
13 KiB
HTML
314 lines
13 KiB
HTML
<!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>
|