Improvements to the parental-agents definition in the arm

Hi and thanks for filing an issue! It will be read with care by human beings.

It would be a tremendous help if you could follow these steps first:

• Search the existing issues in GitLab (both open and closed) to see if your report might be a duplicate. We have a large database here and many issues have already been fixed in the latest versions!
• Make sure this is not a support question. If you have specific trouble configuring or debugging your setup, please use the bind-users mailing list: https://lists.isc.org/mailman/listinfo/bind-users
• You have read and understood the "out in the open" support policy: https://blog.powerdns.com/2016/01/18/open-source-support-out-in-the-open/ . Even though it was written by the PowerDNS folks, we follow it as well!

Before continuing, please select the appropriate issue template in the drop-down menu above, under the heading Description.

(There is no "doc" template. Maybe there should be.)

The current doc for parental-agents laid out in the 9.18 arm is, some formatting tweaks for gitlab aside:

Grammar zone (primary, secondary): parental-agents [ port <integer> ] { ( <remote-servers> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <string> ] [ tls <string> ]; ... };

Grammar topmost: parental-agents <string> [ port <integer> ] { ( <remote-servers> | <ipv4_address> [ port <integer> ] | <ipv6_address> [ port <integer> ] ) [ key <string> ] [ tls <string> ]; ... }; // may occur multiple times

Blocks: topmost, zone (primary, secondary)

Tags: zone

Defines a list of delegation agents to be used by primary and secondary zones.

8.2.10. parental-agents Block Definition and Usage

parental-agents lists allow for a common set of parental agents to be easily used by multiple primary and secondary zones. A parental agent is the entity that is allowed to change a zone’s delegation information (defined in RFC 7344).

What is not apparent from the above:

• If you define a "topmost" parental agent, you must still define it in a zone for it to be used. There is no way to configure a default parental agent, nor to have it apply to zones without stating it for each. The example cited in the 9.18 migration article in the KB only mentions the pure-zone-based version, and doesn't give a good example of how to do it with a globally-defined one.

• The "usage" statement for the zone does not make it apparent how to specify an agent defined topmost -- this implies either two "zone" usage statements (Grammar zone with no defined topmost agent, grammar zone with the agent defined only in the zone statement), or a more complex definition of the "Grammar Zone" statement where it's either "parental-agents { "string"; } followed by the rest of the possible options. (I guess it's possible to use a topmost-defined parental agent but ALSO add others? -- I'm not sure how to properly bracket those options, depending on if that's the case.)

• "A parental agent is the entity that is allowed to change a zone's delegation information" is untrue in this case. While that is one possible usage (for example, specifying "a0.org.afilias-nst.info." for an agent for example.org), The a0.org.afilias-nst.info. is not allowed to change the delegation information -- some hidden SRS server and a stealth master are, as part of the DNSSEC process. A parental-agent may also be set to 8.8.8.8 or any other TSIG-relationship-defined validating resolver, none of which are allowed to change anything about the delegation.

• Also, the "allowed to change" wording implies that there is some nsupdate-like relationship required between our zone and it, that's to be configured, especially because things like TSIG keys are offered as options.

• It isn't immediately clear that the only thing BIND does is send DS queries.

A better phrasing here might be:

"A parental agent is a trusted DNS server that can confirm that a zone's delegation information has been updated in the parent zone of the one being configured, as defined in (rfc foo section bar). [An optional statement about what is implied by "trusted" (TSIG/DNSSEC/ACLs on the parental-agent server) could go here.]"