From 46e35887cb0f861831c6cb01c7ac85c0aa84cc2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Vavru=C5=A1a?= <marek.vavrusa@nic.cz>
Date: Fri, 25 Sep 2015 16:58:46 +0200
Subject: [PATCH] daemon: added basic doc for trust_anchors and DNSSEC
---
daemon/README.rst | 74 ++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 67 insertions(+), 7 deletions(-)
diff --git a/daemon/README.rst b/daemon/README.rst
index 7ac1c3ab1..885160bda 100644
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -132,8 +132,6 @@ the modules use as the :ref:`input configuration <mod-properties>`.
}
}
-The possible simple data types are: string, integer or float, and boolean.
-
.. tip:: The configuration and CLI syntax is Lua language, with which you may already be familiar with.
If not, you can read the `Learn Lua in 15 minutes`_ for a syntax overview. Spending just a few minutes
will allow you to break from static configuration, write more efficient configuration with iteration, and
@@ -179,7 +177,7 @@ to download cache from parent, to avoid cold-cache start.
sink = ltn12.sink.file(io.open('cache.mdb', 'w'))
}
-- reopen cache with 100M limit
- cache.open(100*MB)
+ cache.size = 100*MB
end
Events and services
@@ -333,6 +331,70 @@ For when listening on ``localhost`` just doesn't cut it.
.. tip:: You can use ``net.<iface>`` as a shortcut for specific interface, e.g. ``net.eth0``
+Trust anchors and DNSSEC
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The resolver supports DNSSEC including :rfc:`5011` automated DNSSEC TA updates and :rfc:`7646` negative trust anchors.
+To enable it, you need to provide at least _one_ trust anchor. This step is not automatic, as you're supposed to obtain
+the trust anchor using a secure channel. From there, the Knot DNS Resolver can perform automatic updates for you if you
+run in managed mode.
+
+The recommended way is as follows:
+
+1. Check the current TA published on `IANA website <https://data.iana.org/root-anchors/root-anchors.xml>`_
+2. Fetch current keys, verify and use
+.. code-block:: bash
+
+ $ kdig dnskey . @a.root-servers.net +noall +answer | grep 257 > root.keys
+ $ ldns-key2ds -n root.keys
+ ... verify that digest matches TA published by IANA ...
+ $ kresd -k root.keys
+
+You've just enabled DNSSEC, congratulations!
+
+.. function:: trust_anchors.config(keyfile)
+
+ :param string keyfile: File containing DNSKEY records, should be writeable.
+
+ You can use only DNSKEY records in managed mode. It is equivalent to CLI parameter `-k <keyfile>` or `trust_anchors.file = keyfile`.
+
+ Example output:
+
+ .. code-block:: lua
+
+ > trust_anchors.config('root.keys')
+ [trust_anchors] key: 19036 state: Valid
+
+.. function:: trust_anchors.add(rr_string)
+
+ :param string rr_string: DS/DNSKEY records in presentation format (e.g. `. 3600 IN DS 19036 8 2 49AAC11...`)
+
+ Inserts DS/DNSKEY record(s) into current keyset. These will not be managed or updated.
+
+ Example output:
+
+ .. code-block:: lua
+
+ > trust_anchors.add('. 3600 IN DS 19036 8 2 49AAC11...')
+
+.. function:: trust_anchors.set_insecure(nta_set)
+
+ :param table nta_list: List of domain names (text format) representing NTAs.
+
+ When you use a domain name as an NTA, DNSSEC validation will be turned off at/below these names.
+ Each function call replaces the previous NTA set. You can find the current active set in `trust_anchors.insecure` variable.
+
+ .. tip:: Use the `trust_anchors.negative = {}` alias for easier configuration.
+
+ Example output:
+
+ .. code-block:: lua
+
+ > trust_anchors.negative = { 'bad.boy', 'example.com' }
+ > trust_anchors.insecure
+ [1] => bad.boy
+ [2] => example.com
+
Modules configuration
^^^^^^^^^^^^^^^^^^^^^
@@ -534,17 +596,15 @@ you can see the statistics or schedule new queries.
print(worker.stats().concurrent)
-.. function:: worker.resolve(qname, qtype[, qclass = kres.class.IN, options = 0])
+.. function:: worker.resolve(qname, qtype[, qclass = kres.class.IN, options = 0, callback = nil])
:param string qname: Query name (e.g. 'com.')
:param number qtype: Query type (e.g. ``kres.type.NS``)
:param number qclass: Query class *(optional)* (e.g. ``kres.class.IN``)
:param number options: Resolution options (see query flags)
+ :param function callback: Callback to be executed when resolution completes (e.g. `function cb (pkt) end`). The callback gets a packet containing the final answer and doesn't have to return anything.
:return: boolean
- Resolve a query, there is currently no callback when its finished, but you can track the query
- progress in layers, just like any other query.
-
.. _`JSON-encoded`: http://json.org/example
.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/scripting/
--
GitLab