From: Evan Hunt Date: Thu, 30 Jan 2014 23:09:33 +0000 (-0800) Subject: [master] improve RRL documentation X-Git-Tag: v9.10.0a2~21 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fe9a1e5bd6bbd59127601a1e57593fa5c6228b4a;p=thirdparty%2Fbind9.git [master] improve RRL documentation - wrote better qname classifer doc - imported response size classifier doc from 9.9 sub --- diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml index 0353ddf3aca..79dcf1b4c9a 100644 --- a/doc/arm/Bv9ARM-book.xml +++ b/doc/arm/Bv9ARM-book.xml @@ -4937,7 +4937,8 @@ badresp:1,adberr:0,findfail:0,valfail:0] deny-answer-addresses { address_match_list } except-from { namelist } ; deny-answer-aliases { namelist } except-from { namelist } ; rate-limit { - responses-per-second number ; + domain domain ; + responses-per-second size number ratio fixedpoint number ; referrals-per-second number ; nodata-per-second number ; nxdomains-per-second number ; @@ -9837,18 +9838,20 @@ example.com CNAME rpz-tcp-only. All non-empty responses for a valid domain name (qname) and record type (qtype) are identical and have a limit specified - with responses-per-second - (default 0 or no limit). + by the base responses-per-second option + (that is, responses-per-second with only a + single argument and no additional modifiers). + The default is 0, which indicates that there should be no limit. All empty (NODATA) responses for a valid domain, regardless of query type, are identical. Responses in the NODATA class are limited by nodata-per-second - (default responses-per-second). + (default base responses-per-second). Requests for any and all undefined subdomains of a given valid domain result in NXDOMAIN errors, and are identical regardless of query type. They are limited by nxdomain-per-second - (default responses-per-second). + (default base responses-per-second). This controls some attacks using random names, but can be relaxed or turned off (set to 0) on servers that expect many legitimate @@ -9856,7 +9859,7 @@ example.com CNAME rpz-tcp-only. Referrals or delegations to the server of a given domain are identical and are limited by referrals-per-second - (default responses-per-second). + (default base responses-per-second). @@ -9872,11 +9875,76 @@ example.com CNAME rpz-tcp-only. This controls attacks using invalid requests or distant, broken authoritative servers. By default the limit on errors is the same as the - responses-per-second value, + default base responses-per-second value, but it can be set separately with errors-per-second. + + In addition to the base + responses-per-second value, + up to four (4) additional + responses-per-second options can be + configured, with additional parameters to indicate that + they apply to responses larger than a given size, + or with an amplification factor larger than a given + value. + The size parameter sets the minimum + DNS response size that will trigger the use of this + responses-per-second option. + The ratio parameter sets the minimum + DNS response-size / request-size ratio that falls into the + band, to two decimal places. + These selective rate limits are applied after any other + rate limits have been applied, and they only apply to + positive answers. For example: + + +rate-limit { + responses-per-second 10; + responses-per-second size 1100 5; +}; + + + ...indicates that responses should be limited to ten per second + for responses up to 1099 bytes in size, but only five per second + for responses larger than that. This configuration: + + +rate-limit { + responses-per-second 10; + responses-per-second ratio 7.25 5; + responses-per-second ratio 15.00 2; +}; + + + ...indicates that responses should be limited to ten per + second if the amplification factor is below 7.25, five per + second if above 7.25 but below 15, and two per second if + above 15. + + + Both sizes and ratios can be used together. For example: + + +rate-limit { + responses-per-second 10; + responses-per-second size 1000 ratio 5.00 5; + responses-per-second ratio 10.00 2; +}; + + + This configuration will rate-limit to five per second if + the ratio is over 5 or the size is over + 1000, and to two per second if the ratio is over 10. In the + event that two bands might be chosen (i.e., because the size + is over 1000 and the ratio is over 10), + the one that appears last in the configuration file is the + one chosen. To eliminate any ambiguity, it is recommended + that under normal circumstnaces, rate limiting bands should + be configured using either size or + ratio parameters, but not both. + Many attacks using DNS involve UDP requests with forged source addresses. @@ -9935,6 +10003,33 @@ example.com CNAME rpz-tcp-only. but are counted to compute the query per second rate. + + The optional domain clause specifies + the namespace to which rate limits will apply. It + is possible to use different rate limits for different names + by specifying multiple rate-limit blocks + with different domain clauses. + The rate-limit statement's + domain most closely matches the query + name will be the one applied to a given query. + + + + Rate limiters for different name spaces maintain + separate counters: If, for example, there is a + rate-limit statement for "com" and + another for "example.com", queries matching "example.com" + will not be debited against the rate limiter for "com". + + + + If a rate-limit statement does not specify a + domain, then it applies to the root domain + (".") and thus affects the entire DNS namespace, except those + portions covered by other rate-limit + statements. + + Communities of DNS clients can be given their own parameters or no rate limiting by putting @@ -9950,39 +10045,36 @@ example.com CNAME rpz-tcp-only. UDP responses of all kinds can be limited with the - all-per-second phrase. - This rate limiting is unlike the rate limiting provided by + all-per-second phrase. This rate + limiting is unlike the rate limiting provided by responses-per-second, errors-per-second, and nxdomains-per-second on a DNS server - which are often invisible to the victim of a DNS reflection attack. - Unless the forged requests of the attack are the same as the - legitimate requests of the victim, the victim's requests are - not affected. - Responses affected by an all-per-second limit - are always dropped; the slip value has no - effect. - An all-per-second limit should be - at least 4 times as large as the other limits, - because single DNS clients often send bursts of legitimate - requests. - For example, the receipt of a single mail message can prompt - requests from an SMTP server for NS, PTR, A, and AAAA records - as the incoming SMTP/TCP/IP connection is considered. - The SMTP server can need additional NS, A, AAAA, MX, TXT, and SPF - records as it considers the STMP Mail From - command. - Web browsers often repeatedly resolve the same names that - are repeated in HTML <IMG> tags in a page. - All-per-second is similar to the - rate limiting offered by firewalls but often inferior. - Attacks that justify ignoring the - contents of DNS responses are likely to be attacks on the - DNS server itself. - They usually should be discarded before the DNS server - spends resources making TCP connections or parsing DNS requests, - but that rate limiting must be done before the - DNS server sees the requests. + which are often invisible to the victim of a DNS + reflection attack. Unless the forged requests of the + attack are the same as the legitimate requests of the + victim, the victim's requests are not affected. Responses + affected by an all-per-second limit + are always dropped; the slip value + has no effect. An all-per-second + limit should be at least 4 times as large as the other + limits, because single DNS clients often send bursts + of legitimate requests. For example, the receipt of a + single mail message can prompt requests from an SMTP + server for NS, PTR, A, and AAAA records as the incoming + SMTP/TCP/IP connection is considered. The SMTP server + can need additional NS, A, AAAA, MX, TXT, and SPF records + as it considers the STMP Mail From + command. Web browsers often repeatedly resolve the + same names that are repeated in HTML <IMG> tags + in a page. All-per-second is similar + to the rate limiting offered by firewalls but often + inferior. Attacks that justify ignoring the contents + of DNS responses are likely to be attacks on the DNS + server itself. They usually should be discarded before + the DNS server spends resources make TCP connections + or parsing DNS requests, but that rate limiting must + be done before the DNS server sees the requests.