From: Otto Moerbeek <otto.moerbeek@open-xchange.com>
Date: Tue, 8 Oct 2024 12:41:01 +0000 (+0200)
Subject: Basic docs
X-Git-Tag: rec-5.2.0-alpha1~7^2~11
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=330628086850cc813037bbe4483b59d2de37daf5;p=thirdparty%2Fpdns.git

Basic docs
---

diff --git a/pdns/recursordist/settings/docs-new-preamble-in.rst b/pdns/recursordist/settings/docs-new-preamble-in.rst
index 28faf8e846..667aaad03f 100644
--- a/pdns/recursordist/settings/docs-new-preamble-in.rst
+++ b/pdns/recursordist/settings/docs-new-preamble-in.rst
@@ -472,6 +472,57 @@ An example of an ``proxymappings`` entry, which is a sequence of `ProxyMapping`_
          - example.com
          - example.net
 
+ForwardingCatalogZone
+^^^^^^^^^^^^^^^^^^^^^
+As of version 5.2.0, a forwarding catalog zone entry is defined as:
+
+.. code-block:: yaml
+
+     zone: Name of catalog zone
+     notify_allowed: bool, default false
+     xfr:
+       addresses: [] Sequence of SocketAddress
+       zoneSizeHint: number, default not set
+       tsig:
+         name: string
+         algo: string
+         secret: base64string
+       refresh: number, default not set
+       maxReceivedMBytes: number default not set
+       localAddress: IP address, default not set
+       axfrTimeout: number, default 20
+     groups:
+     - name:
+       forwarders: [] Sequence of SocketAddress
+       recurse: bool, default false
+       notify: bool, default false
+
+An example of an ``forwarding_catalog_zones`` entry, which is a sequence of `ForwardingCatalogZone`_:
+
+.. code-block:: yaml
+
+   forwarding_catalog_zones:
+   - zone: 'forward.example'
+     xfr:
+       addresses: [128.66.1.2]
+     groups:
+      - forwarders: [192.168.178.1] # default forwarder
+      - name: mygroup
+        forwarders: [192.168.179.2] # forwarder for catalog zone members in mygroup
+        recurse: true
+        notify_allowed: true
+   - zone: 'forward2.example'
+     xfr:
+       addresses: [128.66.1.3]
+     groups:
+      - forwarders: [192.168.178.3] # only default forwarder for 2nd catalog zone
+
+:program:`Recursor` will transfer the catalog zone from te authoritative server using IXFR (falling back to AXFR if needed) and add forwarding clauses for all members of the catalog zone.
+The forwarding paremeters will be taken from the default group entry (the one without a name) defined in the YAML settings.
+For catalog zone members in a group, the forwarding parameters will be taken from the group entry with the correspoding name.
+
+The forwarding definitions will be written into a file ``$api_dir/catzone.$zonename``. :ref:`setting-yaml-webservice.api_dir` must be defined, the directory must exist and be writable by the :program:`Recursor` process.
+
 The YAML settings
 -----------------