BIND 10 #2005: DDNS documentation

[BIND 10 Development]

#2005: DDNS documentation
-------------------------------------+-------------------------------------
                   Reporter:         |                 Owner:  jinmei
  jinmei                             |                Status:  reviewing
                       Type:  task   |             Milestone:
                   Priority:  very   |  Sprint-20120619
  high                               |            Resolution:
                  Component:  DDNS   |             Sensitive:  0
                   Keywords:         |           Sub-Project:  DNS
            Defect Severity:  N/A    |  Estimated Difficulty:  6
Feature Depending on Ticket:  DDNS   |           Total Hours:  0
        Add Hours to Ticket:  0      |
                  Internal?:  0      |
-------------------------------------+-------------------------------------

Comment (by jinmei):

 Replying to [comment:8 jreed]:
 > I have a few comments and questions.

 Thanks for the careful read and detailed feedback.  I've tried to
 address as much of it as possible and pushed the revised version.
 If you can check it and give it an explicit okay, that would be great.
 Even if you don't have time or are not fully satisfied, I'd propose
 merging the branch at this point.  I believe it's still much better
 than nothing for the release.  In the case you still have open points
 we can either keep this ticket open or create a new one for the
 remaining issues.

 > {{{
 >       When the processing is completed <command>b10-ddns</command>
 >       will send a response to the client with the processing result.
 > }}}
 > What does "processing result" mean?  (In guide and manpage.)

 I tried to clarify this.

 > {{{
 >       If the zone has been changed as a result, it will internally
 >       notify <command>b10-auth</command> and
 >       <command>b10-xfrout</command> so the new version of the zone will
 >       be served
 > }}}
 > Does that mean there is two different zone databases and it tells auth
 to use the new one?

 I tried to clarify this.

 > For consistent style: some uses of term "process" maybe should be
 "component" instead.

 Yeah I know there was some mixed usage.  The slight difference between
 these two terms keeps confusing me, resulting in such inconsistencies.
 Anyway, I tried to unify them wherever seemingly possible.  The one
 exception is the bind10 "process".  I was not sure if it's called a
 component, so I left it as "process".

 > {{{
 >  Clients cannot reuse the
 >       same TCP connection for multiple requests.
 > }}}
 > Is this a limitation or bug in BIND 10? Or is this per the
 specification?

 The former.  Clarified it.

 > Is there a ticket about update forwarding? If so, maybe put it as a
 comment in the part about that. Maybe make that paragraph a <note> too.

 Created a ticket and commented it.

 > {{{
 >         In addition, <command>b10-xfrout</command> should also be
 >         configured to run; otherwise the notification after an update
 >         (see above) will fail with a timeout, suspending the DDNS
 >         service while <command>b10-ddns</command> waits for the
 response.
 > }}}
 > Is this a bug? Any ticket? What if admin forgets to configure this? Is
 there any warning or error in the logging? How long is it suspended?
 (forever until BIND 10 is restarted?)

 I'd call it a bug.  No specific ticket, but would be part of the
 config-ng work (supporting asynchrony, e.g.).  Updated the doc and
 related log message to clarify this.

 > What ticket number for "The way to configure data sources is now being
 revised." ?

 No specific one, it will be a part of larger feature change.

 > What happens if b10-ddns component is configured and started but
 dependencies aren't enabled? Any warning logged? (Or just doesn't do
 anything?)

 Tried to clarify that.

 > {{{
 > > <userinput>config set Boss/components/b10-ddns/address
 DDNS</userinput>
 > }}}
 >
 > I don't understand "address" well. Why doesn't it know the address is
 DDNS? It seems obvious.
 > ("The address is by convention the thing after b10-, with the first
 letter capital")  So maybe change code to be "Ddns" or allow it to be
 case-insensitive and then remove the obvious configuration?

 I tried to clarify that.  It's the module/component name in its spec,
 so currently should be "DDNS".  If we want to change that, it will be
 a matter of other task (the doc is describing what it is/does right
 now correctly).

 > {{{
 > > <userinput>config set Boss/components/b10-ddns/kind
 dispensable</userinput>
 > }}}
 > That is the default so doesn't need to be documented.

 Unfortunately not.  Clarified it, and opened a ticket.

 > {{{
 >         To allow updates to take effect, an access control rule
 >         (called update ACL) with that policy must explicitly be
 >         configured.
 > }}}
 > What is "that policy"?

 Clarified.

 > {{{
 >             <term>class</term>
 >             <listitem>
 >               <simpara>The RR class of the zone
 >                 (normally <quote>IN</quote>)</simpara>
 >             </listitem>
 > }}}
 > Any default class IN for this? Or does it always have to be defined?
 > Now I see later: "(The <quote>class</quote> can be omitted)." so maybe
 move that sentence earlier and really do omit it and just mention it using
 default class.

 I tried to clarify that.

 > Any plans for specific fine-grained policies like BIND 9 provides? (Now
 I see it mentioned later in the guide.) Any ticket(s) for this?

 Opened a ticket.

 > Do index numbers like zero in "DDNS/zones[0]/origin" match up with index
 numbers used by other components? (I don't think so and this is probably
 not related to this ticket.)

 No, and I don't think we need to note that explicitly here.

 > {{{
 >         The following configuration sequence will add to the previous
 >         ACL a rule that allows update requests sent from a client
 >         using TSIG key name of "key.example" and has an IPv6 address of
 ::1.
 >       <screen>
 > > <userinput>config add DDNS/zones[0]/update_acl {"action": "ACCEPT",
 "from": "::1", "key": "key.example"}</userinput>
 > }}}
 > That seems strange to "add to the previous". Maybe use "set" to set the
 "from"? (I need to test to verify.)  (Ignore the fact that zero becomes
 one -- that seems like a bug.)
 > Why have two rules now?  Now I see they are different -- maybe clearly
 say "using a different TSIG key name"?

 I've updated the doc so it's more readable and clarify some subtle
 points.  Hopefully it's more understandable now.

 > Also maybe the documentation should not show examples of adding entire
 JSON objects, but should add and then set each item individually to be
 clear.

 I'm not sure if I understand this, but if I understand what "add and
 then set" means, it doesn't work right now, and I clarified that.

 > I assume this rule processing stops on first match and continues through
 entire list only if no matches. Maybe document about this in the guide?

 I think it should go to a separate generic ACL chapter, but without
 having it right now, documented it.  Created a ticket for it.

 > Is there any purpose to have an "action": "REJECT" rule?
 >
 > Any example of when to use a "DROP" rule? (Does "DROP" work?)

 I don't think we need an example for these, but I mentioned them.

 > Any way to restrict updates to TCP only?

 No.

 > {{{
 >         One known specific bad result of this is that it could leak
 >         information about which name or record exists or does not
 > ...
 > }}}
 > What is "this"? Is this using the RFC specification way? Or using the
 BIND 10 way?

 Clarified that (it's RFC).

 > {{{
 >         or make sure the update request also updates related DNSSEC
 >         records, but that will be pretty error-prone operation.
 > }}}
 > Why error-prone?  It seems like I have heard of non-BIND9 DNSSEC
 maintenance tools that do use DDNS.

 I thought it's obvious - first, if the updated DNSSEC records are
 populated manually that should be clearly error prone (do we agree
 here?).  If it's from some automated tools, maybe it can work if
 that's the only possible updater, but in the general case it's still
 unreliable because unless you know the exact state of
 before-and-after-update zone (including which name is the next to a
 newly added one) you cannot pre-compute SIGs and NSECs with 100%
 accuracy.

 But I didn't go into this level of details in the guide.

 > {{{
 >         If you need to make manual updates to a dynamic zone,
 >         you'll need to temporarily reject any updates to the zone via
 >         the update ACLs.
 > }}}
 > Why?  Will something fail if you manually update the SQLite3 database
 directly? I understand it may
 > be changed soon after but that would be same as thawing anyway.

 e.g. you may first want to "select" and based on the result change the
 zone.  It won't work if an update is coming between two operations.
 You could do everything in a single transaction, though.  Also, maybe
 we need to fully rethink about how to manually update a dynamic zone
 in BIND 10.  Because it's DB-based there may be other issues or
 advantages.

 Anyway, I didn't go into this detail in the doc.  In any event it's
 not advisable to modify the zone manually if it accepts DDNS.

 > {{{
 >           Zones listed in
 >         <quote>secondary_zones</quote> will never be updated via DDNS
 >         regardless of the update ACL configuration.
 > }}}
 > What will b10-ddns (or b10-auth?) respond to client with? REFUSED?
 NOTIMP? Other?

 Clarified.

 > Update date stamp in man page. Also update the HISTORY to mention when
 it first works. Man page can mention default IN class.
 >
 > I am not sure how to word it, but maybe man page should mention there
 may be multiple update_acl lists.

 Done for history and date.  I didn't touch others - I don't like to
 repeat the same things in multiple places in general, and it makes
 more sense to me the man page basically just refers to guide beyond
 some very basic introductory text.

-- 
Ticket URL: <http://bind10.isc.org/ticket/2005#comment:9>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development