typo
[exim.git] / test / README
1 EXPORTABLE EXIM TEST SUITE
2 --------------------------
3
4 This document last updated for:
5
6 Test Suite Version: 4.87
7 Date: 30 January 2016
8
9
10 BACKGROUND
11 ----------
12
13 For a long time, the Exim test suite was confined to Philip Hazel's
14 workstation, because it relied on that particular environment. The problem is
15 that an MTA such as Exim interacts a great deal with its environment, so if you
16 run it somewhere else, the output will be different, which makes automatic
17 checking difficult. Even in a single environment, things are not all that easy.
18 For instance, if Exim delivers a message, the log line (which one would want to
19 compare) contains a timestamp and an Exim message id that will be different
20 each time. This issue is dealt with by a Perl script that munges the output by
21 recognizing changing sequences and replacing them with fixed values before
22 doing a comparison. Another problem with exporting the original test suite is
23 that it assumes a version of Exim with more or less every optional feature
24 enabled.
25
26 This README describes a new test suite that is intended to be exportable and to
27 run in a number of different environments. The tests themselves are in no
28 particular order; they accumulated over the years as Exim was extended and
29 modified. They vary greatly in size and complexity. Some were specifically
30 constructed to test new features; others were made to demonstrate that a bug
31 had been fixed.
32
33 A few of the original tests have had to be omitted from this more general
34 suite because differences in operating system behaviour make it impossible to
35 generalize them. An example is a test that uses a version of Exim that is
36 setuid to the Exim user rather than root, with the deliver_drop_privilege
37 option set. In Linux, such a binary is able to deliver a message as the caller
38 of Exim, because it can revert to the caller's uid. In FreeBSD this is not the
39 case.
40
41
42 REQUIREMENTS
43 ------------
44
45 In order to run this test suite, the following requirements must be met:
46
47 (1) You should run the tests on a matching version of Exim, because the suite
48     is continuously updated to test the latest features and bug fixes. The
49     version you test does not, however, have to be installed as the live
50     version. You can of course try the tests on any version of Exim, but some
51     may fail. In particular, the test suite will fall apart horrible with
52     versions of Exim prior to 4.54.
53
54 (2) You can use any non-root login to run the tests, but there must be access
55     via "sudo" to root from this login. Privilege is required to override
56     configuration change checks and for things like cleaning up spool files,
57     but on the other hand, the tests themselves need to call Exim from a
58     non-root process. The use of "sudo" is the easiest way to achieve all this.
59     The test script uses "sudo" to do a number of things as root, so it is best
60     if you set a sudo timeout so that you do not have to keep typing a
61     password. For example, if you put
62
63       Defaults timestamp_timeout=480
64
65     in /etc/sudoers, a password lasts for 8 hours (a working day). It is
66     not permitted to run the tests as the Exim user because the test suite
67     tracks the two users independently.  Using the same user would result
68     in false positives on some tests.
69
70     Further, some tests invoke sudo in an environment where there might not be
71     a TTY, so tickets should be global, not per-TTY.  Taking this all together
72     and assuming a user of "exim-build", you might have this in sudoers:
73
74       Defaults:exim-build     timestamp_timeout=480,!tty_tickets
75
76 (3) The login under which you run the tests must have the exim group as a
77     secondary so that it has access to logs, spool files, etc.  However, it
78     should have a different primary group (eg. "users" vs. "eximgroup"). The
79     login should not be one of the names "userx", "usery", "userz", or a few
80     other simple ones such as "abcd" and "xyz" and single letters that are used
81     in the tests. The test suite expects the login to have a gecos name; I think
82     it will now run if the gecos field is empty but there may be anomalies.
83     The login must not contain a dash or an equal sign. (Otherwise some tests
84     about local_from_{suffix,prefix} will fail.)
85
86 (4) The directory into which you unpack the test suite must be accessible by
87     the Exim user, so that code running as exim can access the files therein.
88     This includes search-access on all path elements leading to it. A
89     world-readable directory is fine. However, there may be problems if the
90     path name of the directory is excessively long. This is because it
91     sometimes appears in log lines or debug output, and if it is truncated, it
92     is no longer recognized.
93
94 (5) Exim must be built with its user and group specified at build time, and
95     with certain minimum facilities, namely:
96
97       Routers:        accept, dnslookup, manualroute, redirect
98       Transports:     appendfile, autoreply, pipe, smtp
99       Lookups:        lsearch
100       Authenticators: plaintext
101
102     Most Exim binaries will have these included.
103
104 (6) A C compiler is needed to build some test programs, and the test script is
105     written in Perl, so you need that.
106
107 (7) Some of the tests run Exim as a daemon, and others use a testing server
108     (described below). These require TCP ports. In the configurations and
109     scripts, the ports are parameterized, but at present, fixed values are
110     written into the controlling script. These are ports 1224 to 1229. If these
111     ports are not available for use, some of the tests will fail.
112
113 (8) There is an underlying assumption that the host on which the tests are
114     being run has an IPv4 address (which the test script seeks out). If there
115     is also an IPv6 address, additional tests are run when the Exim binary
116     contains IPv6 support. There are checks in the scripts for a running IPv4
117     interface; when one is not found, some tests are skipped (with a warning
118     message).  The local net may not be in 10.250.0/16 as that is used by the suite.
119
120 (9) Exim must be built with TRUSTED_CONFIG_LIST support, so that the test
121     configs can be placed into it.  A suitable file location is .../exim/test/trusted_configs
122     with content .../exim/test/test-config [fill out the ... to make full
123     paths].  This file should be owner/group matching CONFIGURE_OWNER/GROUP,
124     or root/root, and it has to be accessible for the login, under which
125     you run the tests.  The config files in .../exim/test/confs/ should be
126     owner/group the same.  DISABLE_D_OPTION must not be used. If ALT_CONFIG_PREFIX is used, it
127     must contain the directory of the test-suite.  WHITELIST_D_MACROS should contain:
128
129      DIR:EXIM_PATH:AA:ACL:ACLRCPT:ACL_MAIL:ACL_PREDATA:ACL_RCPT:AFFIX:ALLOW:ARG1:ARG2:AUTHF:AUTHS:AUTH_ID_DOMAIN:BAD:BANNER:BB:BR:BRB:CERT:COM:COMMAND_USER:CONNECTCOND:CONTROL:CREQCIP:CREQMAC:CRL:CSS:D6:DATA:DCF:DDF:DEFAULTDWC:DELAY:DETAILS:DRATELIMIT:DYNAMIC_OPTION:ELI:ERROR_DETAILS:ERT:FAKE:FALLBACK:FILTER:FILTER_PREPEND_HOME:FORBID:FORBID_SMTP_CODE:FUSER:HAI:HAP:HARDLIMIT:HEADER_LINE_MAXSIZE:HEADER_MAXSIZE:HELO_MSG:HL:HOSTS:HOSTS_AVOID_TLS:HOSTS_MAX_TRY:HVH:IFACE:IGNORE_QUOTA:INC:INSERT:IP1:IP2:LAST:LDAPSERVERS:LENCHECK:LIMIT:LIST:LOG_SELECTOR:MAXNM:MESSAGE_LOGS:MSIZE:NOTDAEMON:ONCE:ONLY:OPT:OPTION:ORDER:PAH:PEX:PORT:PTBC:QDG:QOLL:QUOTA:QUOTA_FILECOUNT:QWM:RCPT_MSG:REMEMBER:REQUIRE:RETRY:RETRY1:RETRY2:RETURN:RETURN_ERROR_DETAILS:REWRITE:ROUTE_DATA:RRATELIMIT:SELECTOR:SELF:SERVER:SERVERS:SREQCIP:SREQMAC:SRV:STRICT:SUB:SUBMISSION_OPTIONS:TIMEOUTDEFER:TIMES:TRUSTED:TRYCLEAR:UL:USE_SENDER:UTF8:VALUE:WMF
130
131 (10) Exim must *not* be built with USE_READLINE, as the test-suite's automation
132      assumes the simpler I/O model.
133      Exim must *not* be built with HEADERS_CHARSET set to UTF-8.
134
135
136
137 OPTIONAL EXTRAS
138 ---------------
139
140 If the Exim binary that is being tested contains extra functionality in
141 addition to the minimum specified above, additional tests are run to exercise
142 the extra functionality, except for a few special cases such as the databases
143 (MySQL, PostgreSQL, LDAP) where special data is needed for the tests.
144
145
146 RUNNING THE TEST SUITE
147 ----------------------
148
149 (1) Clone the git tree for Exim.  This include both the Exim source and the
150     testsuite.
151
152 (2) cd into the test/ subdirectory (where this README lives).
153
154 (3) Run "./configure" and then "make". This builds a few auxiliary programs that
155     are written in C.
156
157 (4) echo $PWD/test-config >> your_TRUSTED_CONFIG_LIST_filename
158     Typically that is .../exim/test/trusted_configs
159
160 (5) Run "./runtest" (a Perl script) as described below.
161
162 (6) If you want to see what tests are available, run "./listtests".
163
164
165 BREAKING OUT OF THE TEST SCRIPT
166 -------------------------------
167
168 If you abandon the test run by typing ^C, the interrupt may be passed to a
169 program that the script is running, or it may be passed to the script itself.
170 In the former case, the script should detect that the program has ended
171 abnormally. In both cases, the script tries to clean up everything, including
172 killing any Exim daemons that it has started. However, there may be race
173 conditions in which the clean up does not happen. If, after breaking out of a
174 run, you see strange errors in the next run, look for any left-over Exim
175 daemons, and kill them by hand.
176
177
178 THE LISTTESTS SCRIPT
179 --------------------
180
181 The individual test scripts are in subdirectories of the "scripts" directory.
182 If you do not supply any arguments to ./listtests, it scans all the scripts in
183 all the directories, and outputs the heading line from each script. The output
184 is piped through "less", and begins like this:
185
186 === 0000-Basic ===
187 Basic/0001 Basic configuration setting
188 Basic/0002 Common string expansions
189 Basic/0003 Caseless address blocking
190 ...
191
192 Lines that start === give the name of the subdirectory containing the test
193 scripts that follow. If you supply an argument to ./listtests, it is used as a
194 Perl pattern to match case-independently against the names of the
195 subdirectories. Only those that match are scanned. For example, "./listtests
196 ipv6" outputs this:
197
198 === 1000-Basic-ipv6 ===
199 === Requires: support IPv6
200 Basic-ipv6/1000 -bh and non-canonical IPv6 addresses
201 Basic-ipv6/1001 recognizing IPv6 address in HELO/EHLO
202
203 === 2250-dnsdb-ipv6 ===
204 === Requires: support IPv6
205               lookup dnsdb
206 dnsdb-ipv6/2250 dnsdb ipv6 lookup in string expansions
207
208 If you supply a second argument to ./listtests, it is used as a Perl pattern to
209 match case-independently against the individual script titles. For example,
210 "./listtests . mx" lists all tests whose titles contain "mx", because "."
211 matches all the subdirectory names.
212
213
214 THE RUNTEST SCRIPT
215 ------------------
216
217 If you do not supply any arguments to ./runtest, it searches for an Exim
218 source tree at the same level as the test suite directory. A source tree
219 is a source tree, if it contains a build-* directory.
220
221 It then looks for an Exim binary in a "build" directory of that source
222 tree. If there are several Exim source trees, it chooses the latest
223 version of Exim. Consider the following example:
224
225   $ ls -F /source/exim
226   exim-4.60/  exim-4.62/  exim-testsuite-x.xx/
227
228 A simple ./runtest from within the test suite will use a 4.62 binary if it
229 finds one, otherwise a 4.60 binary. If a binary cannot be found, the script
230 prompts for one. Alternatively, you can supply the binary on the command line:
231
232   ./runtest /usr/exim/bin/exim
233
234 A matching test suite is released with each Exim release; if you use a test
235 suite that does not match the binary, some tests may fail.
236
237 The test suite uses some of the Exim utilities (such as exim_dbmbuild), and it
238 expects to find them in the same directory as Exim itself. If they are not
239 found, the tests that use them are omitted. A suitable comment is output.
240
241 On the ./runtest command line, following the name of the binary, if present,
242 there may be a number of options and then one or two numbers. The full syntax
243 is as follows:
244
245   ./runtest [binary name] [runtest options] [exim options] \
246             [first test] [last test]
247
248 There are some options for the ./runtest script itself:
249
250   -CONTINUE This will allow the script to move past some failing tests. It will
251             write a simple failure line with the test number in a temporary
252             logfile test/failed-summary.log. Unexpected exit codes will still
253             stall the test execution and require interaction.
254
255   -DEBUG    This option is for debugging the test script. It causes some
256             tracing information to be output.
257
258   -DIFF     By default, file comparisons are done using a private compare
259             command called "cf", which is built from source that is provided in
260             the src directory. This is a command I've had for nearly 20 years -
261             look at the source comments for its history - whose output I
262             prefer. However, if you want to use "diff" instead, give -DIFF as a
263             runtest option. In that case, "diff -u" is used for comparisons.
264             (If it turns out that most people prefer to use diff, I'll change
265             the default.)
266
267   -FLAVOR <flavor>
268   -FLAVOUR <flavour>
269             This allows "overrides" for the test results. It's intended
270             use is to deal with distro specific differences in the test
271             output. The default flavour is "FOO" if autodetection fails.
272             (Autodetection is possible for known flavours only. Known
273             flavours are computed after file name extensions in stdout/*
274             and stderr/*.)
275
276             If during the test run differences between the current and
277             the expected output are found and no flavour file exists already,
278             you may update the "common" expected output or you may create a
279             flavour file. If  a flavour file already exists, any updates will go
280             into that flavour file!
281
282   -KEEP     Normally, after a successful run, the test output files are
283             deleted. This option prevents this. It is useful when running a
284             single test, in order to look at the actual output before it is
285             modified for comparison with saved output.
286
287   -NOIPV4   Pretend that an IPv4 interface was not found. This is useful for
288             testing that the test suite correctly skips tests that require
289             a running IPv4 interface.
290
291   -NOIPV6   Pretend that an IPv6 interface was not found. This is useful for
292             testing that the test suite correctly skips tests that require
293             a running IPv6 interface.
294
295   -UPDATE   If this option is set, any detected changes in test output are
296             automatically accepted and used to update the stored copies of the
297             output. It is a dangerous option, but it useful for the test suite
298             maintainer after making a change to the code that affects a lot of
299             tests (for example, the wording of a message).
300
301   -SLOW     For very slow hosts that appear to have Heisenbugs, delay before
302             comparing output files from a testcase
303
304   -TLS <client>  For cross-library testing. Specify 'openssl" or 'gnutls'
305             as the client; the other is used as the server (assumes that
306             both have been built: set up Local/Makefile for OpenSSL and
307             "make exim_openssl", then for GnuTLS and "make exim_gnutls")
308
309 The options for ./runtest must be given first (but after the name of the
310 binary, if present). Any further options, that is, items on the command line
311 that start with a hyphen, are passed to the Exim binary when it is run as part
312 of a test. The only sensible use of this is to pass "-d" in order to run a test
313 with debugging enabled. Any other options are likely to conflict with options
314 that are set in the tests. Some tests are already set up to run with debugging.
315 In these cases, -d on the command line overrides their own debug settings.
316
317 The final two arguments specify the range of tests to be run. Test numbers lie
318 in the range 1 to 9999. If no numbers are given, the defaults are 1 and 8999
319 (sic). Tests with higher numbers (9000 upwards) are not run automatically
320 because they require specific data (such as a particular MySQL table) that is
321 unlikely to be generally available.
322
323 Tests that require certain optional features of Exim are grouped by number, so
324 in any given range, not all the tests will exist. Non-existent tests are just
325 skipped, but if there are no tests at all in the given range, a message is
326 output.
327
328 If you give only one number, just that test is run (if it exists). Instead of a
329 second number, you can give the character "+", which is interpreted as "to the
330 end". Normally this is 8999; if the starting number is 9000 or higher, "+" is
331 interpreted as 9999. Examples:
332
333   ./runtest 1300
334   ./runtest 1400 1699
335   ./runtest /usr/sbin/exim 5000 +
336   ./runtest -DIFF -d 81
337
338 When the script starts up, the first thing it does is to check that you have
339 sudo access to root. Then it outputs the version number of the Exim binary that
340 it is testing, and also information about the optional facilities that are
341 present (obtained from "exim -bV"). This is followed by some environmental
342 information, including the current login id and the hosts's IP address. The
343 script checks that the current user is in the Exim group, and that the Exim
344 user has access to the test suite directory.
345
346 The script outputs the list of tests requested, and a list of tests that will
347 be omitted because the relevant optional facilities are not in the binary. You
348 are then invited to press Return to start the tests running.
349
350
351 TEST OUTPUT
352 -----------
353
354 When all goes well, the only permanent output is the identity of the tests as
355 they are run, and "Script completed" for each test script, for example:
356
357   Basic/0001 Basic configuration setting
358     Script completed
359   Basic/0002 Basic string expansions
360     Script completed
361   Basic/0003 Caseless address blocking
362     Script completed
363   Basic/0004 Caseful address blocking
364     Script completed
365   Basic/0005 -bs to simple local delivery
366   ...
367
368 While a script is running, it shows "Test n" on the screen, for each of the
369 Exim tests within the script. There may also be comments from some tests when a
370 delay is expected, for example, if there is a "sleep" while testing a timeout.
371
372 Before each set of optional tests, an extra identifying line is output. For
373 example:
374
375   >>> The following tests require: authenticator cram_md5
376   CRAM-MD5/2500 CRAM-MD5 server tests
377     Script completed
378   CRAM-MD5/2501 CRAM-MD5 client tests
379     Script completed
380
381 If a test fails, you are shown the output of the text comparison that failed,
382 and prompted as to what to do next. The output is shown using the "less"
383 command, or "more" if "less" is not available. The options for "less" are set
384 to that it automatically exits if there is less that a screenful of output. By
385 default, the output is from the "cf" program, and might look like this:
386
387   DBM/1300 DBM files and exim_dbmbuild
388   ===============
389   Lines 7-9 of "test-stdout-munged" do not match lines 7-11 of "stdout/1300".
390   ----------
391   exim_dbmbuild exit code = 1
392   Continued set of lines is too long: max permitted length is 99999
393   exim_dbmbuild exit code = 1
394   ----------
395   dbmbuild abandoned
396   exim_dbmbuild exit code = 2
397   Continued set of lines is too long: max permitted length is 99999
398   dbmbuild abandoned
399   exim_dbmbuild exit code = 2
400   ===============
401   1 difference found.
402   "test-stdout-munged" contains 16 lines; "stdout/1300" contains 18 lines.
403
404   Continue, Retry, Update & retry, Quit? [Q]
405
406 This example was generated by running the test with a version of Exim
407 that had a bug in the exim_dbmbuild utility (the bug was fixed at release
408 4.53). See "How the tests work" below for a description of the files that are
409 used. In this case, the standard output differed from what was expected.
410
411 The reply to the prompt must either be empty, in which case it takes the
412 default that is given in brackets (in this case Q), or a single letter, in
413 upper or lower case (in this case, one of C, R, U, or Q). If you type anything
414 else, the prompt is repeated.
415
416 "Continue" carries on as if the files had matched; that is, it ignores the
417 mismatch. Any other output files for the same test will be compared before
418 moving on to the next test.
419
420 "Update & retry" copies the new file to the saved file, and reruns the test
421 after doing any further comparisons that may be necessary.
422
423 "Retry" does the same apart from the file copy.
424
425 Other circumstances give rise to other prompts. If a test generates output for
426 which there is no saved data, the prompt (after a message stating which file is
427 unexpectedly not empty) is:
428
429   Continue, Show, or Quit? [Q]
430
431 "Show" displays the data on the screen, and then you get the "Continue..."
432 prompt. If a test ends with an unexpected return code, the prompt is:
433
434   show stdErr, show stdOut, Continue (without file comparison), or Quit? [Q]
435
436 Typically in these cases there will be something interesting in the stderr
437 or stdout output. There is a similar prompt after the "server" auxiliary
438 program fails.
439
440
441 OPENSSL AND GNUTLS ERROR MESSAGES
442 ---------------------------------
443
444 Some of the TLS tests deliberately cause errors to check how Exim handles them.
445 It has been observed that different releases of the OpenSSL and GnuTLS
446 libraries generate different error messages. This may cause the comparison with
447 the saved output to fail. Such errors can be ignored.
448
449
450 OTHER ISSUES
451 ------------
452
453 . Some of the tests are time-sensitive (e.g. when testing timeouts, as in test
454   461). These may fail if run on a host that is also running a lot of other
455   processes.
456
457 . Some versions of "ls" use a different format for times and dates. This can
458   cause test 345 to fail.
459
460 . Test 0142 tests open file descriptors; on some hosts the output may vary.
461
462 . Some tests may fail, for example 0022, because it says it uses cached data
463   when the expected output thinks it should not be in cache.  Item #5 in the
464   Requirements section has:
465     "Exim must be built with its user and group specified at build time"
466   This means that you cannot use the "ref:username" in your Local/Makefile
467   when building the exim binary, in any of the following fields:
468     EXIM_USER  EXIM_GROUP  CONFIGURE_OWNER  CONFIGURE_GROUP
469
470 . If the runtest script warns that the hostname is not a Fully Qualified
471   Domain Name (FQDN), expect that some tests will fail, for example 0036,
472   with an extra log line saying the hostname doesn't resolve.  You must use a
473   FQDN for the hostname for proper test functionality.
474
475 . If you change your hostname to a FQDN, you must delete the test/dnszones
476   subdirectory.  When you next run the runtest script, it will rebuild the
477   content to use the new hostname.
478
479 . If your hostname has an uppercase characters in it, expect that some tests
480   will fail, for example, 0036, because some log lines will have the hostname
481   in all lowercase.  The regex which extracts the hostname from the log lines
482   will not match the lowercased version.
483
484 . Some tests may fail, for example 0015, with a cryptic error message:
485     Server return code 99
486   Due to security concerns, some specific files MUST have the group write bit
487   off.  For the purposes of the test suite, some test/aux-fixed/* files MUST
488   have the group write bit off, so it's easier to just remove the group write
489   bit for all of them.  If your umask is set to 002, the group write bit will
490   be on by default and you'll see this problem, so make sure your umask is
491   022 and re-checkout the test/ subdirectory.
492
493 . Some tests will fail if the username and group name are different. It does
494   not have to be the primary group, a secondary group is sufficient.
495
496
497 OTHER SCRIPTS AND PROGRAMS
498 --------------------------
499
500 There is a freestanding Perl script called "listtests" that scans the test
501 scripts and outputs a list of all the tests, with a short descriptive comment
502 for each one. Special requirements for groups of tests are also noted.
503
504 The main runtest script makes use of a second Perl script and some compiled C
505 programs. These are:
506
507 patchexim          A Perl script that makes a patched version of Exim (see the
508                    next section for details).
509
510 bin/cf             A text comparison program (see above).
511
512 bin/checkaccess    A program that is run as root; it changes uid/gid to the
513                    Exim user and group, and then checks that it can access
514                    files in the test suite's directory.
515
516 bin/client         A script-driven SMTP client simulation.
517
518 bin/client-gnutls  A script-driven SMTP client simulation with GnuTLS support.
519                    This is built only if GnuTLS support is detected on the host.
520
521 bin/client-ssl     A script-driven SMTP client simulation with OpenSSL support.
522                    This is built only if OpenSSL support is detected on the
523                    host.
524
525 bin/client-anytls  A symlink to either client-ssl or client-gnutls, if
526                    any is built.
527
528 bin/fakens         A fake "nameserver" for DNS tests (see below for details).
529
530 bin/fd             A program that outputs details of open file descriptors.
531
532 bin/iefbr14        A program that does nothing, and returns 0. It's just like
533                    the "true" command, but it is in a known place.
534
535 bin/loaded         Some dynamically loaded functions for testing dlfunc support.
536
537 bin/mtpscript      A script-driven SMTP/LMTP server simulation, on std{in,out}.
538
539 bin/server         A script-driven SMTP server simulation, over a socket.
540
541 bin/showids        Output the current uid, gid, euid, egid.
542
543 The runtest script also makes use of a number of ordinary commands such as
544 "cp", "kill", "more", and "rm", via the system() call. In some cases these are
545 run as root by means of sudo.
546
547
548 STANDARD SUBSTITUTIONS
549 ----------------------
550
551 In the following sections, there are several references to the "standard
552 substitutions". These make changes to some of the stored files when they are
553 used in a test. To save repetition, the substitutions themselves are documented
554 here:
555
556   CALLER         is replaced by the login name of the user running the tests
557   CALLERGROUP    is replaced by the caller's group id
558   CALLER_GID     is replaced by the caller's group id
559   CALLER_UID     is replaced by the caller's user id
560   DIR            is replaced by the name of the test-suite directory
561   EXIMGROUP      is replaced by the name of the Exim group
562   EXIMUSER       is replaced by the name of the Exim user
563   HOSTIPV4       is replaced by the local host's IPv4 address
564   HOSTIPV6       is replaced by the local host's IPv6 address
565   HOSTNAME       is replaced by the local host's name
566   PORT_D         is replaced by a port number for normal daemon use
567   PORT_N         is replaced by a port number that should never respond
568   PORT_S         is replaced by a port number for normal bin/server use
569   PORT_DYNAMIC   is replaced by a port number allocated dynamically
570   TESTNUM        is replaced by the current test number
571   V4NET          is replaced by an IPv4 network number for testing
572   V6NET          is replaced by an IPv6 network number for testing
573
574 PORT_D is currently hard-wired to 1225, PORT_N to 1223, and PORT_S to 1224.
575 V4NET is hardwired to 224 and V6NET to ff00. These networks are used for DNS
576 testing purposes, and for testing Exim with -bh. The only requirement is that
577 they are networks that can never be used for an IP address of a real host. I've
578 chosen two multicast networks for the moment.
579
580 PORT_DYNAMIC is allocated by hunting for a free port (starting at port
581 1024) a listener can bind to. This is done by runtest, for simulating
582 inetd operations.
583
584 If the host has no IPv6 address, "<no IPv6 address found>" is substituted but
585 that does not matter because no IPv6 tests will be run. A similar substitution
586 is made if there is no IPv4 address, and again, tests that actually require a
587 running IPv4 interface should be skipped.
588
589 If the host has more than one IPv4 or IPv6 address, the first one that
590 "ifconfig" lists is used. If the only available address is 127.0.0.1 (or ::1
591 for IPv6) it is used, but another value is preferred if available.
592
593 In situations where a specific test is not being run (for example, when setting
594 up dynamic data files), TESTNUM is replaced by an empty string, but should not
595 in fact occur in such files.
596
597
598 HOW THE TESTS WORK
599 ------------------
600
601 Each numbered script runs Exim (sometimes several times) with its own Exim
602 configuration file. The configurations are stored in the "confs" directory,
603 and before running each test, a copy of the appropriate configuration, with the
604 standard substitutions, is made in the file test-config. The -C command line
605 option is used to tell Exim to use this configuration.
606
607 The -D option is used to pass the path of the Exim binary to the configuration.
608 This is not standardly substituted, because there are two possible binaries
609 that might be used in the same test (one setuid to root, the other to the exim
610 user). Some tests also make use of -D to vary the configuration for different
611 calls to the Exim binary.
612
613 Normally, of course, Exim gives up root privilege when -C and -D are used by
614 unprivileged users. We do not want this to happen when running the tests,
615 because we want to be able to test all aspects of Exim, including receiving
616 mail from unprivileged users. The way this is handled is as follows:
617
618 At the start of the runtest script, the patchexim script is run as root. This
619 script makes a copy of the Exim binary that is to be tested, patching it as it
620 does so. (This is a binary patch, not a source patch.) The patch causes the
621 binary, when run, to "know" that it is running in the test harness. It does not
622 give up root privilege when -C and -D are used, and in a few places it takes
623 other special actions, such as delaying when starting a subprocess to allow
624 debug output from the parent to be written first. If you want to know more,
625 grep the Exim source files for "running_in_test_harness".
626
627 The patched binary is placed in the directory eximdir/exim and given the normal
628 setuid root privilege. This is, of course, a dangerous binary to have lying
629 around, especially if there are unprivileged users on the system. To protect
630 it, the eximdir directory is created with the current user as owner, exim as
631 the group owner, and with access drwx--x---. Thus, only the user who is running
632 the tests (who is known to have access to root) and the exim user have access
633 to the modified Exim binary. When runtest terminates, the patched binary is
634 removed.
635
636 Each set of tests proceeds by interpreting its controlling script. The scripts
637 are in subdirectories of the "scripts" directory. They are split up according
638 to the requirements of the tests they contain, with the 0000-Basic directory
639 containing tests that can always be run. Run the "listtests" script to obtain a
640 list of tests.
641
642
643 TEST OUTPUT
644 -----------
645
646 Output from script runs is written to the files test-stdout and test-stderr.
647 When an Exim server is involved, test-stdout-server and test-stderr-server are
648 used for its output. Before being compared with the saved output, the
649 non-server and server files are concatenated, so a single saved file contains
650 both.
651
652 A directory called spool is used for Exim's spool files, and for Exim logs.
653 These locations are specified in every test's configuration file.
654
655 When messages are delivered to files, the files are put in the test-mail
656 directory. Output from comparisons is written to test-cf.
657
658 Before comparisons are done, output texts are modified ("munged") to change or
659 remove parts that are expected to vary from run to run. The modified files all
660 end with the suffix "-munged". Thus, you will see test-stdout-munged,
661 test-mainlog-munged, test-mail-munged, and so on. Other files whose names start
662 with "test-" are created and used by some of the tests.
663
664 At the end of a successful test run, the spool directory and all the files
665 whose names begin with "test-" are removed. If the run ends unsuccessfully
666 (typically after a "Q" response to a prompt), the spool and test files are left
667 in existence so that the problem can be investigated.
668
669
670 TEST COMMANDS
671 -------------
672
673 Each test script consists of a list of commands, each optionally preceded by
674 comments (lines starting with #) and (also optionally) a line containing an
675 expected return code. Some of the commands are followed by data lines
676 terminated by a line of four asterisks.
677
678 The first line of each script must be a comment that briefly describes the
679 script. For example:
680
681   # -bS Use of HELO/RSET
682
683 A line consisting just of digits is interpreted as the expected return code
684 for the command that follows.
685
686 A line consisting of a tilde (~) followed by digits indicates a non-expected
687 return code for the command that follows.
688
689 The default expectation when neither such line exists
690 is a zero return code. For example, here is a complete test script, containing
691 just one command:
692
693   # -bS Unexpected EOF in headers
694   1
695   exim -bS -odi
696   mail from:<someone@some.where>
697   rcpt to:<blackhole@HOSTNAME>
698   data
699   from: me
700   ****
701
702 The expected return code in this case is 1, and the data lines are passed to
703 Exim on its standard input. Both the command line and the data lines have the
704 standard substitutions applied to them. Thus, HOSTNAME in the example above will
705 be replaced by the local host's name. Long commands can be continued over
706 several lines by using \ as a continuation character. This does *not* apply to
707 data lines.
708
709 A line with a leading number followed by a space and then an uppercase
710 word, equals character, value sets an expected return code as above
711 plus an environment variable.  Example:
712
713   255 TZ=GB
714   exim_msgdate -l -u -z -localhost_number=20 000000 1PANS3 ZZZZZZ
715   ****
716
717
718
719
720 Here follows a list of supported commands. They can be divided into two groups:
721
722
723 Commands with no input
724 ----------------------
725
726 These commands are not followed by any input data, or by a line of asterisks.
727
728
729   ### This is a verbose comment
730
731 A line starting with three hashmarks and some space copies the following text to
732 both stdout and stderr file being written by the test.
733
734   dbmbuild <file1> <file1>
735
736 This command runs the exim_dbmbuild utility to build a DBM file. It is used
737 only when DBM support is available in Exim, and typically follows the use of a
738 "write" command (see below) that creates the input file.
739
740
741   dump <dbname>
742
743 This command runs the exim_dumpdb utility on the testing spool directory, using
744 the database name given, for example: "dumpdb retry".
745
746
747   echo <text>
748
749 The text is written to the screen; this is used to output comments from
750 scripts.
751
752
753   exim_lock [options] <file name>
754
755 This command runs the exim_lock utility with the given options and file name.
756 The file remains locked for following commands until a non-daemon "exim"
757 completes.
758
759
760   exinext <data>
761
762 This command runs the exinext utility with the given argument data.
763
764
765   exigrep <data>
766
767 This command runs the exigrep utility with the given data (the search pattern)
768 on the current mainlog file.
769
770
771   exiqgrep <data>
772
773 This command runs the exiqgrep utility with the given options
774 on the current spool directory.
775
776
777   gnutls
778
779 This command is present at the start of all but one of the tests that use
780 GnuTLS. It copies a pre-existing parameter file into the spool directory, so
781 that Exim does not have to re-create the file each time. The first GnuTLS test
782 does not do this, in order to test that Exim can create the file.
783
784
785   killdaemon
786
787 This command must be given in any script that starts an Exim daemon, normally
788 at the end. It searches for the PID file in the spool directory, and sends a
789 SIGINT signal to the Exim daemon process whose PID it finds. See below for
790 comments about starting Exim daemons.
791
792
793   millisleep <m>
794
795 This command causes the script to sleep for m milliseconds. Nothing is output
796 to the screen.
797
798
799   munge <name>
800
801 This command requests custom munging of the test outputs.  The munge names
802 used are coded in the runtest script (look for 'name of munge').
803
804
805   need_ipv4
806
807 This command must be at the head of a script. If no IPv4 interface has been
808 found, the entire script is skipped, and a comment is output.
809
810
811   need_ipv6
812
813 This command must be at the head of a script. If no IPv6 interface has been
814 found, the entire script is skipped, and a comment is output.
815
816
817   need_largefiles
818
819 This command must be at the head of a script. If the Exim binary does not
820 support large files (off_t is <= 4), the entire script is skipped, and a
821 comment is output.
822
823
824   need_move_frozen_messages
825
826 This command must be at the head of a script. If the Exim binary does not have
827 support for moving frozen messages (which is an optional feature), the entire
828 script is skipped, and a comment is output.
829
830
831   no_message_check
832
833 If this command is encountered anywhere in the script, messages that are
834 delivered when the script runs are not compared with saved versions.
835
836
837   no_msglog_check
838
839 If this command is encountered anywhere in the script, message log files that
840 are still in existence at the end of the run (for messages that were not
841 delivered) are not compared with saved versions.
842
843
844   no_munge
845
846 If this command is encountered anywhere in the script, the output is not
847 munged before it is compared with a saved version.
848 This option allows meaningful tests of the exim_msgdate utility;
849 without it all date comparison checks would succeed.
850
851
852   no_stderr_check
853
854 If this command is encountered anywhere in the script, the stderr output from
855 the run is not compared with a saved version.
856
857
858   no_stdout_check
859
860 If this command is encountered anywhere in the script, the stdout output from
861 the run is not compared with a saved version.
862
863
864   rmfiltertest
865
866 This command indicates that the script is for a certain type of filter test, in
867 which there are a lot of repetitive stdout lines that get in the way, because
868 filter tests output data about the sender and recipient. Such lines are removed
869 from the stdout output before comparing, for ease of human perusal.
870
871
872   sleep <n>
873
874 This command causes the script to sleep for n seconds. If n is greater than
875 one, "sleep <n>" is output to the screen, followed by a dot for every second
876 that passes.
877
878
879   sortlog
880
881 This command causes special sorting to occur on the mainlog file before
882 comparison. Every sequence of contiguous delivery lines (lines containing the
883 => -> or *> flags) is sorted. This is necessary in some tests that use parallel
884 deliveries because on different systems the processes may terminate in a
885 different order.
886
887
888 A number of standard file management commands are also recognized. These are
889 cat, chmod, chown, cp, du, ln, ls, du, mkdir, mkfifo, rm, rmdir, and touch.
890 Some are run as root using "sudo".
891
892
893 Commands with input
894 -------------------
895
896 The remaining commands are followed by data lines for their standard input,
897 terminated by four asterisks ("****"). Even if no data is required for the particular
898 usage, the asterisks must be given.
899
900 If the input line starts with ':<cmd>:', this prefix is removed and the
901 line is processed by the runtest script before sending. The following
902 commands are recognised:
903
904 - "eval": process the reset of the line with Perl's string eval()
905   function. This can be used to send arbitrary data by encoding it as
906   escape sequences (e.g. "\x41\101"). If you need a line ending, you have
907   to append it accordingly (e.g. "\r\n").
908
909 - "noeol": do not terminate the data sent to the application with an end
910   of line character.
911
912 - "sleep": interpret the rest of the line as an integer and sleep for
913   that number of seconds before proceeding. No data will be output to
914   the application.
915
916
917   background
918
919 This command takes one script line and runs it in the background,
920 in parallel with following commands.  For external daemons, eg. redis-server.
921
922
923   catwrite <file name> [nxm[=start-of-line-text]]*
924
925 This command operates like the "write" command, which is described below,
926 except that the data it generates is copied to the end of the test-stdout file
927 as well as to the named file.
928
929
930   client [<options>] <ip address> <port> [<outgoing interface>]
931
932 This command runs the auxiliary "client" program that simulates an SMTP client.
933 It is controlled by a script read from its standard input, details of which are
934 given below. There are two options. One is -t, which must be followed directly
935 by a number, to specify the command timeout in seconds (e.g. -t5). The default
936 timeout is 5 seconds. The other option is -tls-on-connect, which causes the
937 client to try to start up a TLS session as soon as it has connected, without
938 using the STARTTLS command. The client program connects to the given IP address
939 and port, using the specified interface, if one is given.
940
941
942   client-ssl [<options>] <ip address> <port> [<outgoing interface>] \
943              [<cert file>] [<key file>]
944
945 When OpenSSL is available on the host, an alternative version of the client
946 program is compiled, one that supports TLS using OpenSSL. The additional
947 arguments specify a certificate and key file when required for the connection.
948 There are two additional options: -tls-on-connect, that causes the client to
949 initiate TLS negotiation immediately on connection; -ocsp that causes the TLS
950 negotiation to include a certificate-status request.  The latter takes a
951 filename argument, the CA info for verifying the stapled response.
952
953
954   client-gnutls [<options>] <ip address> <port> [<outgoing interface>] \
955                 [<cert file>] [<key file>]
956
957 When GnuTLS is available on the host, an alternative version of the client
958 program is compiled, one that supports TLS using GnuTLS. The additional
959 arguments specify a certificate and key file when required. There is one
960 additional option, -tls-on-connect, that causes the client to initiate TLS
961 negotiation immediately on connection.
962
963
964   exim [<options>] [<arguments>]
965
966 This command runs the testing version of Exim. Any occurrence of "$msg1" in the
967 command line is replaced by the ID of the first (oldest) message in Exim's
968 (testing) spool. "$msg2" refers to the second, and so on. The name "exim" can
969 be preceded by an environment setting as in this example:
970
971   LDAPTLS_REQCERT=never exim -be
972
973 It can also be preceded by a number; this specifies a number of seconds to wait
974 before closing the stdout pipe to Exim, and is used for some timeout tests. For
975 example:
976
977   3 exim -bs
978
979 Finally, "exim" can be preceded by "sudo", to run Exim as root. If more than
980 one of these prefixes is present, they must be in the above order.
981
982 If the options include "-DSERVER" but not "-DNOTDAEMON", the script waits for
983 Exim to start but then continues without waiting for it to terminate. Typically
984 this will be for a daemon-mode "-bd" operation.  The daemon should be later
985 terminated using "killdaemon".
986
987
988   exim_exim [<options>] [<arguments>]
989
990 This runs an alternative version of Exim that is setuid to exim rather than to
991 root.
992
993
994   server [<options>] <port or socket> [<connection count>]
995
996 This command runs the auxiliary "server" program that simulates an SMTP (or
997 other) server. It is controlled by a script that is read from its standard
998 input, details of which are given below. A number of options are implemented:
999
1000   -d       causes the server to output debugging information
1001
1002   -t <sec> sets a timeout (default 5) for when the server is
1003            awaiting an incoming connection. If negative, the
1004            absolute value is used and a timeout results in a
1005            nonfailure exit code
1006
1007   -noipv4  causes the server not to set up an IPv4 socket
1008
1009   -noipv6  causes the server not to set up an IPv6 socket
1010
1011   -i <sec> sets an initial pause, to delay before creating the listen sockets
1012
1013 By default, in an IPv6 environment, both kinds of socket are set up. However,
1014 the test script knows which interfaces actually exist on the host, and it adds
1015 -noipv4 or -noipv6 to the server command as required. An error occurs if both
1016 these options are given.
1017
1018 The only required argument is either a port number or the path name of a Unix
1019 domain socket. The port is normally PORT_S, which is changed to an actual
1020 number by the standard substitutions. The optional final argument specifies the
1021 number of different connections to expect (default 1). These must happen
1022 serially (one at a time). There is no support for multiple simultaneous
1023 connections. Here are some example commands:
1024
1025   server PORT_S
1026   server -t 10 PORT_S 3
1027   server /tmp/somesocket
1028
1029 The following lines, up to a line of four asterisks, are the server's
1030 controlling standard input (described below). These lines are read and
1031 remembered; during the following commands, until a non-deamon "exim" command
1032 is reached, the server is run in parallel.  Then the server termination
1033 is waited for.
1034
1035
1036   write <file name> [nxm[=start-of-line-text]]*
1037
1038 The "write" command is a way of creating files of specific sizes for buffering
1039 tests, or containing specific data lines. Being able to do this from within the
1040 script saves holding lots of little test files. The optional argument specifies
1041 n lines of length m. The lines consist of the letter "a". If start of line text
1042 is supplied, it replaces "a"s at the start of each line. Underscores in the
1043 start of line text are turned into spaces. The optional argument may be
1044 repeated. The data lines that follow a "write" command are split into two by a
1045 line of four plus signs. Any above the split are written before the
1046 fixed-length lines, and any below the split are written after. For example:
1047
1048   write test-data 3x30=AB_ 1x50
1049   Pre-data
1050   lines
1051   ++++
1052   Post-data
1053   lines
1054   ****
1055
1056 This command generates a file containing:
1057
1058   Pre-data
1059   lines
1060   AB aaaaaaaaaaaaaaaaaaaaaaaaaaa
1061   AB aaaaaaaaaaaaaaaaaaaaaaaaaaa
1062   AB aaaaaaaaaaaaaaaaaaaaaaaaaaa
1063   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1064   Post-data
1065   lines
1066
1067 If there are no fixed-length line specifiers, there is no need to split the
1068 data, and a line of plusses is not needed.
1069
1070
1071   [sudo] perl
1072
1073 This command runs Perl, with the data as its standard input, to allow arbitrary
1074 one-off things to be done.
1075
1076
1077 CLIENT SCRIPTS
1078 --------------
1079
1080 Lines in client scripts are of several kinds:
1081
1082 (1) "??? ": If a line begins with three question marks and a space, the rest of the
1083     line defines the start of expected output from the server. If what is
1084     received does not match, the client bombs out with an error message.
1085
1086 (2) "???*": If a line begins with three question marks and an asterisk, the server
1087     is expected to close the connection.
1088
1089 (3) "????": If a line begins with four question marks, the rest of the line defines
1090     the start of one or more possible output lines from the server.  When it
1091     matches, the client silently repeats the comparison using the next server
1092     line.  When the match fails, the client silently proceeds to the next script
1093     line with the then-current server output unconsumed.
1094
1095 (4) "+++ ": If a line starts with three plus signs followed by a space, the rest of the
1096     line specifies a number of seconds to sleep for before proceeding.
1097
1098 (5) ">>> ": If a line begins with three '>' characters and a space, the rest of the
1099     line is input to be sent to the server.  Backslash escaping is done as
1100     described below, but no trailing "\r\n" is sent.
1101
1102 (6) "<<< ": If a line begin with three '<' characters and a space, the rest of the
1103     line is a filename; the content of the file is inserted into the script
1104     at this point.
1105
1106 (7) Otherwise, the line is an input line line that is sent to the server. Any
1107     occurrences of \r and \n in the line are turned into carriage return and
1108     linefeed, respectively. This is used for testing PIPELINING.
1109     Any sequences of \x followed by two hex digits are converted to the equivalent
1110     byte value.  Any other character following a \ is sent verbatim.
1111     The line is sent with a trailing "\r\n".
1112
1113 Here is a simple example:
1114
1115   client 127.0.0.1 PORT_D
1116   ??? 220
1117   EHLO xxx
1118   ??? 250-
1119   ??? 250
1120   AUTH PLAIN AbdXi0AdnD2CVy
1121   ??? 535
1122   quit
1123   ??? 221
1124   ****
1125
1126 In the case of client-gnutls and client-ssl, if a command is "starttls", this
1127 is remembered, and after a subsequent OK response, an attempt to move into TLS
1128 mode occurs. If a command is "starttls_wait", the client sends "starttls" but
1129 does not start up TLS; this is for testing timeouts. If a command is "stoptls",
1130 an existing TLS connection is shut down, but nothing is sent.
1131
1132
1133 SERVER SCRIPTS
1134 --------------
1135
1136 The server program sleeps till a connection occurs or its timeout is reached,
1137 in which case it bombs out. The next set of command lines are interpreted. They
1138 are of the following kinds:
1139
1140 (1) A line that starts with '>' or with a digit is an output line that is sent
1141     to the client. In the case of '>':
1142
1143     (a) If the line starts with ">>", no terminating CRLF is sent.
1144     (b) If the line starts with ">CR>", just CR is sent at the end.
1145     (c) If the line starts with ">LF>", just LF is sent at the end.
1146     (d) If the line starts with ">*eof", nothing is sent and the connection
1147           is closed.
1148
1149     The data that is sent starts after the initial '>' sequence.  Within
1150     each line the sequence '\x' followed by two hex digits can be used
1151     to specify an arbitrary byte value.  The sequence '\\' specifies a
1152     single backslash.
1153
1154 (2) A line that starts with "*sleep" specifies a number of seconds to wait
1155     before proceeding.
1156
1157 (3) A line containing "*data" and a number specifies that the client is
1158     expected to send that many byte; the server discards them
1159
1160 (4) A line containing "*eof" specifies that the client is expected to close
1161     the connection at this point.
1162
1163 (5) A line containing just '.' specifies that the client is expected to send
1164     many lines, terminated by one that contains just a dot.
1165
1166 (6) Otherwise, the line defines the start of an input line that the client
1167     is expected to send. To allow for lines that start with digits, the line
1168     may start with '<', which is not taken as part of the input data. If the
1169     lines starts with '<<' then only the characters are expected; no return-
1170     linefeed terminator. If the input does not match, the server bombs out
1171     with an error message.  Backslash-escape sequences may be used in the
1172     line content as for output lines.
1173
1174 Here is a simple example of server use in a test script:
1175
1176   server PORT_S
1177   220 Greetings
1178   EHLO
1179   250 Hello there
1180   MAIL FROM
1181   250 OK
1182   RCPT TO
1183   250 OK
1184   DATA
1185   354 Send it!
1186   .
1187   250 OK
1188   QUIT
1189   225 OK
1190   ****
1191
1192 After a "server" command in a test script, the server runs in parallel until an
1193 "exim" command is reached. The "exim" command attempts to deliver one or more
1194 messages to port PORT_S on the local host. When it has finished, the test
1195 script waits for the "server" process to finish.
1196
1197 The "mtpscript" program is like "server", except that it uses stdin/stdout for
1198 its input and output instead of a script. However, it is not called from test
1199 scripts; instead it is used as the command for pipe transports in some
1200 configurations, to simulate non-socket LMTP servers.
1201
1202
1203 AUXILIARY DATA FILES
1204 --------------------
1205
1206 Many of the tests make use of auxiliary data files. There are two types; those
1207 whose content is fixed, and those whose content needs to be varied according to
1208 the current environment. The former are kept in the directory aux-fixed. The
1209 latter are distributed in the directory aux-var-src, and copied with the
1210 standard substitutions into the directory aux-var at the start of each test
1211 run.
1212
1213 Most of the auxiliary files have names that start with a test number,
1214 indicating that they are specific to that one test. A few fixed files (for
1215 example, some TLS certificates) are used by more than one test, and so their
1216 names are not of this form.
1217
1218 There are also some auxiliary DNS zone files, which are described in the next
1219 section.
1220
1221
1222 DNS LOOKUPS AND GETHOSTBYNAME
1223 -----------------------------
1224
1225 The original test suite required special testing zones to be loaded into a
1226 local nameserver. This is no longer a requirement for the new suite. Instead, a
1227 program called fakens is used to simulate a nameserver. When Exim is running in
1228 the test harness, instead of calling res_search() - the normal call to the DNS
1229 resolver - it calls a testing function. This handles a few special names itself
1230 (for compatibility with the old test suite), but otherwise passes the query to
1231 the fakens program.
1232
1233 The fakens program consults "zone files" in the directory called dnszones, and
1234 returns data in the standard resource record format for Exim to process as if
1235 it came from the DNS. However, if the requested domain is not in any of the
1236 zones that fakens knows about, it returns a special code that causes Exim to
1237 pass the query on to res_search(). The zone files are:
1238
1239   db.test.ex    A zone for the domain test.ex.
1240   db.ip4.10     A zone for one special case in 10.250.0.0/16 (see below)
1241   db.ip4.V4NET  A zone for the domain V4NET.in-addr.arpa.
1242   db.ip4.127    A zone for the domain 127.in-addr.arpa.
1243   db.ip6.V6NET  A zone for the domain inverted(V6NET).ip6.arpa.
1244   db.ip6.0      A zone for the domain 0.ip6.arpa.
1245
1246 V4NET and V6NET are substituted with the current testing networks (see above).
1247 In the case of V6NET, the network is four hex digits, and it is split and
1248 inverted appropriately when setting up the zone.
1249
1250 These fake zone files are built dynamically from sources in the dnszones-src
1251 directory by applying the standard substitutions. The test suite also builds
1252 dynamic zone files for the name of the current host and its IP address(es). The
1253 idea is that there should not be any need to rely on an external DNS.
1254
1255 The fakens program handles some names programmatically rather than using the
1256 fake zone files.  These are:
1257
1258   manyhome.test.ex  This name is used for testing hosts with ridiculously large
1259                     numbers of IP addresses; 2048 IP addresses are generated
1260                     and returned. Doing it this way saves having to make the
1261                     interface to fakens handle more records that can fit in the
1262                     data block. The addresses that are generated are in the
1263                     10.250.0.0/16 network.
1264
1265   test.again.dns    This always provokes a TRY_AGAIN response, for testing the
1266                     handling of temporary DNS error. If the full domain name
1267                     starts with digits, a delay of that many seconds occurs.
1268
1269   test.fail.dns     This always provokes a NO_RECOVERY response, for testing
1270                     DNS server failures.
1271
1272 The use of gethostbyname() and its IPv6 friends is also subverted when Exim is
1273 running in the test harness. The test code handles a few special names
1274 directly; for all the others it uses DNS lookups, which are then handled as
1275 just described. Thus, the use of /etc/hosts is completely bypassed. The names
1276 that are specially handled are:
1277
1278   localhost         Always returns 127.0.0.1 or ::1, for IPv4 and IPv6 lookups,
1279                     respectively.
1280
1281   <an IP address>   If the IP address is of the correct form for the lookup
1282                     type (IPv4 or IPv6), it is returned. Otherwise a panic-die
1283                     error occurs.
1284
1285 The reverse zone db.ip4.10 is provided just for the manyhome.test.ex case. It
1286 contains a single wildcard resource record. It also contains the line
1287
1288   PASS ON NOT FOUND
1289
1290 Whenever fakens finds this line in a zone file, it returns PASS_ON instead of
1291 HOST_NOT_FOUND. This causes Exim to pass the query to res_search().
1292
1293 ****