]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
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 "zombies" (most will actually be in | |
46 | the "T" 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 "make check". 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 "all" 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 "make install" | |
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 "make install BIN_DIR=/usr/local/bin" | |
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 "umlfreeroot" | |
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 "freeswan-snap2001sep16b" 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 "script" 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 "root" (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 "ipsec look"</LI> | |
237 | <LI> login to sunrise. run "ping sunset"</LI> | |
238 | <LI> login to west. run "tcpdump -p -i eth1 -n" (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 "make check", 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="debug gdb-pid=1659" | |
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 | "waituser". 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. "west") 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 "make check" 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 "T"racing mode.</LI> | |
298 | <LI> UMLs can also hang, and will report "Tracing myself and I can't get | |
299 | out". 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> |