BIND 10 #2066: general description on ACL in bind10 guide

[BIND 10 Development]

#2066: general description on ACL in bind10 guide
-------------------------------------+-------------------------------------
                   Reporter:         |                 Owner:  jinmei
  jinmei                             |                Status:  reviewing
                       Type:         |             Milestone:
  defect                             |  Sprint-20120821
                   Priority:         |            Resolution:
  medium                             |             Sensitive:  0
                  Component:         |           Sub-Project:  Core
  documentation                      |  Estimated Difficulty:  4
                   Keywords:         |           Total Hours:  0
            Defect Severity:  N/A    |
Feature Depending on Ticket:         |
        Add Hours to Ticket:  0      |
                  Internal?:  0      |
-------------------------------------+-------------------------------------

Comment (by jinmei):

 - I have no opinion about the general organization.

 - I don't think we need a changelog for it (but if you think we do I
   don't oppose).

 - Personally, I'd like to see some formal definition of the ACL
   syntax like
 {{{
 acl = (rule(, rules...))
 rule = {"action": "ACCEPT"|"REJECT"|"DROP" [, match [, matches...]]}
 match = {"from": <ip_prefix> | "key": <tsig-keyname> | maybe-more-...}
 }}}

 - the general description is a bit confusing to me in that it
   partially seems to talk about the concept while using specific data
   structure (i.e., JSON).  When we talk about the concept, it'd be
   more understandable to me if we use more commonly used conceptual
   terms like "a list" (although it's also used in the context of JSON)
   or "key value mapping", etc.  So, for example, the following general
   description would be more understandable to me:
   - an ACL is a list of rules
   - a rule is a set of key-value mappings
   - the set in a rule must always have exactly one special mapping
     called "action"
   - the set in a rule may have other mappings; they are called
     "matches".
   - (and explain how these apply in request processing)

 - As noted in a commented-out "TODO", I think we need some description
   of keyring and a reference to it.

 - I suspect the example shown in 8.1.4 generally doesn't work.  See my
   comment about the removed note from the DDNS section below.

 - I found one typo in the example in 8.1.3.

 - the above two points seem to suggest you might not actually try to
   configure these the server using these examples.  Personally, I
   generally try to confirm example config snippet actually works by
   cut-and-past'ing it to bindctl - in fact, I often find errors in the
   example that way.  If you didn't do that, I suggest you do it at
   least once.

 - "tsig key" is DNS specific, while we probably want to describe the
   ACLs as a general framework.  I'd like to clarify this point
   somehow (like 'in practice "key" is meaningful only when used in a
   DNS-related application)

 - This sentence doesn't parse for me:
 {{{#!diff
 +      You can configure it the same as any ACL
 }}}
 - I think this note should be kept somewhere:
 {{{#!diff
 -      (Note the "add" in the first line.  Before this sequence, we
 -      have had only entry in <varname>zones[0]/update_acl</varname>.
 -      The <command>add</command> command with a value (rule) adds
 -      a new entry and sets it to the given rule.
 -
 -      Due to a limitation of the current implementation, it doesn't
 -      work if you first try to just add a new entry and then set it to
 -      a given rule.)
 }}}
   (although "we have had only entry" doesn't make sense to me...maybe
   the intent was "we have had no entry").
 - I'd keep at least one simple example of an ACL for the recursive server.

-- 
Ticket URL: <https://bind10.isc.org/ticket/2066#comment:6>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development