From: Petr Špaček <petr.spacek@nic.cz>
Date: Wed, 18 Apr 2018 12:33:42 +0000 (+0200)
Subject: prefill: documentation
X-Git-Tag: v2.3.0~6^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7b9bb84816178f069acb7caf9ed586c43487b1f5;p=thirdparty%2Fknot-resolver.git

prefill: documentation
---

diff --git a/daemon/README.rst b/daemon/README.rst
index 0a4d27a56..975c01c1b 100644
--- 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 f109b3c88..1d4491f0e 100644
--- 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
index 000000000..678e9f2d5
--- /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