auth: catalog zone documentation

diff --git a/docs/backends/index.rst b/docs/backends/index.rst
index d72f52efbd8506c688b3af6b7643167a22a60ec0..e10956d6639597b21992bc66a6b235468447c2b1 100644 (file)
--- a/docs/backends/index.rst
+++ b/docs/backends/index.rst
@@ -3,35 +3,35 @@ Backends
 
 The following table describes the supported backends and some of their capabilities.
 
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| Name                                           | Native | Master | Slave | Super slave  | :doc:`Dynamic DNS Update <../dnsupdate>` | :doc:`DNSSEC <../dnssec/index>` | Launch       |
-+================================================+========+========+=======+==============+==========================================+=================================+==============+
-| :doc:`BIND <bind>`                             | Yes    | Yes    | Yes   | Experimental | No                                       | Yes                             | ``bind``     |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Generic Mysql <generic-mysql>`           | Yes    | Yes    | Yes   | Yes          | Yes                                      | Yes                             | ``gmysql``   |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Generic ODBC <generic-odbc>`             | Yes    | Yes    | Yes   | Yes          | Yes                                      | Yes                             | ``godbc``    |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Generic Postgresql <generic-postgresql>` | Yes    | Yes    | Yes   | Yes          | Yes                                      | Yes                             | ``gpgsql``   |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Generic SQLite3 <generic-sqlite3>`       | Yes    | Yes    | Yes   | Yes          | Yes                                      | Yes                             | ``gsqlite3`` |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`GeoIP <geoip>`                           | Yes    | No     | No    | No           | No                                       | Yes                             | ``geoip``    |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`LDAP <ldap>`                             | Yes    | Yes    | No    | No           | No                                       | No                              | ``ldap``     |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`LMDB <lmdb>`                             | Yes    | Yes    | Yes   | No           | No                                       | Yes                             | ``lmdb``     |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Lua2 <lua2>`                             | Yes    | Yes    | No    | No           | No                                       | Yes                             | ``lua2``     |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Pipe <pipe>`                             | Yes    | No     | No    | No           | No                                       | Partial                         | ``pipe``     |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Random <random>`                         | Yes    | No     | No    | No           | No                                       | Partial                         | ``random``   |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`Remote <remote>`                         | Yes    | Yes\*  | Yes\* | Yes\*        | No                                       | Yes\*                           | ``remote``   |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
-| :doc:`TinyDNS <tinydns>`                       | Yes    | Yes    | No    | No           | No                                       | Partial                         | ``tinydns``  |
-+------------------------------------------------+--------+--------+-------+--------------+------------------------------------------+---------------------------------+--------------+
++------------------------------------------------+--------+-------- +-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| Name                                           | Native | Primary | Secondary | Producer | Consumer | Autoprimary  | :doc:`DNS Update <../dnsupdate>` | :doc:`DNSSEC <../dnssec/index>` | Launch       |
++================================================+========+=========+===========+==========+==========+==============+==================================+=================================+==============+
+| :doc:`BIND <bind>`                             | Yes    | Yes     | Yes       | No       | No       | Yes          | No                               | Yes                             | ``bind``     |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Generic Mysql <generic-mysql>`           | Yes    | Yes     | Yes       | Yes      | Yes      | Yes          | Yes                              | Yes                             | ``gmysql``   |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Generic ODBC <generic-odbc>`             | Yes    | Yes     | Yes       | Yes      | Yes      | Yes          | Yes                              | Yes                             | ``godbc``    |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Generic Postgresql <generic-postgresql>` | Yes    | Yes     | Yes       | Yes      | Yes      | Yes          | Yes                              | Yes                             | ``gpgsql``   |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Generic SQLite3 <generic-sqlite3>`       | Yes    | Yes     | Yes       | Yes      | Yes      | Yes          | Yes                              | Yes                             | ``gsqlite3`` |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`GeoIP <geoip>`                           | Yes    | No      | No        | No       | No       | No           | No                               | Yes                             | ``geoip``    |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`LDAP <ldap>`                             | Yes    | Yes     | No        | No       | No       | No           | No                               | No                              | ``ldap``     |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`LMDB <lmdb>`                             | Yes    | Yes     | Yes       | Yes      | Yes      | No           | No                               | Yes                             | ``lmdb``     |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Lua2 <lua2>`                             | Yes    | Yes     | No        | No       | No       | No           | No                               | Yes                             | ``lua2``     |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Pipe <pipe>`                             | Yes    | No      | No        | No       | No       | No           | No                               | No                              | ``pipe``     |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`Random <random>`                         | Yes    | No      | No        | No       | No       | No           | No                               | No                              | ``random``   |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+-----------------------------------------------+
+| :doc:`Remote <remote>`                         | Yes    | Yes\*   | Yes\*     | No       | No       | Yes\*        | No                               | Yes\*                           | ``remote``   |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
+| :doc:`TinyDNS <tinydns>`                       | Yes    | Yes     | No        | No       | No       | No           | No                               | No                              | ``tinydns``  |
++------------------------------------------------+--------+---------+-----------+----------+----------+--------------+----------------------------------+---------------------------------+--------------+
 
 All the generic SQL backends have similar functionality, apart from the database they communicate with.
 These backends have :doc:`features unique <generic-sql>` to the generic SQL backends.

diff --git a/docs/catalog.rst b/docs/catalog.rst
new file mode 100644 (file)
index 0000000..4703d8f
--- /dev/null
+++ b/docs/catalog.rst
@@ -0,0 +1,112 @@
+Catalog Zone (RFC  TBD)
+=======================
+
+Starting with the PowerDNS Authoritative Server 4.7.0, catalog zone support is available. The current supported catalog version is "2". All all the important features of catalog zones are supported. There are however a few properties where support is limited:
+
+-  There is no support for group templates on consumers;
+-  There is no support for custom extensions;
+
+The implementation requires the backend to support a number of new operations. Currently, the following backends have been modified to support catalog zones:
+
+- :doc:`gmysql <backends/generic-mysql>`
+- :doc:`gpgsql <backends/generic-postgresql>`
+- :doc:`gsqlite3 <backends/generic-sqlite3>`
+- :doc:`godbc <backends/generic-odbc>`
+- :doc:`lmdb <backends/lmdb>`
+
+.. _catalog-configuration-options:
+
+Configuration options
+---------------------
+
+None really.
+
+.. _catalog-metadata:
+
+Per zone settings
+-----------------
+
+It is highly recommended to protect catalog zones with :doc:`TSIG <../tsig>`
+
+CATALOG-HASH
+~~~~~~~~~~~~
+
+Producer zones are storing the member state as a hash in this metadata setting. This setting is managed by the authoritative server. Modify or deleting this value will result in a serial increase of the producer zone and the update or recreation of this value.
+
+Setup Catalog Zones
+-------------------
+
+.. note::
+  Catalog zone specification and operation is described in `DNS Catalog Zones <https://datatracker.ietf.org/doc/draft-ietf-dnsop-dns-catalog-zones)>`__.
+
+Setting up a producer zone
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting up a producer zone is not very different from a regular primary zone. A producer zone is a minimal zone of type CONSUMER with only SOA and NS records at apex. All the records in a producer zone are ignored while generating a catalog.
+
+A initial producer zone may look like this:
+
+::
+
+  $TTL 3600
+  $ORIGIN catalog.invalid.
+  @               IN      SOA     ns1.zone.invalid. hostmaster.zone.invalid. (  1
+                          1H ; refresh
+                          10M ; retry
+                          1W ; expire
+                          1800 ; default_ttl
+                          )
+
+  @               IN      NS      ns1.zone.invalid.
+
+An interesting detail is the serial. Since the serial of a producer zone is automatically updated, it is important for the initial serial to be equal or lower than epoch. This serial is increased to EPOCH after each relevant member update.
+
+Create a producer zone:
+
+.. code-block:: shell
+
+  pdnsutil load-zone catalog.invalid zones/catalog.invalid ZONEFILE
+  pdnsutil set-kind catalog.invalid producer
+
+Creating producer zones is supported in the :doc:`API <http-api/zone>`.
+
+Assigning members to a producer zone
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After the producer zone is created it is necessary to assign member zone to it. In the example below example.com is the member and catalog.invalid is the catalog.
+
+.. code-block:: shell
+
+  pdnsutil set-catalog example.com catalog.invalid
+
+Setting catalog values is supported in the :doc:`API <http-api/zone>`.
+
+Each member zone may have one or more additional properties. PowerDNS supports the flowing properties:
+
+- coo - A single DNSName
+- group - Multiple string values for group are allowed
+
+.. code-block:: shell
+
+  pdnsutil set-option example.com producer coo other-catalog.invalid
+  pdnsutil set-option example.com producer group pdns-group-x pdns-group-y
+
+There is also an option to set a specific <unique-N> value for a zone this is done by setting a the `unique` value. This is used to signal a state reset to the consumer. The value u unique is a single dns label.
+
+.. code-block:: shell
+
+  pdnsutil --config-dir=. --config-name=gmysql set-option test.com producer unique 123
+
+Setting options is not yet supported in the API.`
+
+Setting up a consumer zone
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting up a consumer zone on a secondary server is almost identical to a normal secondary zone.
+
+.. code-block:: shell
+
+  pdnsutil create-secondary-zone catalog.invalid 127.0.0.1
+  pdnsutil set-kind catalog.invalid consumer
+
+Creating producer zones is supported in the :doc:`API <http-api/zone>`.

diff --git a/docs/indexTOC.rst b/docs/indexTOC.rst
index bad9bfcab980c7e72b7eb6266c69e6a1bed30b30..6301756ff0e9159ab4e39b2d995f738609321fc9 100644 (file)
--- a/docs/indexTOC.rst
+++ b/docs/indexTOC.rst
@@ -16,6 +16,7 @@ PowerDNS Authoritative Server
     dnssec/index
     domainmetadata
     dnsupdate
+    catalog
     tsig
     lua-records/index
     guides/index