Add rrl plugin (#238)

add rrl to external plugins

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>

content/explugins/rrl.md

@@ -0,0 +1,121 @@
++++
+ title = "rrl"
+ description = "*rrl* - mitigate amplification attacks with response rate limiting"
+ weight = 10
+ tags = [  "plugin" , "rrl" ]
+ categories = [ "plugin", "external" ]
+ date = "2021-10-07T00:00:00+00:00"
+ repo = "https://github.com/coredns/rrl"
+ home = "https://github.com/coredns/rrl/blob/master/README.md"
++++
+
+ ## Description
+
+The *rrl* plugin tracks response rates per category of response. 
+The category of a given response consists of the following:
+
+* Prefix of the client IP (per the ipv4/6-prefix-length)
+* Requested name (qname) excluding response type of error (see response type below)
+* Requested type (qtype) excluding response type of error (see response type below)
+* Response type (each corresponding to the configurable per-second allowances)
+  * response - for positive responses that contain answers
+  * nodata - for NODATA responses
+  * nxdomain - for NXDOMAIN responses
+  * referrals - for referrals or delegations
+  * error - for all DNS errors (except NXDOMAIN)
+
+
+To better protect against attacks using invalid requests, requested name
+and type are not categorized separately for error type requests. In other
+words, all error responses are limited collectively per client, regardless
+of qname or qtype.
+
+Each category has an account balance which is credited at a rate of the
+configured *per-second* allowance for that response type, and debited each
+time a response in that category would be sent to a client.  When an account
+balance is negative, responses in the category are dropped until the balance
+goes non-negative.  Account balances cannot be more positive than  *per-second*
+allowance, and cannot be more negative than *window* * *per-second* allowance.
+
+The response rate limiting implementation intends to replicate the behavior
+of BIND 9's response rate limiting feature.
+
+When limiting requests, the category of each request is determined by the
+prefix of the client IP (per the ipv4/6-prefix-length).
+
+ ## Syntax
+
+~~~txt
+rrl [ZONES...] {
+    window SECONDS
+    ipv4-prefix-length LENGTH
+    ipv6-prefix-length LENGTH
+    responses-per-second ALLOWANCE
+    nodata-per-second ALLOWANCE
+    nxdomains-per-second ALLOWANCE
+    referrals-per-second ALLOWANCE
+    errors-per-second ALLOWANCE
+    requests-per-second ALLOWANCE
+    max-table-size SIZE
+    report-only
+}
+~~~
+
+* `window SECONDS` - the rolling window in **SECONDS** during which response rates are tracked. Default 15.
+
+* `ipv4-prefix-length LENGTH` - the prefix **LENGTH** in bits to use for identifying a ipv4 client. Default 24.
+
+* `ipv6-prefix-length LENGTH` - the prefix **LENGTH** in bits to use for identifying a ipv6 client. Default 56.
+
+* `responses-per-second ALLOWANCE` - the number of positive responses allowed per second. An **ALLOWANCE** of 0 disables rate limiting of positive responses. Default 0.
+
+* `nodata-per-second ALLOWANCE` - the number of `NODATA` responses allowed per second. An **ALLOWANCE** of 0 disables rate limiting of NODATA responses. Defaults to responses-per-second.
+
+* `nxdomains-per-second ALLOWANCE` - the number of `NXDOMAIN` responses allowed per second. An **ALLOWANCE** of 0 disables rate limiting of NXDOMAIN responses. Defaults to responses-per-second.
+
+* `referrals-per-second ALLOWANCE` - the number of referral responses allowed per second. An **ALLOWANCE** of 0 disables rate limiting of referral responses. Defaults to responses-per-second.
+
+* `errors-per-second ALLOWANCE` - the number of error responses allowed per second (excluding NXDOMAIN). An **ALLOWANCE** of 0 disables rate limiting of error responses. Defaults to responses-per-second.
+
+* `requests-per-second ALLOWANCE` - the number of requests allowed per second. An **ALLOWANCE** of 0 disables rate limiting of requests. Default 0.
+
+* `max-table-size SIZE` - the maximum number of responses to be tracked at one time. When exceeded, rrl stops rate limiting new responses. Defaults to 100000.
+
+* `report-only` -  Do not drop requests/responses when rates are exceeded, only log metrics. Defaults to false.
+
+## Metrics
+
+If monitoring is enabled (via the *prometheus* plugin) then the following metric are exported:
+
+* `coredns_rrl_responses_exceeded_total{client_ip}` - Counter of responses exceeding QPS limit.
+* `coredns_rrl_requests_exceeded_total{client_ip}` - Counter of requests exceeding QPS limit.
+
+## Examples
+
+Example 1
+
+~~~ corefile
+
+. {
+  rrl . {
+    responses-per-second 10
+  }
+}
+
+~~~
+
+## Bugs / Known Issues / Limitations
+
+BIND9's implementation of Response Rate Limiting will rate limit all wildcard generated records in one account per the base domain of the wild card.  e.g. Both `a.dom.com.` and  `b.dom.com.` would be accounted for as `dom.com.`, if they are generated from the wildcard record `*.dom.com.`
+
+Per the BIND 9.11 ARM...
+
+> Responses generated from local wildcards are counted and limited as if they were for the parent domain name. 
+> This controls flooding using random.wild.example.com.
+
+In CoreDNS *rrl* wildcard responses are accounted for individually.
+
+## See Also
+
+[A Quick Introduction to Response Rate Limiting](https://kb.isc.org/docs/aa-01000)
+