Add autohints docs

diff --git a/.github/actions/spell-check/allow.txt b/.github/actions/spell-check/allow.txt
index 8a7947bf5455d9413d1718b5bf8ce5c4975e8515..6d424f5857c1f6e08ce317a495556ce27fcef527 100644 (file)
--- a/.github/actions/spell-check/allow.txt
+++ b/.github/actions/spell-check/allow.txt
@@ -129,6 +129,7 @@ apowerdnscom
 appliedpolicy
 appliedpolicytype
 appname
+autohints
 APTR
 APublic
 AQEX

diff --git a/docs/guides/index.rst b/docs/guides/index.rst
index 78ca691673b236aa60eb985b87973cfc469b0542..3b6ded0ad5269ac8b76798a20c7093f01c8ded12 100644 (file)
--- a/docs/guides/index.rst
+++ b/docs/guides/index.rst
@@ -8,6 +8,7 @@ Guides and How Tos
   recursion
   virtual-instances
   alias
+  svcb
   kskroll
   kskrollcdnskey
   zskroll

diff --git a/docs/guides/svcb.rst b/docs/guides/svcb.rst
new file mode 100644 (file)
index 0000000..1daa1cf
--- /dev/null
+++ b/docs/guides/svcb.rst
@@ -0,0 +1,77 @@
+Using SVCB and derived records
+==============================
+The PowerDNS Authoritative Server has support for the SVCB record and derived records (like HTTPS).
+This support includes doing the standards recommended following of alias-form records in-zone and adding those to the additional section.
+Apart from that, there's the PowerDNS special for "autohints".
+
+Automatic hints
+---------------
+PowerDNS can automatically fill in ``ipv4hint`` and ``ipv6hint`` parameters in SVCB records based on A and AAAA records already present in the zone.
+Consider the following zone content::
+
+  example.com      IN HTTPS 0 www.example.com
+
+  www.example.com  IN HTTPS 1 . ipv4hint=auto
+  www.example.com  IN A     192.0.2.1
+  www.example.com  IN AAAA  2001:db8::1
+
+  ipv6.example.com IN HTTPS 1 . ipv6hint=auto
+  ipv6.example.com IN AAAA  2001:db8::2
+  ipv6.example.com IN AAAA  2001:db8::3
+
+A query for ``example.org|HTTPS`` will be responded to like this::
+
+  ;; QUESTION SECTION:
+  ;example.org.                        IN      HTTPS
+
+  ;; ANSWER SECTION:
+  example.org.         3600    IN      HTTPS   0 www.example.com
+
+  ;; ADDITIONAL SECTION:
+  www.example.org.     3600    IN      A       192.0.2.1
+  www.example.org.     3600    IN      HTTPS   1 . ipv4hint=192.0.2.1
+  www.example.org.     3600    IN      AAAA    2001:db8::1
+
+Notice that PowerDNS did additional processing and added the target HTTPS record, and the address records to the additional section.
+Also notice that the ipv4hint in the ``www.example.org|HTTPS`` records is set to the value of the A record.
+
+PowerDNS takes all the corresponding address records, e.g. when asking for ipv6.example.com::
+
+  ;; QUESTION SECTION:
+  ;ipv6.example.org.           IN      HTTPS
+
+  ;; ANSWER SECTION:
+  ipv6.example.org.    3600    IN      HTTPS   1 . ipv6hint=2001:db8::2,2001:db8::3
+
+  ;; ADDITIONAL SECTION:
+  ipv6.example.org.    3600    IN      AAAA    2001:db8::2
+  ipv6.example.org.    3600    IN      AAAA    2001:db8::3
+
+When autohints are applied
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+PowerDNS expands the autohints both when answering a query, as well as when serving an AXFR.
+The text "auto" is **never** served over the wire, ensuring compatibility with any and all client software.
+
+When no address records exist
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Consider the following zone content::
+
+  no-ipv6.example.com  IN HTTPS 1 . ipv4hint=auto ipv6hint=auto
+  no-ipv6.example.com  IN A     192.0.2.2
+
+Here, no AAAA record exists for www.example.com, so PowerDNS can not put any data in the ipv6hint.
+In this case, the ipv6hint parameter is dropped when answering the query (and on AXFR)::
+
+  ;; QUESTION SECTION:
+  ;no-ipv6.example.org.                IN      HTTPS
+
+  ;; ANSWER SECTION:
+  no-ipv6.example.org. 3600    IN      HTTPS   1 . ipv4hint=192.0.2.2
+
+  ;; ADDITIONAL SECTION:
+  no-ipv6.example.org. 3600    IN      A       192.0.2.2
+
+:doc:`pdnsutil <../manpages/pdnsutil.1>` checks if the autohints in SVCB and derived records can be found in the zone when using ``pdnsutil check-zone``.
+It will emit a warning when there are no hints to be found::
+
+  [warning] HTTPS record for no-ipv6.example.org has automatic IPv6 hints, but no AAAA-record for the target at no-ipv6.example.org exists.