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
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
|
<html>
<head>
<title>FreeS/WAN "make check" guide</title>
<!-- Changed by: Michael Richardson, 02-Apr-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: makecheck.html,v 1.1 2004/03/15 20:35:24 as Exp $
$Log: makecheck.html,v $
Revision 1.1 2004/03/15 20:35:24 as
added files from freeswan-2.04-x509-1.5.3
Revision 1.25 2003/04/02 20:28:33 mcr
document for NETJIGVERBOSE environment variable.
Revision 1.24 2003/04/02 02:17:52 mcr
added documentation on "PACKETRATE"
Revision 1.23 2003/02/27 09:28:24 mcr
added documentation for *_RUN2_SCRIPT.
Revision 1.22 2003/02/20 20:00:44 mcr
added documentation for ${host}HOST.
Revision 1.21 2003/02/20 19:56:11 mcr
documented new umlXhost test case.
Revision 1.20 2002/12/06 02:11:42 mcr
added new test type, module_compile.
Revision 1.19 2002/12/04 03:47:06 mcr
added documentation of various *TESTDEBUG options in
the testing environment.
Revision 1.18 2002/10/31 19:01:31 mcr
documentation for RUN_*_SCRIPT.
Revision 1.17 2002/09/11 19:43:36 mcr
added documentation on format of TESTLIST.
Revision 1.16 2002/09/11 19:26:48 mcr
renamed umlpluto -> umlplutotest.
Revision 1.15 2002/07/29 22:27:12 mcr
added kernel_patch_test test type.
Revision 1.14 2002/06/19 18:24:44 mcr
renamed SCRIPT to INIT_SCRIPT.
Revision 1.13 2002/06/19 10:06:07 mcr
added nightly.html to the documentation tree.
Revision 1.12 2002/06/19 09:19:26 mcr
wrote documentation for umlpluto parts of makecheck,
and adjusted scripts for consistency.
Revision 1.11 2002/06/19 07:26:31 mcr
added FINAL_SCRIPT to be run after sending packets through.
renamed "SCRIPT" to "INIT_SCRIPT" (left compat variable)
Revision 1.10 2002/06/17 05:40:57 mcr
Added test cases for the "make rpm" machinery.
Revision 1.9 2002/06/08 17:12:49 mcr
added new libtest test type for use in testing libfreeswan
Revision 1.8 2002/05/27 00:19:38 mcr
removed reference to single_netjig.png because mkhtml does not
grok it.
Revision 1.7 2002/05/07 01:31:52 mcr
documented the new "mkinsttest" target type.
Revision 1.6 2002/05/05 23:10:50 mcr
added documentation of $TEST_TYPE variable.
Revision 1.5 2002/04/19 22:48:41 mcr
added documentation on NETJIGDEBUG and CONSOLEDIFFDEBUG.
Revision 1.4 2002/04/01 23:59:46 mcr
added documentation on REF_{PUB,PRIV}_FILTER.
Revision 1.3 2002/04/01 23:38:46 mcr
redo of updates to makecheck
Revision 1.2 2002/03/12 21:12:07 mcr
initial stab at documentation on klips testing infrastructure.
-->
</head>
<body>
<h1><a name="makecheck">How to configure to use "make check"</a></h1>
<H2>What is "make check"</H2>
<p>
"make check" is a target in the top level makefile. It takes care of
running a number of unit and system tests to confirm that FreeSWAN has
been compiled correctly, and that no new bugs have been introduced.
</p>
<p>
As FreeSWAN contains both kernel and userspace components, doing testing
of FreeSWAN requires that the kernel be simulated. This is typically difficult
to do as a kernel requires that it be run on bare hardware. A technology
has emerged that makes this simpler. This is
<A HREF="http://user-mode-linux.sourceforge.net">User Mode Linux</A>.
</p>
<p>
User-Mode Linux is a way to build a Linux kernel such that it can run as a process
under another Linux (or in the future other) kernel. Presently, this can only be
done for 2.4 guest kernels. The host kernel can be 2.2 or 2.4.
</p>
<p>
"make check" expects to be able to build User-Mode Linux kernels with FreeSWAN included.
To do this it needs to have some files downloaded and extracted prior
to running "make check". This is described in the
<A HREF="umltesting.html">UML testing</A> document.
</p>
<p>
After having run the example in the UML testing document and
successfully brought up the four machine combination, you are ready to
use "make check"
</p>
<h2>Running "make check"</h2>
<p>
"make check" works by walking the FreeSWAN source tree invoking the
"check" target at each node. At present there are tests defined only
for the <CODE>klips</CODE> directory. These tests will use the UML
infrastructure to test out pieces of the <CODE>klips</CODE> code.
</p>
<p>
The results of the tests can be recorded. If the environment variable
<CODE>$REGRESSRESULTS</CODE> is non-null, then the results of each
test will be recorded. This can be used as part of a nightly
regression testing system, see
<A HREF="nightly.html">Nightly testing</A> for more details.
</p>
<p>
"make check" otherwise prints a minimal amount of output for each
test, and indicates pass/fail status of each test as they are run.
Failed tests do not cause failure of the target in the form of exit
codes.
</p>
<H1>How to write a "make check" test</H1>
<h2>Structure of a test</h2>
<p>
Each test consists of a set of directories under <CODE>testing/</CODE>.
There are directories for <CODE>klips</CODE>, <CODE>pluto</CODE>, <CODE>packaging</CODE>
and <CODE>libraries</CODE>.
Each directory has a list of tests to run is stored in a file called <CODE>TESTLIST</CODE> in that directory. e.g. <CODE>testing/klips/TESTLIST</CODE>.
</P>
<H2 NAME="TESTLIST">The TESTLIST</H2>
<P>
This isn't actually a shell script. It just looks like one. Some tools other than
/bin/sh process it. Lines that start with # are comments. </P>
<PRE>
# test-kind directory-containing-test expectation [PR#]
</PRE>
<P>The first word provides the test type, detailed below. </P>
<P> The second word is the name of the test to run. This the directory
in which the test case is to be found..</P>
<P>The third word may be one of:
<DL>
<DT> blank/good</DT>
<DD>the test is believed to function, report failure</DD>
<DT> bad</DT>
<DD> the test is known to fail, report unexpected success</DD>
<DT> suspended</DT>
<DD> the test should not be run</DD>
</DL>
<P>
The fourth word may be a number, which is a PR# if the test is
failing.
</P>
<H2>Test kinds</H2>
The test types are:
<DL>
<DT>skiptest</DT>
<DD>means run no test.</DD>
<DT>ctltest</DT>
<DD>means run a single system without input/output.</DD>
<DT>klipstest</DT>
<DD>means run a single system with input/output networks</DD>
<DT><A HREF="#umlplutotest">umlplutotest</A></DT>
<DD>means run a pair of systems</DD>
<DT><A HREF="#umlXhost">umlXhost</A></DT>
<DD>run an arbitrary number of systems</DT>
<DT>suntest (TBD)</DT>
<DD>means run a quad of east/west/sunrise/sunset</DD>
<DT>roadtest (TBD)</DT>
<DD>means run a trio of east-sunrise + warrior</DD>
<DT>extrudedtest (TBD)</DT>
<DD>means run a quad of east-sunrise + warriorsouth + park</DD>
<DT>mkinsttest</TD>
<DD>a test of the "make install" machinery.</DD>
<DT>kernel_test_patch</TD>
<DD>a test of the "make kernelpatch" machinery.</DD>
</DL>
Tests marked (TBD) have yet to be fully defined.
</p>
<p>
Each test directory has a file in it called <CODE>testparams.sh</CODE>.
This file sets a number of environment variables to define the
parameters of the test.
</p>
<H2>Common parameters</H2>
<DL>
<DT>TESTNAME</DT>
<DD>the name of the test (repeated for checking purposes)</DD>
<DT>TEST_TYPE</DT>
<DD>the type of the test (repeat of type type above)</DD>
<DT>TESTHOST</DT>
<DD>the name of the UML machine to run for the test, typically "east"
or "west"</DD>
<DT>TEST_PURPOSE</DT>
<DD>The purpose of the test is one of:
<DL>
<DT>goal</DT>
<DD>The goal purpose is where a test is defined for code that is not yet
finished. The test indicates when the goals have in fact been reached.</DD>
<DT>regress</DT>
<DD>This is a test to determine that a previously existing bug has been repaired. This
test will initially be created to reproduce the bug in isolation, and then the bug will
be fixed.</DD>
<DT>exploit</DT>
<DD>This is a set of packets/programs that causes a vulnerability to be
exposed. It is a specific variation of the regress option.</DD>
</DL>
</DD>
<DT>TEST_GOAL_ITEM<DT>
<DD>in the case of a goal test, this is a reference to the requirements document</DD>
<DT>TEST_PROB_REPORT</DT>
<DD>in the case of regression test, this the problem report number from GNATS</DD>
<DT>TEST_EXPLOIT_URL</DT>
<DD>in the case of an exploit, this is a URL referencing the paper explaining
the origin of the test and the origin of exploit software</DD>
<DT>REF_CONSOLE_OUTPUT</DT>
<DD>a file in the test directory that contains the sanitized console
output against which to compare the output of the actual test.</DD>
<DT>REF_CONSOLE_FIXUPS</DT>
<DD>a list of scripts (found in <CODE>klips/test/fixups</CODE>) to
apply to sanitize the console output of the machine under test.
These are typically perl, awk or sed scripts that remove things in
the kernel output that change each time the test is run and/or
compiled.
</DD>
<DT>INIT_SCRIPT</DT>
<DD><p>a file of commands that is fed into the virtual machine's console
in single user mode prior to starting the tests. This file will
usually set up any eroute's and SADB entries that are required for
the test. </p>
<p>Lines beginning with # are skipped. Blank lines are
skipped. Otherwise, a shell prompted is waited for each time
(consisting of <CODE>\n#</CODE>) and then the command is sent.
Note that the prompt is waited for before the command and not after,
so completion of the last command in the script is not
required. This is often used to invoke a program to monitor the
system, e.g. <CODE>ipsec pf_key</CODE>.
</P>
<DT>RUN_SCRIPT</DT>
<DD><P>a file of commands that is fed into the virtual machine's console
in single user mode, before the packets are sent. On single machine
tests, this script doesn't provide any more power than INIT_SCRIPT,
but is implemented for consistency's sake.</P>
<DT>FINAL_SCRIPT</DT>
<DD><p>a file of commands that is fed into the virtual machine's console
in single user mode after the final packet is sent. Similar to INIT_SCRIPT,
above. If not specified, then the single command "halt" is sent.
If specified, then the script should end with a halt command to
nicely shutdown the UML.
</P>
<DT>CONSOLEDIFFDEBUG</DT>
<DD>If set to "true" then the series of console fixups (see REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should be set to "false", or unset otherwise)</DD>
<DT>NETJIGDEBUG</DT>
<DD>If set to "true" then the series of console fixups (see REF_CONSOLE_FIXUPS) will be output after it is constructed. (It should be set to "false", or unset otherwise)</DD>
<DT>NETJIGTESTDEBUG</DT>
<DD> If set to "netjig", then the results of talking to the <CODE>uml_netjig</CODE>
will be printed to stderr during the test. In addition, the jig will
be invoked with --debug, which causes it to log its process ID, and
wait 60 seconds before continuing. This can be used if you are trying
to debug the <CODE>uml_netjig</CODE> program itself.</DT>
<DT>HOSTTESTDEBUG</DT>
<DD> If set to "hosttest", then the results of taling to the consoles of the UMLs will
be printed to stderr during the test.</DT>
<DT>NETJIGWAITUSER</DT>
<DD> If set to "waituser", then the scripts will wait forever for user
input before they shut the tests down. Use this is if you are
debugging through the kernel.</DD>
<DT>PACKETRATE</DT>
<DD> A number, in miliseconds (default is 500ms) at which packets will
be replayed by the netjig.</DD>
</DL>
<H2>KLIPStest paramaters</H2>
<P>
The klipstest function starts a program
(<CODE>testing/utils/uml_netjig/uml_netjig</CODE>) to
setup a bunch of I/O sockets (that simulate network interfaces). It
then exports the references to these sockets to the environment and
invokes (using system()) a given script. It waits for the script to
finish.
</P>
<!-- <IMG SRC="single_netjig.png" ALT="block diagram of uml_netjig"> -->
<P>
The script invoked (<CODE>testing/utils/host-test.tcl</CODE>) is a TCL
<A HREF="http://expect.nist.gov/">expect</A> script that arranges to start the UML
and configure it appropriately for the test. The configuration is done
with the script given above for <VAR>INIT_SCRIPT</VAR>. The TCL script then forks,
leaves the UML in the background and exits. uml_netjig continues. It then
starts listening to the simulated network answering ARPs and inserting
packets as appropriate.
</P>
<P>
The klipstest function invokes <CODE>uml_netjig</CODE> with arguments
to capture output from network interface(s) and insert packets as
appropriate:
<DL>
<DT>PUB_INPUT</DT>
<DD>a <A HREF="http://www.tcpdump.org/">pcap</A> file to feed in on
the public (encrypted) interface. (typically, eth1)</DD>
<DT>PRIV_INPUT</DT>
<DD>a pcap file to feed in on the private (plain-text) interface
(typically, eth0).</DD>
<DT>REF_PUB_OUTPUT</DT>
<DD>a text file containing tcpdump output. Packets on the public
(eth1) interface are captured to a
<A HREF="http://www.tcpdump.org/">pcap</A> file by
<CODE>uml_netjig</CODE>. The klipstest function then uses tcpdump on
the file to produce text output, which is compared to the file given.</DD>
<DT>REF_PUB_FILTER</DT>
<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD>
<DT>REF_PRIV_OUTPUT</DT>
<DD>a text file containing tcpdump output. Packets on the private
(eth0) interface are captured and compared after conversion by
tcpdump, as with <VAR>REFPUBOUTPUT</VAR>.</DD>
<DT>REF_PRIV_FILTER</DT>
<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD>
<DT>EXITONEMPTY</DT>
<DD>a flag for <CODE>uml_netjig</CODE>. It should contain
"--exitonempty" of uml_netjig should exit when all of the input
(<VAR>PUBINPUT</VAR>,<VAR>PRIVINPUT</VAR>) packets have been injected.</DD>
<DT>ARPREPLY</DT>
<DD>a flag for <CODE>uml_netjig</CODE>. It should contain "--arpreply"
if <CODE>uml_netjig</CODE> should reply to ARP requests. One will
typically set this to avoid having to fudge the ARP cache manually.</DD>
<DT>TCPDUMPFLAGS</DT>
<DD>a set of flags for the tcpdump used when converting captured
output. Typical values will include "-n" to turn off DNS, and often
"-E" to set the decryption key (tcpdump 3.7.1 and higher only) for
ESP packets. The "-t" flag (turn off timestamps) is provided automatically</DD>
<DT>NETJIG_EXTRA</DT>
<DD>additional comments to be sent to the netjig. This may arrange to
record or create additional networks, or may toggle options.
</DL>
<H2>mkinsttest paramaters</H2>
<P>
The basic concept of the <CODE>mkinsttest</CODE> test type is that it
performs a "make install" to a temporary $DESTDIR. The resulting tree can then
be examined to determine if it was done properly. The files can be uninstalled
to determine if the file list was correct, or the contents of files can be
examined more precisely.
</P>
<DL>
<DT>INSTALL_FLAGS</DT>
<DD>If set, then an install will be done. This provides the set of flags to
provide for the install. The target to be used (usually "install") must be
among the flags. </DD>
<DT>POSTINSTALL_SCRIPT</DT>
<DD>If set, a script to run after initial "make install". Two arguments are provided: an absolute path to the root of the FreeSWAN src tree, and an absolute path to the temporary installation area.</DD>
<DT>INSTALL2_FLAGS</DT>
<DD>If set, a second install will be done using these flags. Similarly to
INSTALL_FLAGS, the target must be among the flags. </DD>
<DT>UNINSTALL_FLAGS</DT>
<DD>If set, an uninstall will be done using these flags. Similarly to
INSTALL_FLAGS, the target (usually "uninstall") must be among the flags.</DD>
<DT>REF_FIND_f_l_OUTPUT</DT>
<DD>If set, a <CODE>find $ROOT ( -type f -or -type -l )</CODE> will be done to get a list of a real files and symlinks. The resulting file will be compared
to the file listed by this option.</DD>
<DT>REF_FILE_CONTENTS</DT>
<DD>If set, it should point to a file containing records for the form:
<PRE>
<VARIABLE>reffile</VARIABLE> <VARIABLE>samplefile</VARIABLE>
</PRE>
one record per line. A diff between the provided reference file, and the
sample file (located in the temporary installation root) will be done for
each record.
</DD>
</DL>
<H2>rpm_build_install_test paramaters</H2>
<P>
The <CODE>rpm_build_install_test</CODE> type is to verify that the proper
packing list is produced by "make rpm", and that the mechanisms for
building the kernel modules produce consistent results.
</P>
<DL>
<DT>RPM_KERNEL_SOURCE</DT>
<DD>Point to an extracted copy of the RedHat kernel source code. Variables
from the environment may be used.</DD>
<DT>REF_RPM_CONTENTS</DT>
<DD>This is a file containing one record per line. Each record consists
of a RPM name (may contain wildcards) and a filename to compare the
contents to. The RPM will be located and a file list will be produced with
rpm2cpio.</DD>
</DL>
<H2>libtest paramaters</H2>
<P>
The libtest test is for testing library routines. The library file is
expected to provided an <CODE>#ifdef</CODE> by the name of
<VAR>library</VAR><CODE_MAIN</CODE>.
The libtest type invokes the C compiler to compile this file, links it against
<CODE>libfreeswan.a</CODE> (to resolve any other dependancies) and runs the
test with the <CODE>-r</CODE> argument to invoke a regression test.</P>
<P>The library test case is expected to do a self-test, exiting with status code 0 if everything is okay, and with non-zero otherwise. A core dump (exit code greater than 128) is noted specifically.
</P>
<P>
Unlike other tests, there are no subdirectories required, or other
parameters to set.
</P>
<H2 NAME="umlplutotest">umlplutotest paramaters</H2>
<P>
The umlplutotest function starts a pair of user mode line processes.
This is a 2-host version of umlXhost. The "EAST" and "WEST" slots are defined.
</P>
<H2 NAME="umlXhost">umlXhost parameters</H2>
<P>
The umlXtest function starts an arbitrary number of user mode line processes.
</P>
<!-- <IMG SRC="single_netjig.png" ALT="block diagram of uml_netjig"> -->
<P>
The script invoked (<CODE>testing/utils/Xhost-test.tcl</CODE>) is a TCL
<A HREF="http://expect.nist.gov/">expect</A> script that arranges to start each
UML
and configure it appropriately for the test. It then starts listening
(using uml_netjig) to the simulated network answering ARPs and
inserting packets as appropriate.
</P>
<P>
umlXtest has a series of slots, each of which should be filled by a host.
The list of slots is controlled by the variable, XHOST_LIST. This variable
should be set to a space seperated list of slots. The former umlplutotest
is now implemented as a variation of the umlXhost test,
with XHOST_LIST="EAST WEST".
</P>
<P>
For each host slot that is defined, a series of variables should be
filled in, defining what configuration scripts to use for that host.
</P>
<P>
The following are used to control the console input and output to the system.
Where the string ${host} is present, the host slot should be filled in.
I.e. for the two host system with XHOST_LIST="EAST WEST", then the
variables: EAST_INIT_SCRIPT and WEST_INIT_SCRIPT will exist.
<DL>
<DT>${host}HOST</DT>
<DD>The name of the UML host which will fill this slot</DD>
<DT>${host}_INIT_SCRIPT</DT>
<DD><p>a file of commands that is fed into the virtual machine's console
in single user mode prior to starting the tests. This file will
usually set up any eroute's and SADB entries that are required for
the test. Similar to INIT_SCRIPT, above.</p>
<DT>${host}_RUN_SCRIPT</DT>
<DD><P>a file of commands that is fed into the virtual machine's console
in single user mode, before the packets are sent. This set of
commands is run after all of the virtual machines are initialized.
I.e. after EAST_INIT_SCRIPT <B>AND</B> WEST_INIT_SCRIPT. This script
can therefore do things that require that all machines are properly
configured.</P>
<DT>${host}_RUN2_SCRIPT</DT>
<DD><P>a file of commands that is fed into the virtual machine's console
in single user mode, after the packets are sent. This set of
commands is run before any of the virtual machines have been shut
down. (I.e. before EAST_FINAL_SCRIPT <B>AND</B> WEST_FINAL_SCRIPT.)
This script can therefore catch post-activity status reports.</P>
<DT>${host}_FINAL_SCRIPT</DT>
<DD><p>a file of commands that is fed into the virtual machine's console
in single user mode after the final packet is sent. Similar to INIT_SCRIPT,
above. If not specified, then the single command "halt" is sent. Note that
when this script is run, the other virtual machines may already have been killed.
If specified, then the script should end with a halt command to nicely
shutdown the UML.
</P>
<DT>REF_${host}_CONSOLE_OUTPUT</DT>
<DD>Similar to REF_CONSOLE_OUTPUT, above.</DT>
</DL>
</P>
<P>Some additional flags apply to all hosts:
<DL>
<DT>REF_CONSOLE_FIXUPS</DT>
<DD>a list of scripts (found in <CODE>klips/test/fixups</CODE>) to
apply to sanitize the console output of the machine under test.
These are typically perl, awk or sed scripts that remove things in
the kernel output that change each time the test is run and/or
compiled.
</DD>
</DL>
</P>
<P> In addition to input to the console, the networks may have input
fed to them:
<DL>
<DT>EAST_INPUT/WEST_INPUT</DT>
<DD>a <A HREF="http://www.tcpdump.org/">pcap</A> file to feed in on
the private network side of each network. The "EAST" and "WEST" here
refer to the networks, not the hosts.</DD>
<DT>REF_PUB_FILTER</DT>
<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD>
<DT>REF_EAST_FILTER/REF_WEST_FILTER</DT>
<DD>a program that will filter the TCPDUMP output to do further processing. Defaults to "cat".</DD><
<DT>TCPDUMPFLAGS</DT>
<DD>a set of flags for the tcpdump used when converting captured
output. Typical values will include "-n" to turn off DNS, and often
"-E" to set the decryption key (tcpdump 3.7.1 and higher only) for
ESP packets. The "-t" flag (turn off timestamps) is provided automatically</DD>
<DT>REF_EAST_OUTPUT/REF_WEST_OUTPUT</DT>
<DD>a text file containing tcpdump output. Packets on the private
(eth0) interface are captured and compared after conversion by
tcpdump, as with <VAR>REF_PUB_OUTPUT</VAR>.</DD>
</P>
<P>
There are two additional environment variables that may be set on the
command line:
<DL>
<DT> NETJIGVERBOSE=verbose export NETJIGVERBOSE</DT>
<DD> If set, then the test output will be "chatty", and let you know what
commands it is running, and as packets are sent. Without it set, the
output is limited to success/failure messages.</DD>
<DT> NETJIGTESTDEBUG=netjig export NETJIGTESTDEBUG</DT>
<DD> This will enable debugging of the communication with uml_netjig,
and turn on debugging in this utility.
This does not imply NETJIGVERBOSE.</DL>
<DT> HOSTTESTDEBUG=hosttest export HOSTTESTDEBUG</DT>
<DD> This will show all interactions with the user-mode-linux
consoles</DD>
</DL>
</P>
<H2 NAME="kernelpatch">kernel_patch_test paramaters</H2>
<P>
The kernel_patch_test function takes some kernel source, copies it with
lndir, and then applies the patch as produced by "make kernelpatch".
</P>
<P>
The following are used to control the input and output to the system:
<DL>
<DT>KERNEL_NAME</DT>
<DD>the kernel name, typically something like "linus" or "rh"</DD>
<DT>KERNEL_VERSION</DT>
<DD>the kernel version number, as in "2.2" or "2.4".</DD>
<DT>KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC</DT>
<DD>This variable should set in the environment, probably in
~/freeswan-regress-env.sh. Examples of this variables would be
KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point
to an extracted copy of the kernel source in question.</DD>
<DT>REF_PATCH_OUTPUT</DT>
<DD>a copy of the patch output to compare against</DD>
<DT>KERNEL_PATCH_LEAVE_SOURCE</DT>
<DD>If set to a non-empty string, then the patched kernel source is not
removed at the end of the test. This will typically be set in the
environment while debugging.</DD>
</DL>
</P>
<H2 NAME="modtest">module_compile paramaters</H2>
<P>
The module_compile test attempts to build the KLIPS module against a
given set of kernel source. This is also done by the RPM tests, but
in a very specific manner.
</P>
<P>
There are two variations of this test - one where the kernel either
doesn't need to be configured, or is already done, and tests were there
is a local configuration file.
</P>
<P>
Where the kernel doesn't need to be configured, the kernel source that
is found is simply used. It may be a RedHat-style kernel, where one
can cause it to configure itself via rhconfig.h-style definitions. Or,
it may just be a kernel tree that has been configured.
</P>
<P>
If the variable KERNEL_CONFIG_FILE is set, then a new directory is
created for the kernel source. It is populated with lndir(1). The referenced
file is then copied in as .config, and "make oldconfig" is used to configure
the kernel. This resulting kernel is then used as the reference source.
</P>
<p>
In all cases, the kernel source is found the same was for the kernelpatch
test, i.e. via KERNEL_VERSION/KERNEL_NAME and KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC.</P>
<P>
Once there is kernel source, the module is compiled using the top-level
"make module" target.
</P>
<P>
The test is considered successful if an executable is found in OUTPUT/module/ipsec.o at the end of the test.
</P>
<DL>
<DT>KERNEL_NAME</DT>
<DD>the kernel name, typically something like "linus" or "rh"</DD>
<DT>KERNEL_VERSION</DT>
<DD>the kernel version number, as in "2.2" or "2.4".</DD>
<DT>KERNEL_${KERNEL_NAME}${KERNEL_VERSION}_SRC</DT>
<DD>This variable should set in the environment, probably in
~/freeswan-regress-env.sh. Examples of this variables would be
KERNEL_LINUS2_0_SRC or KERNEL_RH7_3_SRC. This variable should point
to an extracted copy of the kernel source in question.</DD>
<DT>KERNEL_CONFIG_FILE</DT>
<DD>The configuration file for the kernel.</DD>
<DT>KERNEL_PATCH_LEAVE_SOURCE</DT>
<DD>If set to a non-empty string, then the configured kernel source is not
removed at the end of the test. This will typically be set in the
environment while debugging.</DD>
<DT>MODULE_DEF_INCLUDE</DT>
<DD>The include file that will be used to configure the KLIPS module, and
possibly the kernel source. </DD>
</DL>
<H1>Current pitfalls</H1>
<DL>
<DT> "tcpdump dissector" not available. </DT>
<DD> This is a non-fatal warning. If uml_netjig is invoked with the -t
option, then it will attempt to use tcpdump's dissector to decode
each packet that it processes. The dissector is presently not
available, so this option it normally turned off at compile time.
The dissector library will be released with tcpdump version
4.0.</DD>
</DL>
</body>
</html>
|
