From 529589af6117dbdead15478e8a84c6a826583ec7 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Ale=C5=A1=20Mr=C3=A1zek?= <ales.mrazek@nic.cz>
Date: Mon, 3 Jul 2023 17:23:26 +0200
Subject: [PATCH] docs: config: yaml for cache prefill

---
 doc/config-cache-prefill.rst | 50 ++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 doc/config-cache-prefill.rst

diff --git a/doc/config-cache-prefill.rst b/doc/config-cache-prefill.rst
new file mode 100644
index 000000000..d8a867844
--- /dev/null
+++ b/doc/config-cache-prefill.rst
@@ -0,0 +1,50 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-cache-prefill:
+
+Cache prefilling
+================
+
+This provides ability to periodically prefill the 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 servers.
+
+
+.. option:: cache/prefill: <list>
+   .. option:: origin: <zone name>
+
+      Name of the zone, only root zone import is supported at the moment.
+
+   .. option:: url: <url string>
+
+      URL of a file in :rfc:`1035` zone file format.
+
+   .. option:: refresh-interval: <time ms|s|m|h|d>
+      :default: 1d
+
+      Time between zone data refresh attempts.
+
+   .. option:: ca-file: <path>
+
+      Path to CA certificate bundle used to authenticate the HTTPS connection (optional, system-wide store will be used if not specified)
+
+.. code-block:: yaml
+
+   cache:
+     prefill:
+       - origin: "."
+         url: https://www.internic.net/domain/root.zone
+         refresh-interval: 12h
+         ca-file: /etc/pki/tls/certs/ca-bundle.crt
+
+This configuration downloads the zone file from URL `https://www.internic.net/domain/root.zone` and imports it into the cache every day. The HTTPS connection is authenticated using a CA certificate from file `/etc/pki/tls/certs/ca-bundle.crt` and signed zone content is validated using DNSSEC.
+
+The root zone to be imported must be signed using DNSSEC and the resolver must have a valid DNSSEC configuration.
+
+
+Dependencies
+------------
+
+Prefilling depends on the lua-http_ library.
+
+.. _lua-http: https://luarocks.org/modules/daurnimator/http
-- 
2.47.2