Opened 7 years ago

Closed 7 years ago

#2005 closed task (complete)

DDNS documentation

Reported by: jinmei Owned by: jinmei
Priority: very high Milestone: Sprint-20120619
Component: ddns Version:
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DNS Feature Depending on Ticket: DDNS
Estimated Difficulty: 6 Add Hours to Ticket: 0
Total Hours: 8 Internal?: no

Description

man page and guide.

Subtickets

Change History (15)

comment:1 Changed 7 years ago by jelte

  • Milestone changed from Next-Sprint-Proposed to Sprint-20120612

comment:2 Changed 7 years ago by jelte

  • Priority changed from medium to very high

comment:3 Changed 7 years ago by jinmei

  • Owner set to jinmei
  • Status changed from new to accepted

comment:4 Changed 7 years ago by jinmei

  • Owner changed from jinmei to UnAssigned
  • Status changed from accepted to reviewing

trac2005 is ready for review.

I've only committed and pushed xml source to reduce the amount of
diff. For review, it would be easier to generate an html and nroff
versions from XML.

For the guide, I made a small unrelated changes at fb03a64
but the main changes are the completely new chapter, Chapter 11.
So basically only that chapter (and all of it) should be reviewed.

I basically suggest we merge it as soon as possible, just correcting
obvious errors and adding critical missing information as polishing
documentation is a never ending process.

I also suggest adding a meta changelog entry for the entire DDNS
support:

446.	[func]		team
	b10-ddns is now functional and handles dynamic update requests
	per RFC 2136.  See BIND 10 guide for configuration and operation
	details.

comment:5 Changed 7 years ago by jelte

  • Owner changed from UnAssigned to jelte

comment:6 follow-up: Changed 7 years ago by jelte

  • Owner changed from jelte to jinmei

Overall, it looks good. A few comments:

In 'Enabling Dynamic Update' (around line 1950), I'd probably add a note that b10-xfrout is essentially required to run as well. If it is not running, b10-ddns will be in a coma for 4 seconds after each update (waiting for xfrout to not respond) (the note can include that we plan to change this in some way in the future).

Around line 2074, the note about how update_acl must be set completely in one go is not entirely right; you can't add entries without value, but you can add entries one at a time if you specify the entry;

> config add DDNS/zones[0]/update_acl
Error: No value given and no default for /DDNS/zones[0]/update_acl
> config add DDNS/zones[0]/update_acl { "action": "ACCEPT", "key": "key.example.org", "from": "192.168.8.8" }
> config add DDNS/zones[0]/update_acl { "action": "REJECT", "key": "key.example.org", "from": "192.168.9.9" }
> config commit
>

Line 2160: "There has to be no configuration to make this possible.", I'd rephrase that as "This is done automaticallyl; it does not require specific configuration to make this possible" (except of course that IXFR itself needs to be enabled). The current text implies that you have to explicitely not configure something.

And about the manpage; not sure if we mention it for the other daemons, but -h is also a valid argument :)

Assuming that there is not too much discussion on the above, I won't be able to look at it again, so you may merge after looking at these comments :)
(otherwise you'll have to request someone else to take a look)

comment:7 in reply to: ↑ 6 Changed 7 years ago by jinmei

Replying to jelte:

Thanks for the prompt review.

Overall, it looks good. A few comments:

In 'Enabling Dynamic Update' (around line 1950), I'd probably add a note that b10-xfrout is essentially required to run as well. If it is not running, b10-ddns will be in a coma for 4 seconds after each update (waiting for xfrout to not respond) (the note can include that we plan to change this in some way in the future).

Ah, good point. Added.

Around line 2074, the note about how update_acl must be set completely in one go is not entirely right; you can't add entries without value, but you can add entries one at a time if you specify the entry;

Hmm, I didn't know that:-) In that case examples using 'add' are
definitely better. Revised that way.

Line 2160: "There has to be no configuration to make this possible.", I'd rephrase that as "This is done automaticallyl; it does not require specific configuration to make this possible" (except of course that IXFR itself needs to be enabled). The current text implies that you have to explicitely not configure something.

Okay, changed.

And about the manpage; not sure if we mention it for the other daemons, but -h is also a valid argument :)

Okay, added.

Assuming that there is not too much discussion on the above, I won't be able to look at it again, so you may merge after looking at these comments :)
(otherwise you'll have to request someone else to take a look)

If you are still working and can check the latest version, that would
be good; otherwise, just enjoy your vacation:-)

comment:8 follow-up: Changed 7 years ago by jreed

I have a few comments and questions.

      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.)

      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?

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

 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?

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.

        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?)

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

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

&gt; <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?

&gt; <userinput>config set Boss/components/b10-ddns/kind dispensable</userinput>

That is the default so doesn't need to be documented.

        To allow updates to take effect, an access control rule
        (called update ACL) with that policy must explicitly be
        configured.

What is "that policy"?

            <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.

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?

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.)

        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>
&gt; <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"?

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 assume this rule processing stops on first match and continues through entire list only if no matches. Maybe document about this in the guide?

Is there any purpose to have an "action": "REJECT" rule?

Any example of when to use a "DROP" rule? (Does "DROP" work?)

Any way to restrict updates to TCP only?

        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?

        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.

        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.

          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?

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.

Those are my comments before using it :)

comment:9 in reply to: ↑ 8 Changed 7 years ago by jinmei

Replying to 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.

&gt; <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).

&gt; <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>
&gt; <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.

comment:10 Changed 7 years ago by jinmei

  • Owner changed from jinmei to jreed

comment:11 Changed 7 years ago by jinmei

  • Total Hours changed from 0 to 2.5

comment:12 Changed 7 years ago by jinmei

  • Total Hours changed from 2.5 to 0

comment:13 follow-up: Changed 7 years ago by jreed

  • Owner changed from jreed to jinmei

I just pushed some very minor changes.

Thanks for the many clarifications.

Please merge this. (Note I think there may be a git merge conflict as I saw a place that had a change done later in master.) Thanks.

comment:14 in reply to: ↑ 13 Changed 7 years ago by jinmei

Replying to jreed:

I just pushed some very minor changes.

Thanks for the many clarifications.

Please merge this. (Note I think there may be a git merge conflict as I saw a place that had a change done later in master.) Thanks.

Thanks, merge done. I'm closing this ticket for now.

If you have remaining open issues please open a new ticket.

comment:15 Changed 7 years ago by jinmei

  • Resolution set to complete
  • Status changed from reviewing to closed
  • Total Hours changed from 0 to 8
Note: See TracTickets for help on using tickets.