README.rst 6.42 KB
Newer Older
Marek Vavrusa's avatar
Marek Vavrusa committed
1 2
DNS test harness (Deckard)
==========================
Marek Vavruša's avatar
Marek Vavruša committed
3

Marek Vavrusa's avatar
Marek Vavrusa committed
4 5 6
Deckard is a DNS software testing tool that creates a controlled environment for reproducible tests.
In essence - it runs given binary as a subprocess, sends it scripted queries, and intercepts queries
from the tested binary. It can simulate network issues, DNS environment changes, and fake time.
Marek Vavruša's avatar
Marek Vavruša committed
7

Marek Vavrusa's avatar
Marek Vavrusa committed
8 9
All network communications are redirected `over UNIX sockets <socket_wrapper>`_.
Test cases are written in `scenarios <SCENARIO_GUIDE.rst>`_, that contain:
Marek Vavruša's avatar
Marek Vavruša committed
10

Marek Vavrusa's avatar
Marek Vavrusa committed
11 12
- A declarative description of the environment (e.g. what queries can the subject make)
- A sequence of queries (and expected answers), and other events (e.g. what should the subject answer)
Marek Vavruša's avatar
Marek Vavruša committed
13

Marek Vavrusa's avatar
Marek Vavrusa committed
14 15
Requirements
------------
16

Marek Vavrusa's avatar
Marek Vavrusa committed
17
Deckard requires next software to be installed:
18

Marek Vavrusa's avatar
Marek Vavrusa committed
19 20 21
- Python >= 2.7
- dnspython_ - DNS library for Python.
- Jinja2_ - template engine for generating config files.
22
- `socket_wrapper`_ - a modification of `initial socket_wrapper`_ library (part of the cwrap_ tool set for creating an isolated networks).
23

Marek Vavrusa's avatar
Marek Vavrusa committed
24
It also depends on libfaketime_, but it is embedded as it requires a rather recent version (automatically synchronised with ``make``).
25

Marek Vavrusa's avatar
Marek Vavrusa committed
26 27
Compatibility
-------------
28

Marek Vavrusa's avatar
Marek Vavrusa committed
29
Works well on Linux, Mac OS X [#]_ and probably all BSDs. Tested with `Knot DNS Resolver`_ and `PowerDNS Recursor`_.
30

Marek Vavrusa's avatar
Marek Vavrusa committed
31
.. [#] Python from Homebrew must be used, as the built-in Python is protected by the CSR_ from OS X 10.11 and prevents library injection.
32

Marek Vavrusa's avatar
Marek Vavrusa committed
33 34
How to use it
-------------
35
    
Marek Vavrusa's avatar
Marek Vavrusa committed
36 37 38
Create a config file template
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

39
If the tested server accepts a config file(s), you have to create a template for it.
Marek Vavrusa's avatar
Marek Vavrusa committed
40 41 42 43
Deckard uses the Jinja2_ templating engine (like Ansible or Salt) with several variables that you can use.
It's okay if you don't use them, but expect some tests to fail (i.e. if you don't set the ``TRUST_ANCHOR``,
then the DNSSEC tests won't work properly).

44 45
- ``ROOT_ADDR``    - root server hint. Port is not set and assumed to be equal to 53.
- ``SELF_ADDR``    - assigned address for the tested binary. Port is not set and assumed to be equal to 53.
Marek Vavrusa's avatar
Marek Vavrusa committed
46 47
- ``NO_MINIMIZE``  - ``'true'`` or ``'false'``, enables or disables query minimization respectively.
- ``WORKING_DIR``  - working directory, equivalent to the value of a ``SOCKET_WRAPPER_DIR``
48
  environment variable.
Grigorii Demidov's avatar
Grigorii Demidov committed
49
- ``INSTALL_DIR``  - Deckard home directory
Marek Vavruša's avatar
Marek Vavruša committed
50
- ``TRUST_ANCHOR`` - a trust anchor in form of a DS record, see `scenario guide <https://gitlab.labs.nic.cz/knot/deckard/blob/master/SCENARIO_GUIDE.rst>`_.
51

Marek Vavrusa's avatar
Marek Vavrusa committed
52 53
Setting up the test
^^^^^^^^^^^^^^^^^^^
54

Marek Vavrusa's avatar
Marek Vavrusa committed
55
You can alter test process using the Makefile variables:
56

Marek Vavrusa's avatar
Marek Vavrusa committed
57 58
- ``TESTS``        - path to scenario files; default: ``sets/resolver``
- ``DAEMON``       - path to binary have to be tested; default: ``kresd``
59 60 61
- ``TEMPLATE``     - colon-separated list of jinja2 template files to generate configuration files; default: ``kresd.j2``
- ``CONFIG``       - colon-separated list of names of configuration files to be generated; resulting files will be generated  respectively to the ``TEMPLATE`` file list, i.e. first file in list is the result of processing of the first file from ``TEMPLATE`` list, etc.; default: ``config``

Marek Vavrusa's avatar
Marek Vavrusa committed
62
- ``ADDITIONAL``   - additional parameters for binary, intended to test; not set by default
63

Marek Vavrusa's avatar
Marek Vavrusa committed
64 65
Run it
^^^^^^
66

Marek Vavrusa's avatar
Marek Vavrusa committed
67
Execute the tests by running **make**:
68 69 70 71 72

.. code-block:: bash

    make TESTS=sets/resolver DAEMON=/usr/local/bin/kresd TEMPLATE=kresd.j2 CONFIG=config

Marek Vavrusa's avatar
Marek Vavrusa committed
73
These are the default values for Knot DNS Resolver.
74

Marek Vavrusa's avatar
Marek Vavrusa committed
75 76
Examples
--------
77

Marek Vavrusa's avatar
Marek Vavrusa committed
78
1. Configuration file example for Knot DNS Resolver:
79

Marek Vavrusa's avatar
Marek Vavrusa committed
80
.. code-block:: lua
81 82 83 84 85 86 87

    net = { '{{SELF_ADDR}}' }
    modules = {'stats', 'policy', 'hints'}
    hints.root({['k.root-servers.net'] = '{{ROOT_ADDR}}'})
    option('NO_MINIMIZE', {{NO_MINIMIZE}})
    option('ALLOW_LOCAL', true)
    trust_anchors.add('{{TRUST_ANCHOR}}')
Marek Vavrusa's avatar
Marek Vavrusa committed
88 89 90


2. Configuration file example for PowerDNS Recursor [#]_:
Marek Vavrusa's avatar
Marek Vavrusa committed
91

Marek Vavrusa's avatar
Marek Vavrusa committed
92 93 94 95 96 97 98 99
::

    # config-dir    Location of configuration directory (recursor.conf)
    config-dir={{WORKING_DIR}}
    # local-address IP addresses to listen on, separated by spaces or commas. Also accepts ports.
    local-address={{SELF_ADDR}}
    # socket-dir    Where the controlsocket will live
    socket-dir={{WORKING_DIR}}
100 101
    # hint-file	If set, load root hints from this file
    hint-file={{INSTALL_DIR}}/template/hints.pdns
Marek Vavrusa's avatar
Marek Vavrusa committed
102 103 104 105

.. [#] Only changed directives in the default config are shown.

3. Test script for PowerDNS Recursor:
106 107 108 109 110 111 112 113 114 115 116 117

.. code-block:: bash

    #!/bin/bash
    TESTS=sets/resolver 
    DAEMON=pdns_recursor
    TEMPLATE=recursor.j2 
    CONFIG=recursor.conf
    ADDITIONAL=--config-dir=./
    export TESTS DAEMON TEMPLATE CONFIG ADDITIONAL
    make

Marek Vavrusa's avatar
Marek Vavrusa committed
118 119
For developers
--------------
120

Marek Vavrusa's avatar
Marek Vavrusa committed
121 122
Writing your own scenario
^^^^^^^^^^^^^^^^^^^^^^^^^
123

Marek Vavruša's avatar
Marek Vavruša committed
124
See `scenario guide <https://gitlab.labs.nic.cz/knot/deckard/blob/master/SCENARIO_GUIDE.rst>`_
125

Marek Vavrusa's avatar
Marek Vavrusa committed
126 127 128 129 130 131 132 133
Setting up socket wrapper library (cwrap)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Detailed instructions on using cwrap you can read here_

Generally, explicit environment setup for cwrap is not required. 
When cwrap environment is absent, default values will be used :

134
- ``SOCKET_WRAPPER_DEFAULT_IFACE`` = 2
Marek Vavrusa's avatar
Marek Vavrusa committed
135 136 137 138 139 140 141 142 143 144
- ``SOCKET_WRAPPER_DIR`` will be created in default temporary directory with 
  randomly generated name, prefixed by ``/tmp``
- ``SOCKET_WRAPPER_DEBUGLEVEL`` will not be set

``SOCKET_WRAPPER_DIR`` can also be used as a work directory for binary under test. When a test 
fails, the work directory can contain useful information for post-mortem analysis. You can explicitly
set ``SOCKET_WRAPPER_DIR`` to a custom path for more convenient analysis.

Acknowledgments
---------------
145

Marek Vavruša's avatar
Marek Vavruša committed
146 147
The test scenario design and a lot of tests were written for `NLnetLabs Unbound <http://unbound.net/index.html>`_ (BSD licensed).
The original test case format is described in the `Doxygen documentation <http://unbound.net/documentation/doxygen/replay_8h.html#a6f204646f02cc4debbaf8a9b3fdb59a7>`_.
148

Marek Vavrusa's avatar
Marek Vavrusa committed
149 150
.. _cwrap: https://cwrap.org/
.. _`dnspython`: http://www.dnspython.org/
151
.. _Jinja2: http://jinja.pocoo.org/
152 153
.. _`socket_wrapper`: https://gitlab.labs.nic.cz/labs/socket_wrapper
.. _`initial socket_wrapper`: https://cwrap.org/socket_wrapper.html
154 155 156 157
.. _Libfaketime: https://github.com/wolfcw/libfaketime
.. _`Knot DNS Resolver`: https://gitlab.labs.nic.cz/knot/resolver/blob/master/README.md
.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/
.. _here: https://git.samba.org/?p=socket_wrapper.git;a=blob;f=doc/socket_wrapper.1.txt;hb=HEAD
158
.. _CSR: http://apple.stackexchange.com/questions/193368/what-is-the-rootless-feature-in-el-capitan-really