prefill: documentation

diff --git a/daemon/README.rst b/daemon/README.rst
index 0a4d27a56609ded92dff55f02e32950fc72dac9a..975c01c1bf4dea08a7387365a89204dcd21ee407 100644 (file)
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -1024,6 +1024,8 @@ The daemon also supports `systemd socket activation`_, it is automatically detec
 
 See ``kresd.systemd(7)`` for details.
 
+.. _enabling-dnssec:
+
 Enabling DNSSEC
 ===============
 

diff --git a/doc/modules.rst b/doc/modules.rst
index f109b3c8850b28f7fd42fb5e4592a5629013a198..1d4491f0e25c7c6b2d3d38a5e5b9d635cae1f6e2 100644 (file)
--- a/doc/modules.rst
+++ b/doc/modules.rst
@@ -31,3 +31,4 @@ Knot DNS Resolver modules
 .. include:: ../modules/serve_stale/README.rst
 .. include:: ../modules/detect_time_skew/README.rst
 .. include:: ../modules/detect_time_jump/README.rst
+.. include:: ../modules/prefill/README.rst

diff --git a/modules/prefill/README.rst b/modules/prefill/README.rst
new file mode 100644 (file)
index 0000000..678e9f2
--- /dev/null
+++ b/modules/prefill/README.rst
@@ -0,0 +1,39 @@
+Cache prefilling
+----------------
+
+This module provides ability to periodically prefill DNS cache by importing root zone data obtained over HTTPS.
+
+Intended users of this module are big resolver operators which will benefit from decreased latencies and smaller amount of traffic towards DNS root servets.
+
+Example configuration is:
+
+.. code-block:: lua
+
+       modules.load('prefill')
+       prefill.config({
+              ['.'] = {
+                      url = 'https://www.internic.net/domain/root.zone',
+                      ca_file = '/etc/pki/tls/certs/ca-bundle.crt',
+                      interval = 86400  -- seconds
+              }
+        })
+
+This configuration downloads zone file from URL `https://www.internic.net/domain/root.zone` and imports it into cache every 86400 seconds (1 day). The HTTPS connection is authenticated using CA certificate from file `/etc/pki/tls/certs/ca-bundle.crt` and signed zone content is validated using DNSSEC.
+
+Root zone to import must be signed using DNSSEC and the resolver must have valid DNSSEC configuration. (For further details please see :ref:`enabling-dnssec`.)
+
+.. csv-table::
+ :header: "Parameter", "Description"
+
+ "ca_file", "path to CA certificate bundle used to authenticate the HTTPS connection"
+ "interval", "number of seconds between zone data refresh attempts"
+ "url", "URL of a file in :rfc:`1035` zone file format"
+
+Only root zone import is supported at the moment.
+
+Dependencies
+^^^^^^^^^^^^
+
+Depends on the luasec_ library.
+
+.. _luasec: https://luarocks.org/modules/brunoos/luasec