1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
|
<html>
<head>
<title>FreeS/WAN User-Mode-Linux testing guide</title>
<!-- Changed by: Michael Richardson, 05-Mar-2003 -->
<meta name="keywords" content="Linux, IPsec, VPN, security, FreeSWAN, testing, User-Mode-Linux, UML">
<!--
Written by Michael Richardson for the Linux FreeS/WAN project
Freely distributable under the GNU General Public License
More information at www.freeswan.org
Feedback to users@lists.freeswan.org
$Id: umltesting.html,v 1.1 2004/03/15 20:35:24 as Exp $
$Log: umltesting.html,v $
Revision 1.1 2004/03/15 20:35:24 as
added files from freeswan-2.04-x509-1.5.3
Revision 1.23 2003/09/18 15:12:11 dhr
fix link to kernel.org mirrors page
Revision 1.22 2003/03/07 03:49:25 dhr
fix recommended version of uml-patch
Revision 1.21 2003/03/06 08:37:03 dhr
capture more of MCR's knowledge about BIND
Revision 1.20 2003/03/06 02:15:44 mcr
added note about need for bind9.
Revision 1.19 2003/03/05 23:20:39 mcr
updates from -47 to -53.
Revision 1.18 2003/02/27 08:25:48 dhr
update to reflect newer umlfreeroot
Revision 1.17 2003/02/27 08:16:45 dhr
make clear what is the latest version of the UML patch that we've used
Revision 1.16 2003/02/21 01:35:31 mcr
updated latest umlfreeroot to 15.1.
Revision 1.15 2003/01/21 03:26:34 mcr
updated documentation on UML state.
Revision 1.14 2002/11/11 16:43:35 mcr
adjusted formatting of uml_netjig notes.
Revision 1.13 2002/11/08 10:13:05 mcr
updated documentation for 2.4.19
Revision 1.12 2002/11/03 23:44:23 mcr
fixed some formatting in umltesting.html
added some notes about NETJIGWAITUSER re: having tests
prompt before they exit. Helps with debugging.
Revision 1.11 2002/10/31 19:01:31 mcr
documentation for RUN_*_SCRIPT.
Revision 1.10 2002/09/15 23:57:59 dhr
update suggested umlfreeroot
Revision 1.9 2002/09/15 19:28:05 mcr
added some comments about problems with UMLs.
Revision 1.8 2002/09/11 20:00:25 mcr
updated umlroot rev to 8.0.
Revision 1.7 2002/09/09 21:37:43 mcr
updated document to reference currently working kernel+UML.
Revision 1.6 2002/08/02 22:43:35 mcr
added section on debugging with UMLs.
Revision 1.5 2002/05/30 18:47:57 dhr
Update from experience:
- fixed HTML bugs
- restructure slightly
- added another intro paragraph
- mentioned lack of Super User requirements
- added tcpdump build and install procedure
- added uml utils build procedure
- added invitation to try "make check"
- fixed minor typos and mistakes
Revision 1.4 2002/03/12 21:10:37 mcr
removed instruction on downloading umlminishare, as this is
now simply included in umlrootXXX. reformated some other text.
Revision 1.3 2002/01/29 02:21:21 mcr
updated instructions for 2.4.17, and for newest UMLroot.
Revision 1.2 2001/11/27 05:24:09 mcr
added reference to uml-rhroot, but commented out.
This proceedure is not yet ready for prime time.
Revision 1.1 2001/11/05 04:35:57 mcr
adapted text from design list posting into HTML for Sandy.
-->
</head>
<body>
<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>Preliminary Notes on BIND</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>Steps to Install UML for FreeS/WAN</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> 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> 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>
<!-- 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> 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>
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.
</OL>
<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> 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> 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>
</OL>
<LI> If you need to build a newer tcpdump:
<UL>
<LI>
Make sure you have OpenSSL installed -- it is needed for cryptographic routines.
<LI>
Unpack libpcap and tcpdump source in parallel directories (the tcpdump
build procedures look for libpcap next door).
<LI>
Change directory into the libpcap source directory and then build the library:
<PRE>
<CODE>
./configure
make
</CODE>
</PRE>
<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>
</UL>
<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> set up the configuration file
<UL>
<LI>
<CODE>
cd /c2/freeswan/sandbox/freeswan-1.97/testing/utils
</CODE>
<LI> copy umlsetup-sample.sh to ../../umlsetup.sh:
<CODE>
cp umlsetup-sample.sh ../../umlsetup.sh
</CODE>
<LI> open up ../../umlsetup.sh in your favorite editor.
<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> Set TESTINGROOT if you intend to run the script outside of the
sandbox/snapshot/release directory. Otherwise, it will configure itself.
<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> 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> 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> BASICROOT should be set to the directory used in 2b, or to the directory
that you created with RPMs.
<LI> SHAREDIR should be set to the directory used in 2c, to /usr/share
for Debian potato users, or to $BASICROOT/usr/share.
</UL>
<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> 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> 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> verify that pluto started on east/west, run "ipsec look"
<LI> login to sunrise. run "ping sunset"
<LI> login to west. run "tcpdump -p -i eth1 -n"
(tcpdump must be version 3.7.1 or newer)
<LI> Closing a console xterm will shut down that UML.
<LI> You can "make check", if you want to.
It is run from /c2/freeswan/sandbox/freeswan-1.97.</LI>
</OL>
<H1>Debugging the kernel with GDB</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</A>.
</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:
<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>
<P>
Set the following in the environment:
<PRE>
UML_east_OPT="debug gdb-pid=1659"
</PRE>
</P>
<P>
Then start the user-mode-linux in the test scheme you wish:
<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>Other notes about debugging</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>User-Mode-Linux mysteries</H1>
<UL>
<LI> running more than one UML of the same name (e.g. "west") can cause
problems.
<LI> running more than one UML from the same root file system is not
a good idea.
<LI> all this means that running "make check" twice on the same machine
is probably not a good idea.
<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]
</BLOCK>
these will need to be killed. Note that they are in "T"racing mode.
<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.
</UL>
<H1>Getting more info from uml_netjig</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>
</body>
</html>
|
