diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 97437c8d12..772bd82c43 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -1316,27 +1316,48 @@ TODO An ACL, or Access Control List, is a way to describe if a request is allowed or disallowed. The principle is, there's a list of rules. - A request either matches the rule or it doesn't. If it matches, - a decision is made and no more ACL processing happens. If it does - not match, the processing moves to the next rule. If there are - no more rules, a default action is taken. + Each rule is a name-value mapping (a dictionary, in the JSON + terminology). Each rule must contain exactly one mapping called + "action", which describes what should happen if the rule applies. + There may be more mappings, calld matches, which describe the + conditions under which the rule applies. - Each element in the ACL is a dictionary. There's exactly one - action element. This element describes the - decision taken when the rule matches. If it is set to - "ACCEPT", the request processed. In case of "REJECT", the request - is not processed and an error message is sent back (what it means - depends on which ACL it is). The action of "DROP" does not - process the request and sends no answer — pretending the - request never came (which means the sender might resend it). + When there's a query, the first rule is examined. If it matches, the + action in it is taken. If not, next rule is examined. If there are no + more rules to examine, a default action is taken. - Other elements inside the rule describe the properties a request - must have to match. The request must match all the properties - in the check. + There are three possible "action" values. The "ACCEPT" value means + the query is handled. If it is "REJECT", the query is not answered, + but a polite error message is sent back (if that makes sense in the + context). The "DROP" action acts like a black hole. The query is + not answered and no error message is sent. + + + + If there are multiple matching conditions inside the rule, all of + them must be satisfied for the rule to apply. This can be used, + for example, to require the query to be signed by a TSIG key and + originate from given address. + + + + This is encoded in form of JSON. Semi-formal description could look + something like this. It is described in more details below. + + ACL := [ RULE, RULE, ... ] +RULE := { "action": "ACCEPT"|"REJECT"|"DROP", MATCH, MATCH, ... } +RULE_RAW := { MATCH, MATCH, ... } +MATCH := FROM_MATCH|KEY_MATCH|NOT_MATCH|OR_MATCH|AND_MATCH|... +FROM_MATCH := "from": "<ip range> +KEY_MATCH := "key": "<key name> +NOT_MATCH := "NOT": RULE_RAW +OR_MATCH := "ANY": [ RULE_RAW, RULE_RAW, ... ] +AND_MATCH := "ALL": [ RULE_RAW, RULE_RAW, ... ] +