From: Pieter Lexis Date: Tue, 22 Aug 2017 15:06:47 +0000 (+0200) Subject: doc: Add missing Zone properties and SOA-EDIT-API X-Git-Tag: auth-4.1.0-rc1~5^2~2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=cd46fc6cabe00e9dc7ab823e415c83b6e0ecd7f7;p=thirdparty%2Fpdns.git doc: Add missing Zone properties and SOA-EDIT-API Closes #3895 Closes #4129 --- diff --git a/docs/dnsupdate.rst b/docs/dnsupdate.rst index c8bc41c017..686b23bf4c 100644 --- a/docs/dnsupdate.rst +++ b/docs/dnsupdate.rst @@ -170,6 +170,8 @@ verification. 5 sql> insert into domainmetadata(domain_id, kind, content) values(5, ‘NOTIFY-DNSUPDATE’,’1’); +.. _metadata-soa-edit-dnsupdate: + SOA-EDIT-DNSUPDATE ~~~~~~~~~~~~~~~~~~ diff --git a/docs/domainmetadata.rst b/docs/domainmetadata.rst index 97f383e5ed..c58917ebc6 100644 --- a/docs/domainmetadata.rst +++ b/docs/domainmetadata.rst @@ -169,6 +169,19 @@ fresh RRSIGs. See the :ref:`DNSSEC documentation ` for more information. +.. _metadata-soa-edit-api: + +SOA-EDIT-API +------------ + +On changes to the contents of a zone made through the :doc:`API `, +the SOA record will be edited according to the SOA-EDIT-API rules. These rules +are the same as the :ref:`SOA-EDIT-DNSUPDATE ` rules. +If not set during zone creation, a SOA-EDIT-API metadata record is created and set to ``DEFAULT``. +If this record is removed from the backend, the default behaviour is to not do any SOA editing based on this setting. +This is different from setting ``DEFAULT``. + + TSIG-ALLOW-AXFR --------------- diff --git a/docs/http-api/endpoint-zones.rst b/docs/http-api/endpoint-zones.rst index 2a1c369503..4e82e1f0f3 100644 --- a/docs/http-api/endpoint-zones.rst +++ b/docs/http-api/endpoint-zones.rst @@ -12,6 +12,8 @@ Zones endpoint :param server_id: The name of the server + A :json:object:`Zone` MUST be sent in the request body. + - ``dnssec``, ``nsec3narrow``, ``presigned``, ``nsec3param``, ``active-keys`` are OPTIONAL. - ``dnssec``, ``nsec3narrow``, ``presigned`` default to ``false``. diff --git a/docs/http-api/zone-properties.rst b/docs/http-api/zone-properties.rst index 64806bd188..dda636e0d1 100644 --- a/docs/http-api/zone-properties.rst +++ b/docs/http-api/zone-properties.rst @@ -1,3 +1,4 @@ + :property integer serial: The SOA serial number :property integer notified_serial: The SOA serial notifications have been sent out for :property [str] masters: List of IP addresses configured as a master for this zone ("Slave" type zones only) @@ -5,58 +6,37 @@ :property string nsec3param: The NSEC3PARAM record (not implemented) :property bool nsec3narrow: Whether or not the zone uses NSEC3 narrow (not implemented) :property bool presigned: Whether or not the zone is pre-signed (not implemented) - :property string soa_edit: The SOA-EDIT metadata item. MAY be set to change the ``SOA-EDIT`` zone setting. - :property string soa_edit_api: The SOA-EDIT-API metadata item + :property string soa_edit: The :ref:`metadata-soa-edit` metadata item + :property string soa_edit_api: The :ref:`metadata-soa-edit-api` metadata item + :property string zone: May contain a BIND-style zone file when creating a zone + :property str account: MAY be set. Its value is defined by local policy + :property [str] nameservers: MAY be sent in client bodies during creation, and MUST NOT be sent by the server. Simple list of strings of nameserver names, including the trailing dot. Not required for slave zones. +.. note:: + Switching ``dnssec`` to ``true`` (from ``false``) sets up DNSSEC signing + based on the other flags, this includes running the equivalent of + ``secure-zone`` and ``rectify-zone``. This also applies to newly created + zones. If ``presigned`` is ``true``, no DNSSEC changes will be made to + the zone or cryptokeys. -Switching ``dnssec`` to ``true`` (from ``false``) sets up DNSSEC signing -based on the other flags, this includes running the equivalent of -``secure-zone`` and ``rectify-zone``. This also applies to newly created -zones. If ``presigned`` is ``true``, no DNSSEC changes will be made to -the zone or cryptokeys. . + ``dnssec``, ``nsec3narrow``, ``nsec3param``, ``presigned`` are not yet implemented. -**TODO**: ``dnssec``, ``nsec3narrow``, ``nsec3param``, ``presigned`` are -not yet implemented. +.. note:: -- ``soa_edit_api`` MAY be set. If it is set, on changes to the contents - of a zone made through the API, the SOA record will be edited - according to the SOA-EDIT-API rules. (Which are the same as the - SOA-EDIT-DNSUPDATE rules.) If not set during zone creation, a - SOA-EDIT-API metadata record is created and set to ``DEFAULT``. (If - this record is removed from the backend, the default behaviour is to - not do any SOA editing based on this setting. This is different from - setting ``DEFAULT``). - -- ``account`` MAY be set. Its value is defined by local policy. - -- ``notified_serial``, ``serial`` MUST NOT be sent in client bodies. - -- ``nameservers`` MAY be sent in client bodies during creation, and - MUST NOT be sent by the server. Simple list of strings of nameserver - names, including the trailing dot. Note: Before 4.0.0, names were - taken without the trailing dot. . Not - required for slave zones. - -- ``rrsets``: list of DNS records and comments in the zone. - -Please see the description for ``PATCH`` for details on the fields in -``RRset``, ``Record`` and ``Comment``. - -Turning on DNSSEC with custom keys: just create the zone with ``dnssec`` -set to ``false``, and add keys using the cryptokeys REST interface. Have -at least one of them ``active`` set to ``true``. **TODO**: not yet -implemented. + ``notified_serial``, ``serial`` MUST NOT be sent in client bodies. Changes made through the Zones API will always yield valid zone data, -and the zone will be properly "rectified" (**TODO**: not yet -implemented). If changes are made through other means (e.g. direct -database access), this is not guaranteed to be true and clients SHOULD +and the zone will be properly "rectified". If changes are made through other means +(e.g. direct database access), this is not guaranteed to be true and clients SHOULD trigger rectify. +.. note:: + + Rectification is not yet implemented. + Backends might implement additional features (by coincidence or not). These things are not supported through the API. When creating a slave zone, it is recommended to not set any of -``nameservers``, ``records``. - +``nameservers``, ``records`` or ``zone``.