mirror of
https://github.com/coredns/coredns.io.git
synced 2024-04-21 12:32:00 +00:00
Chris O'HaverandGitHub
d70d442a6a
add rrl to external plugins Signed-off-by: Chris O'Haver <cohaver@infoblox.com>
122 lines
5.0 KiB
Markdown
122 lines
5.0 KiB
Markdown
+++
|
|
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)
|
|
|