From: Vladimír Čunát <vladimir.cunat@nic.cz>
Date: Wed, 8 May 2024 06:27:06 +0000 (+0200)
Subject: modules/hints docs: transplant text from the user docs
X-Git-Tag: v6.0.12~2^2~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2053514b095cd3835c0c56ca1e4f5115b8d863e6;p=thirdparty%2Fknot-resolver.git

modules/hints docs: transplant text from the user docs

It will be deleted from user docs, and perhaps it could be useful.
---

diff --git a/modules/hints/README.rst b/modules/hints/README.rst
index 7d7751882..386493ce9 100644
--- a/modules/hints/README.rst
+++ b/modules/hints/README.rst
@@ -101,6 +101,7 @@ Properties
 .. function:: hints.root_file(path)
 
   Replace current root hints from a zonefile.  If the path is omitted, the compiled-in path is used, i.e. the root hints are reset to the default.
+  Otherwise it's the same as the following option.
 
 .. function:: hints.root(root_hints)
 
@@ -109,8 +110,14 @@ Properties
 
   Replace current root hints and return the current table of root hints.
 
-  These root hints are only used as fallback when addresses of ``NS .`` aren't available,
-  e.g. when cache is completely clear.
+  If a resolver is not set up to forward requests, it must have some method of locating root servers.
+  This is typically done by using a predefined list of root server addresses,
+  referred to as SBELT in :rfc:`1034`, which acts as a fallback.
+
+  Knot Resolver includes an up-to-date list by default, since root server addresses very rarely change.
+  However, this default can be overridden at ``configure`` time (``root_hints`` meson option),
+  and you can also override it via ``hints.root(..)`` or ``hints.root_file(..)`` at runtime.
+  Some Linux distributions maintain it in a separate package.
 
   .. tip:: If no parameters are passed, it only returns current root hints set without changing anything.