README.rst 4.34 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

4
Deckard is a DNS software testing tool that creates a controlled network environment for reproducible tests.
Marek Vavruša's avatar
Marek Vavruša committed
5

6 7 8 9 10 11 12 13 14 15 16 17 18
In essence, it works like this:

- Deckard runs given binaries as subprocesses in an isolated network environment.
- When binaries are up, Deckard sends scripted queries and checks replies.
- When a binary attempts to contact another server, Deckard intercepts the communication and replies with scripted answer.
- Deckard can simulate network issues, DNS environment changes, and fake time (for DNSSEC validation tests).

No changes to real network setup are required because all network communications are redirected over UNIX sockets (and recorded to PCAP).

Test cases are described by `scenarios <doc/scenario_guide.rst>`_ that contain:

- A declarative description of the environment (e.g. what queries can the binary under test make and what Deckard should answer)
- A sequence of queries (and expected answers), and other events (e.g. time jumps forward)
Marek Vavruša's avatar
Marek Vavruša committed
19 20


Marek Vavrusa's avatar
Marek Vavrusa committed
21 22
Requirements
------------
23

24
Deckard requires following software to be installed:
25

Tomas Krizek's avatar
Tomas Krizek committed
26 27
- Python >= 3.5
- augeas_ - library for editing configuration files
28 29 30
- dnspython_ - DNS library for Python
- Jinja2_ - template engine for generating config files
- PyYAML_ - YAML parser for Python
Tomas Krizek's avatar
Tomas Krizek committed
31
- python-augeas_ - Python bindings for augeas API
32 33
- pytest_ - testing framework for Python, used for running the test cases
- pytest-xdist_ - module for pytest for distributed testing
34
- custom C libraries (installed automatically, see below)
35

36 37
For convenient use it is strongly recommended to have a C compiler, Git, and ``make`` available.
First execution of ``make`` will automatically download and compile following libraries:
38

39 40
- libfaketime_ - embedded because Deckard requires a rather recent version
- `modified socket_wrapper`_ - custom modification of `original socket_wrapper`_ library (part of the cwrap_ tool set for creating an isolated networks)
41 42


43
Compatibility
Marek Vavrusa's avatar
Marek Vavrusa committed
44
-------------
45

46
Works well on Linux, Mac OS X [#]_ and probably all BSDs. Tested with `Knot DNS Resolver`_, `Unbound`_, and `PowerDNS Recursor`_. It should work with other software as well as long as all functions used by the binary under test are supported by our `modified socket_wrapper`_.
47

48
.. [#] 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.
Marek Vavrusa's avatar
Marek Vavrusa committed
49

Marek Vavrusa's avatar
Marek Vavrusa committed
50

51 52
Usage
-----
Marek Vavrusa's avatar
Marek Vavrusa committed
53

54 55 56
- `User guide <doc/user_guide.rst>`_ describes how to run tests on a binary.
- `Scenario guide <doc/scenario_guide.rst>`_ describes how to write a new test.
- `Devel guide <doc/devel_guide.rst>`_ contains some tips for Deckard developers.
Marek Vavrusa's avatar
Marek Vavrusa committed
57

58

59 60
License
-------
61

62
See `LICENSE <LICENSE>`_ file.
63 64


65 66
Acknowledgments
---------------
67

68
The test scenario design and a lot of tests were written by `NLnet Labs`_ for ``testbound`` suite used by `Unbound`_ (BSD licensed). We are grateful that ``testbound`` authors are `willing to discuss <https://unbound.nlnetlabs.nl/pipermail/unbound-users/2017-March/004699.html>`_ further Deckard development.
69

70
The original test case format is described in the `header file replay.h <http://unbound.net/documentation/doxygen/replay_8h.html#a6f204646f02cc4debbaf8a9b3fdb59a7>`_ distributed with `Unbound`_.
Marek Vavrusa's avatar
Marek Vavrusa committed
71 72


73 74
Contacting us
-------------
Marek Vavrusa's avatar
Marek Vavrusa committed
75

76
Please report problems to our GitLab: https://gitlab.labs.nic.cz/knot/deckard/issues
Marek Vavrusa's avatar
Marek Vavrusa committed
77

78
If you have any comments feel free to send e-mail to knot-dns@labs.nic.cz! Do not get confused by the name, we are happy if you want to use Deckard with any software.
79

80
Happy testing.
81 82


Tomas Krizek's avatar
Tomas Krizek committed
83
.. _`augeas`: http://augeas.net/
84 85
.. _`CSR`: http://apple.stackexchange.com/questions/193368/what-is-the-rootless-feature-in-el-capitan-really
.. _`Jinja2`: http://jinja.pocoo.org/
86
.. _`Knot DNS Resolver`: https://gitlab.labs.nic.cz/knot/resolver/blob/master/README.md
87
.. _`NLnet Labs`: https://www.nlnetlabs.nl/
88
.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/
89
.. _`PyYAML`: http://pyyaml.org/
90
.. _`Unbound`: https://www.unbound.net/
91 92 93 94 95
.. _`cwrap`: https://cwrap.org/
.. _`dnspython`: http://www.dnspython.org/
.. _`libfaketime`: https://github.com/wolfcw/libfaketime
.. _`modified socket_wrapper`: https://gitlab.labs.nic.cz/labs/socket_wrapper
.. _`original socket_wrapper`: https://cwrap.org/socket_wrapper.html
Tomas Krizek's avatar
Tomas Krizek committed
96
.. _`python-augeas`: https://pypi.org/project/python-augeas/
97 98
.. _`pytest`: https://pytest.org/
.. _`pytest-xdist`: https://pypi.python.org/pypi/pytest-xdist