Commit aac89ca9 authored by Grigorii Demidov's avatar Grigorii Demidov

docs: some additions were made

parent 9f38df11
......@@ -19,7 +19,7 @@ Deckard requires next software to be installed:
- Python >= 2.7
- dnspython_ - DNS library for Python.
- Jinja2_ - template engine for generating config files.
- `socket_wrapper`_ - a part of the cwrap_ tool set for creating an isolated networks.
- `socket_wrapper`_ - a modification of `initial socket_wrapper`_ library (part of the cwrap_ tool set for creating an isolated networks).
It also depends on libfaketime_, but it is embedded as it requires a rather recent version (automatically synchronised with ``make``).
......@@ -36,17 +36,13 @@ How to use it
Create a config file template
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the tested server accepts a config file, you have to create a template for it.
If the tested server accepts a config file(s), you have to create a template for it.
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).
- ``ROOT_ADDR`` - root server hint. An IPv4 address like ``127.0.0.{2-40}``,
where the last byte is equal to the ``SOCKET_WRAPPER_DEFAULT_IFACE`` environment variable.
When root hints resides in separated file, this file must be edited manually and the environment variable
must be set in advance. Port is not set and assumed to be equal to 53.
- ``SELF_ADDR`` - assigned address for the tested binary. It is an IPv4 address from ``127.0.0.{2-40}`` range.
Port is not set and assumed to be equal to 53.
- ``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.
- ``NO_MINIMIZE`` - ``'true'`` or ``'false'``, enables or disables query minimization respectively.
- ``WORKING_DIR`` - working directory, equivalent to the value of a ``SOCKET_WRAPPER_DIR``
environment variable.
......@@ -60,8 +56,9 @@ You can alter test process using the Makefile variables:
- ``TESTS`` - path to scenario files; default: ``sets/resolver``
- ``DAEMON`` - path to binary have to be tested; default: ``kresd``
- ``TEMPLATE`` - jinja2 template file to generate configuration file; default: ``kresd.j2``
- ``CONFIG`` - name of configuration file to be generated; default: ``config``
- ``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``
- ``ADDITIONAL`` - additional parameters for binary, intended to test; not set by default
Run it
......@@ -134,7 +131,7 @@ 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 :
- ``SOCKET_WRAPPER_DEFAULT_IFACE`` = 10
- ``SOCKET_WRAPPER_DEFAULT_IFACE`` = 2
- ``SOCKET_WRAPPER_DIR`` will be created in default temporary directory with
randomly generated name, prefixed by ``/tmp``
- ``SOCKET_WRAPPER_DEBUGLEVEL`` will not be set
......@@ -152,7 +149,8 @@ The original test case format is described in the `Doxygen documentation <http:/
.. _cwrap: https://cwrap.org/
.. _`dnspython`: http://www.dnspython.org/
.. _Jinja2: http://jinja.pocoo.org/
.. _`socket_wrapper`: https://cwrap.org/socket_wrapper.html
.. _`socket_wrapper`: https://gitlab.labs.nic.cz/labs/socket_wrapper
.. _`initial socket_wrapper`: https://cwrap.org/socket_wrapper.html
.. _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/
......
......@@ -2,6 +2,7 @@ Scenario example
=================
iter_ns_badaa.rpl
::
; config options
stub-addr: 193.0.14.129 # K.ROOT-SERVERS.NET.
CONFIG_END
......@@ -98,20 +99,11 @@ iter_ns_badaa.rpl
Execution flow :
First of all IP4 addresses, found in the script when parsing will be translated
to 127.0.0.XXX range :
- 193.0.14.129 <==> 127.0.0.2
- 192.5.6.30 <==> 127.0.0.4
- 10.20.30.40 <==> 127.0.0.5
At this example SOCKET_WRAPPED_DEFAULT_IFACE set to 2 and
KRESD_WRAPPER_DEFAULT_IFACE not set, so 127.0.0.3 occupied by Resolver. At next
steps only local addresses will be used.
First, STEP 1 QUERY will be performed.
Next, STEP 1 QUERY will be performed.
Python sends query to Resolver
::
id 31296
opcode QUERY
rcode NOERROR
......@@ -125,9 +117,18 @@ Python sends query to Resolver
;AUTHORITY
;ADDITIONAL
Resolver have been configured to use address 127.0.0.2 as a root server.
So it sends query to Python fake server which listen at address 127.0.0.2
At this scenario stub-addr is set to 193.0.14.129, thus Resolver have been configured to use address
193.0.14.129 as a root server. So it sends query to Python fake server which listen at address 193.0.14.129
::
> [plan] plan 'catalyst.morecowbell.' type 'A'
[resl] => using root hints
[resl] => querying: '193.0.14.129' score: 10 zone cut: '.' m12n: 'CaTALYSt.MoReCoWBEll.' type: 'A'
::
id 7367
opcode QUERY
rcode NOERROR
......@@ -135,7 +136,7 @@ So it sends query to Python fake server which listen at address 127.0.0.2
edns 0
payload 1452
;QUESTION
CAtaLyST.MOreCOWBeLL. IN A
CaTALYSt.MoReCoWBEll. IN A
;ANSWER
;AUTHORITY
;ADDITIONAL
......@@ -143,12 +144,13 @@ So it sends query to Python fake server which listen at address 127.0.0.2
Python fake server starts range analyzing to make answer.
Let's look at first range
::
RANGE_BEGIN 0 100
ADDRESS 193.0.14.129
STEP ID is equal 1, so it matches the condition n1 <= step id <= n2
Next, 193.0.14.129 is mapped to 127.0.0.2.
Since query was directed to 127.0.0.2, this range will be used.
Next, ADDRESS field is equal to 193.0.14.129. Since query was directed
specifically to 193.0.14.129, this range will be used.
Next, Python walks through list of entries to choose eligible entry.
First entry at this range requires comparison of "opcode qtype qname" field list.
......@@ -162,15 +164,20 @@ As we seen, opcode matches.
Let's look at domain names.
ENTRY datablock:
::
SECTION QUESTION
MORECOWBELL. IN A
Incoming query :
::
;QUESTION
caTALysT.moReCoWbEll. IN A
CaTALYSt.MoReCoWBEll. IN A
So, subdomain matches and second entry of first range used as answer pattern.
Python fake server sends answer to Resolver :
::
id 7367
opcode QUERY
rcode NOERROR
......@@ -178,17 +185,26 @@ Python fake server sends answer to Resolver :
edns 0
payload 1280
;QUESTION
CAtaLyST.MOreCOWBeLL. IN A
CaTALYSt.MoReCoWBEll. IN A
;ANSWER
;AUTHORITY
MORECOWBELL. 3600 IN NS a.gtld-servers.net.
;ADDITIONAL
a.gtld-servers.net. 3600 IN A 127.0.0.4
a.gtld-servers.net. 3600 IN A 192.5.6.30
Note that additional section contains local IP. Because new address is found,
Note that additional section contains IP address. Because new address is found,
Python fake server immediately starts listening on this address.
Resolver sends next query to 127.0.0.4:
Resolver sends next query to 192.5.6.30:
::
[iter] <= referral response, follow
[ pc ] => answer cached for TTL=900
[resl] => querying: '192.5.6.30' score: 10 zone cut: 'morecowbell.' m12n: 'catalyst.mOREcoWBEll.' type: 'A'
::
id 58167
opcode QUERY
rcode NOERROR
......@@ -196,14 +212,15 @@ Resolver sends next query to 127.0.0.4:
edns 0
payload 1452
;QUESTION
cAtaLyst.MoRECowBEll. IN A
catalyst.mOREcoWBEll. IN A
;ANSWER
;AUTHORITY
;ADDITIONAL
Since query is directed to 127.0.0.4 which mapped to 192.5.6.30,
Since query is directed to 192.5.6.30,
this range will be analyzed :
::
; a.gtld-servers.net.
RANGE_BEGIN 0 100
ADDRESS 192.5.6.30
......@@ -213,16 +230,20 @@ Opcode and qtype fields are the same as fields in incoming query.
Let's compare qname.
ENTRY datablock :
::
SECTION QUESTION
CATALYST.MORECOWBELL. IN A
Incoming query :
::
;QUESTION
cAtaLyst.MoRECowBEll. IN A
catalyst.mOREcoWBEll. IN A
So, qname also the same. All fields matches and Python server sends answer
derived from this entry :
::
id 58167
opcode QUERY
rcode NOERROR
......@@ -232,16 +253,25 @@ derived from this entry :
;QUESTION
cAtaLyst.MoRECowBEll. IN A
;ANSWER
CATALYST.MORECOWBELL. 3600 IN A 127.0.0.5
CATALYST.MORECOWBELL. 3600 IN A 10.20.30.40
;AUTHORITY
CATALYST.MORECOWBELL. 3600 IN NS a.gtld-servers.net.
;ADDITIONAL
Here Python found new address 127.0.0.5 and starts listening.
Here Python found new address 10.20.30.40 and starts listening.
Next queries and answers :
query; Resolver ---> Python (127.0.0.2)
::
[iter] <= referral response, follow
[plan] plan 'a.gtld-servers.net.' type 'AAAA'
[resl] => using root hints
[resl] => querying: '193.0.14.129' score: 54 zone cut: '.' m12n: 'A.Gtld-sERverS.nEt.' type: 'AAAA'
query; Resolver ---> Python (193.0.14.129)
::
id 13810
opcode QUERY
rcode NOERROR
......@@ -249,13 +279,14 @@ query; Resolver ---> Python (127.0.0.2)
edns 0
payload 1452
;QUESTION
A.gTld-serveRS.NET. IN AAAA
A.Gtld-sERverS.nEt. IN AAAA
;ANSWER
;AUTHORITY
;ADDITIONAL
answer; Python ---> Resolver
::
id 13810
opcode QUERY
rcode NOERROR
......@@ -269,76 +300,29 @@ answer; Python ---> Resolver
. 3600 IN SOA bla. bla. 1 2 3 4 5
;ADDITIONAL
query; Resolver ---> Python (127.0.0.2)
::
id 20735
opcode QUERY
rcode NOERROR
flags
edns 0
payload 1452
;QUESTION
A.gTLd-seRVeRs.nEt. IN A
;ANSWER
;AUTHORITY
;ADDITIONAL
answer; Python ---> Resolver
at this point Resolver returns answer to query from STEP 1 QUERY.
::
id 20735
opcode QUERY
rcode NOERROR
flags QR
edns 0
payload 1280
;QUESTION
A.gTLd-seRVeRs.nEt. IN A
;ANSWER
a.gtld-servers.net. 3600 IN A 127.0.0.4
;AUTHORITY
;ADDITIONAL
query; Resolver ---> Python (127.0.0.4)
::
id 10288
opcode QUERY
rcode NOERROR
flags
edns 0
payload 1452
;QUESTION
CAtalYst.MORECowBeLl. IN A
;ANSWER
;AUTHORITY
;ADDITIONAL
[iter] <= rcode: NOERROR
[ pc ] => answer cached for TTL=900
[ rc ] => satisfied from cache
[iter] <= rcode: NOERROR
[resl] finished: 4, queries: 2, mempool: 16400 B
answer; Python ---> Resolver
::
id 10288
opcode QUERY
rcode NOERROR
flags QR AA
edns 0
payload 1280
;QUESTION
CAtalYst.MORECowBeLl. IN A
;ANSWER
CATALYST.MORECOWBELL. 3600 IN A 127.0.0.5
;AUTHORITY
CATALYST.MORECOWBELL. 3600 IN NS a.gtld-servers.net.
;ADDITIONAL
at this point Resolver returns answer to query from STEP 1 QUERY.
::
opcode QUERY
rcode NOERROR
flags QR RD RA
edns 0
payload 1452
payload 4096
;QUESTION
catalyst.morecowbell. IN A
;ANSWER
catalyst.morecowbell. 3600 IN A 127.0.0.5
catalyst.morecowbell. 3600 IN A 10.20.30.40
;AUTHORITY
;ADDITIONAL
......@@ -346,9 +330,8 @@ Now STEP 10 will be performed. Is has a single entry which contains
**MATCH all** clause. **MATCH all** means set of dns flags must be equal and
all sections presented in ENTRY must be equal to ones in answer.
Incoming answer has next flags were set: **QR RD AA**. ENTRY datablock contains
**REPLY QR RD RA NOERROR** clause. As we see, flags set is equal. If we remember
that address 10.20.30.40 is mapped to 127.0.0.5, we easily can see equality of
question and answer sections of both dns messages.
**REPLY QR RD RA NOERROR** clause. As we see, flags set is equal. Also, we can
see equality of question and answer sections of both dns messages.
So, Python got expected answer and test is passed.
......@@ -20,12 +20,6 @@ Sets like a dns message sections. **RAW** contains single-line data which will b
interpreted as raw dns message. Lines started with semicolon (;) are ignored
and can be used as comments.
Notice that configuration values, header data or **SECTION** blocks can contain
IP addresses. Despite the fact that socket wrapper can only deal with a range
of 127.0.0.2-127.0.0.254 (or fd00::5357:5f02 - fd00::5357:5ffE) it's not
necessary to use only these ranges. Arbitrary addresses can be used. They
will be automatically translated to local addresses.
**Configuration**
Configuration part is a list of "key : value" pairs, one pair per line.
......@@ -39,8 +33,9 @@ Next keys can be used
means query minimization algorithm will not be used.
- **stub-addr** : ipv4-addr
address will be translated to default local address, which will be listened
by Python fake dns server immediately after startup.
address, which will be listened by Python fake dns server immediately after startup.
When configuration files will be generated by Jinja2 engine, ``ROOT_ADDR`` template
variable will be replaced by this address.
- **thrust-anchor** : ``string value``
Delegation Signer record, can be used for DNSSEC-related scenarios
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment