regression-tests.recursor/README.md

   1 Some notes on running and extending the recursor tests
   2
   3 SYSTEM CONFIG
   4 -------------
   5
   6 The recursor regression suite requires a series of available IPs to bind to.
   7
   8 Debian/Ubuntu example:
   9
  10     $ grep -w lo /etc/network/interfaces
  11     auto lo
  12     iface lo inet loopback
  13         up /sbin/ip addr add 10.0.3.0/24 dev lo
  14
  15 The suite also requires `bind()` access to port 53. The example config
  16 relies on authbind for this:
  17
  18     $ ls -al /etc/authbind/byport/53
  19     -rwxr-xr-x 1 you you 0 May 31  2012 /etc/authbind/byport/53
  20
  21 Note that this file needs to be executable by the user you run as for
  22 authbind to work!
  23
  24 Other dependencies: daemontools, lua-posix
  25
  26 SETTING UP
  27 ----------
  28
  29 Copy `vars.sample` to `vars`
  30
  31     $ cp vars.sample vars
  32
  33 Edit `vars`:
  34
  35 The /24 to bind the various daemons in:
  36
  37     PREFIX=10.0.3
  38
  39 How to run the auth server (usually no need to change this):
  40
  41     AUTHRUN="exec authbind ../../../pdns/pdns_server --config-dir=. > logfile 2>&1"
  42
  43 How to run the recursor (usually, again, no need to change this):
  44
  45     RECRUN="exec authbind ../../../pdns/recursordist/pdns_recursor --config-dir=. --socket-dir=. --daemon=no --trace=yes --dont-query= --local-address=$PREFIX.9 --hint-file=hintfile --packetcache-ttl=0 --max-cache-ttl=15 --threads=1 > logfile 2>&1"
  46
  47
  48 RUNNING
  49 -------
  50
  51 Write out the various configuration files, create the service dirs (this uses
  52 `vars`):
  53
  54     $ ./config.sh
  55
  56 Start all daemons:
  57
  58     $ ./start.sh
  59
  60 Check that they are all up:
  61
  62     $ svstat configs/*
  63     configs/10.0.3.10: up (pid 1145) 13 seconds
  64     configs/10.0.3.11: up (pid 1141) 13 seconds
  65     configs/10.0.3.12: up (pid 1137) 13 seconds
  66     ...
  67     configs/10.0.3.8: up (pid 1138) 13 seconds
  68     configs/recursor-service: up (pid 1140) 13 seconds
  69
  70 (They all need to be up more than a few seconds, otherwise they might be
  71 crashing on startup. Check the per-service `logfile` if something is wrong).
  72
  73 Run the tests:
  74
  75     $ ./runtests
  76
  77 Various things might go wrong the first time you run the tests. Correct them
  78 and try again. If you think you have fixed everything and you still have some
  79 tests failing (most importantly the ghost-* tests), run `svc -t configs/*` and
  80 try again.
  81
  82 Eventually:
  83
  84     12 out of 12 (100.00%) tests passed, 0 were skipped
  85
  86 CLEANING UP
  87 -----------
  88
  89 Stop all daemons:
  90
  91     $ ./stop.sh
  92
  93 Remove config dirs:
  94
  95     $ ./clean.sh
  96
  97 ADDING TESTS
  98 ------------
  99
 100 The testing setup consists of one recursor (at .9), one auth for our fake root
 101 zone (at .8) and another bunch of auths for deeper zones (at .10 and up).
 102
 103 `config.sh` creates all the daemon configs, zonefiles, and, where necessary,
 104 Lua prequery scripts to emulate behaviour that `pdns_server` cannot produce
 105 natively.
 106
 107 Figure out whether your new test needs another zone, and edit config.sh accordingly.
 108
 109 Create a new directory for your test. It should at least have `command` (don't forget
 110 chmod +x), `description`, and an `expected_result` file (often empty at this stage).
 111
 112 When you have that set up, run `./runtests` again. Your test will fail; check the
 113 `real_result` file. If it looks alright, copy it to `expected_result`.
 114
 115 Congratulations, you have just written a test!