Basic docs

diff --git a/pdns/recursordist/settings/docs-new-preamble-in.rst b/pdns/recursordist/settings/docs-new-preamble-in.rst
index 28faf8e846197bfde8430568e82e0d9d21a47ac3..667aaad03ff1fed4f80b0addb4bcce5a78643145 100644 (file)
--- 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
 -----------------