doc: acl behaviour description improved

doc/configuration.rst

@@ -88,32 +88,51 @@ Access control list (ACL)
 
 An ACL list specifies which remotes are allowed to send the server a specific
 request. A remote can be a single IP address or a network subnet. Also a TSIG
-key can be assigned (see :doc:`keymgr <man_keymgr>` how to generate a TSIG key)::
+key can be assigned (see :doc:`keymgr <man_keymgr>` how to generate a TSIG key).
 
-    key:
-      - id: key1
-        algorithm: hmac-md5
-        secret: Wg==
+With no ACL rule, all the actions are denied for the zone. Each ACL rule
+can allow one or more actions for given address/subnet/TSIG, or deny them.
+
+The rule precendence, if multiple rules match (e.g. overlapping address ranges),
+is not for stricter or more specific rules. In any case, just the first -- in the
+order of rules in zone or template acl configuration item, not in the order of
+declarations in acl section -- matching rule applies and the rest is ignored.
+
+See following examples and :ref:`ACL section`.::
 
     acl:
       - id: address_rule
-        address: [2001:db8::1, 192.168.2.0/24] # Allowed IP address list
-        action: [transfer, update]  # Allow zone transfers and updates
+        address: [2001:db8::1, 192.168.2.0/24]
+        action: transfer
 
-      - id: deny_rule             # Negative match rule
+      - id: deny_rule
         address: 192.168.2.100
         action: transfer
-        deny: on                  # The request is denied
+        deny: on
+
+    zone:
+      - domain: acl1.example.com.
+        acl: [deny_rule, address_rule] # deny_rule first here to take precendence
+
+::
+
+    key:
+      - id: key1
+        algorithm: hmac-md5
+        secret: Wg==
+
+    acl:
+      - id: deny_all
+        address: 192.168.3.0/24
+        deny: on # no action specified and deny on implies denial of all actions
 
       - id: key_rule
         key: key1                 # Access based just on TSIG key
-        action: transfer
-
-These rules can then be referenced from a zone :ref:`zone_acl`::
+        action: [transfer, notify]
 
     zone:
-      - domain: example.com
-        acl: [address_rule, deny_rule, key_rule]
+      - domain: acl2.example.com
+        acl: [deny_all, key_rule]
 
 Slave zone
 ==========

doc/man/knot.conf.5in

@@ -328,8 +328,7 @@ match one of them. Empty value means that TSIG key is not required.
 \fIDefault:\fP not set
 .SS action
 .sp
-An ordered list of allowed actions. Empty action list is only allowed if
-\fI\%deny\fP is set.
+An ordered list of allowed (or denied) actions.
 .sp
 Possible values:
 .INDENT 0.0
@@ -344,8 +343,9 @@ Possible values:
 \fIDefault:\fP not set
 .SS deny
 .sp
-Deny if \fI\%address\fP, \fI\%key\fP and
-\fI\%action\fP match.
+If enabled, instead of allowing, deny the specified \fI\%action\fP,
+\fI\%address\fP, \fI\%key\fP, or combination if these
+items. If no action is specified, deny all actions.
 .sp
 \fIDefault:\fP off
 .SH CONTROL SECTION

doc/reference.rst

@@ -373,8 +373,7 @@ match one of them. Empty value means that TSIG key is not required.
 action
 ------
 
-An ordered list of allowed actions. Empty action list is only allowed if
-:ref:`deny<acl_deny>` is set.
+An ordered list of allowed (or denied) actions.
 
 Possible values:
 
@@ -389,8 +388,9 @@ Possible values:
 deny
 ----
 
-Deny if :ref:`address<acl_address>`, :ref:`key<acl_key>` and
-:ref:`action<acl_action>` match.
+If enabled, instead of allowing, deny the specified :ref:`action<acl_action>`,
+:ref:`address<acl_address>`, :ref:`key<acl_key>`, or combination if these
+items. If no action is specified, deny all actions.
 
 *Default:* off