From 72e6f22cdfdfc452aef1ea628ad7dfba749e6497 Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Fri, 12 Feb 2021 15:04:52 +0100 Subject: [PATCH] Add autohints docs --- .github/actions/spell-check/allow.txt | 1 + docs/guides/index.rst | 1 + docs/guides/svcb.rst | 77 +++++++++++++++++++++++++++ 3 files changed, 79 insertions(+) create mode 100644 docs/guides/svcb.rst diff --git a/.github/actions/spell-check/allow.txt b/.github/actions/spell-check/allow.txt index 8a7947bf54..6d424f5857 100644 --- 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 78ca691673..3b6ded0ad5 100644 --- 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 index 0000000000..1daa1cf552 --- /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. -- 2.47.2