diff --git a/Configuration.md b/Configuration.md index 715b42a..1a3102f 100644 --- a/Configuration.md +++ b/Configuration.md @@ -173,7 +173,7 @@ Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possib - **Protection settings** - `protection_enabled` — Whether any kind of filtering and protection should be done, when off it works as a plain dns forwarder. - `filtering_enabled` — Filtering of DNS requests based on filter lists. - - `blocking_mode` — Specifies how to block DNS requests. "nxdomain" (default): respond with NXDOMAIN status; "null_ip": respond with the unspecified IP address (0.0.0.0); or "custom_ip": reponsd with `blocking_ipv4` or `blocking_ipv6`. + - `blocking_mode` — Specifies how to block DNS requests. "nxdomain" (default): respond with NXDOMAIN status; "null_ip": respond with the unspecified IP address (0.0.0.0); or "custom_ip": respond with `blocking_ipv4` or `blocking_ipv6`. - `blocking_ipv4` - IP address to be returned for a blocked A request if `blocking_mode` is set to `custom_ip` - `blocking_ipv6` - IP address to be returned for a blocked AAAA request if `blocking_mode` is set to `custom_ip` - `blocked_response_ttl` — For how many seconds the clients should cache a filtered response. Low values are useful on LAN if you change filters very often, high values are useful to increase performance and save traffic. diff --git a/Getting-Started.md b/Getting-Started.md index 5b72d90..d631ff4 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -18,7 +18,7 @@ Download the archive with the binary file for your operating system from the [la We currently **officially** support the following operating systems: * Linux: [64-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz), [32-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_386.tar.gz) -* Linux ARM: [32-bit ARMv6](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv6.tar.gz) (recommended for Rapsberry Pi), [64-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_arm64.tar.gz), [32-bit ARMv5](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv5.tar.gz), [32-bit ARMv7](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv7.tar.gz) +* Linux ARM: [32-bit ARMv6](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv6.tar.gz) (recommended for Raspberry Pi), [64-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_arm64.tar.gz), [32-bit ARMv5](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv5.tar.gz), [32-bit ARMv7](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv7.tar.gz) * Linux MIPS: [32-bit MIPS](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mips_softfloat.tar.gz), [32-bit MIPSLE](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mipsle_softfloat.tar.gz), [64-bit MIPS](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mips64_softfloat.tar.gz), [64-bit MIPSLE](https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mips64le_softfloat.tar.gz) * Windows: [64-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_windows_amd64.zip), [32-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_windows_386.zip) * MacOS: [64-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_darwin_amd64.zip), [32-bit](https://static.adguard.com/adguardhome/release/AdGuardHome_darwin_386.zip) diff --git a/Hosts-Blocklists.md b/Hosts-Blocklists.md index 5a769de..f6c9900 100644 --- a/Hosts-Blocklists.md +++ b/Hosts-Blocklists.md @@ -8,6 +8,7 @@ * [Rule modifiers](#modifiers) * [client](#client) * [dnstype](#dnstype) + * [dnsrewrite](#dnsrewrite) * [important](#important) * [badfilter](#badfilter) * [ctag](#ctag) @@ -131,6 +132,8 @@ Client names usually contain spaces or other special characters, that's why you #### `dnstype` +(Since **v0.105.0**.) + The `$dnstype` modifier allows specifying DNS request type on which this rule will be triggered. @@ -162,6 +165,121 @@ $dnstype=value2 * `||example.org^$dnstype=~A|~CNAME` — Only allow `A` and `CNAME` DNS requests for `example.org`, block out the rest. +#### `dnsrewrite` + +(Since **v0.105.0**.) + +The `$dnsrewrite` response modifier allows replacing the content of the response +to the DNS request for the matching hosts. + +The shorthand syntax is: + +``` +$dnsrewrite=1.2.3.4 +$dnsrewrite=abcd::1234 +$dnsrewrite=example.net +$dnsrewrite=REFUSED +``` + +The keywords, like `REFUSED`, MUST be in all caps. + +The full syntax is of the form `RCODE;RRTYPE;VALUE`: + +``` +$dnsrewrite=NOERROR;A;1.2.3.4 +$dnsrewrite=NOERROR;AAAA;abcd::1234 +$dnsrewrite=NOERROR;CNAME;example.net +$dnsrewrite=REFUSED;; +``` + +The `CNAME` one is special because _AdGuardHome_ will resolve the host and add +its info to the response. That is, if example.net has IP `1.2.3.4`, and the +user has this in their filter rules: + +``` +||example.com^$dnsrewrite=example.net +``` + +Or: + +``` +||example.com^$dnsrewrite=NOERROR;CNAME;example.net +``` + +Then the response will be something like: + +``` +$ nslookup example.com my.adguard.local +Server: my.adguard.local +Address: 127.0.0.1#53 + +Non-authoritative answer: +example.com canonical name = example.net. +Name: example.net +Address: 1.2.3.4 +``` + +Keyword rewrites (for example, `REFUSED`) take precedence over the other. Next, +the `CNAME` rewrite. After that, all other records's values are summed as one +response, so this: + +``` +||example.com^$dnsrewrite=NOERROR;A;1.2.3.4 +||example.com^$dnsrewrite=NOERROR;A;1.2.3.5 +``` + +Will result in a response with two `A` records. + +Currently supported RR types with examples: + +* `||4.3.2.1.in-addr.arpa.^$dnsrewrite=NOERROR;PTR;example.net.` adds a `PTR` + record for reverse DNS. Reverse DNS requests for `1.2.3.4` to the + _AdGuardHome_ DNS server will result in `example.net`. + + **NOTE:** the IP MUST be in reverse order, and the value MUST contain a final + dot. See [RFC](https://tools.ietf.org/html/rfc1035#section-3.5). + +* `||example.com^$dnsrewrite=NOERROR;A;1.2.3.4` adds an `A` record with the + value `1.2.3.4`. + +* `||example.com^$dnsrewrite=NOERROR;AAAA;abcd::1234` adds an `AAAA` record with + the value `abcd::1234`. + +* `||example.com^$dnsrewrite=NOERROR;CNAME;example.org` adds a `CNAME` record. + See explanation above. + +* `||example.com^$dnsrewrite=NOERROR;HTTPS;32 example.com alpn=h3` adds an + `HTTPS` record. Only a subsed of parameter values is supported: values must + be `contiguous` and, where a `value-list` is expected`, only one value is + currently supported: + + ``` + ipv4hint=127.0.0.1 // Supported. + ipv4hint="127.0.0.1" // Unsupported. + ipv4hint=127.0.0.1,127.0.0.2 // Unsupported. + ipv4hint="127.0.0.1,127.0.0.2" // Unsupported. + ``` + + This will change in the future. + +* `||example.com^$dnsrewrite=NOERROR;MX;32 example.mail` adds an `MX` record + with precedence value `32` and exchange value `example.mail`. + +* `||example.com^$dnsrewrite=NOERROR;SVCB;32 example.com alpn=h3` adds and + `SVCB` value. See `HTTPS` above. + +* `||example.com^$dnsrewrite=NOERROR;TXT;hello_world` adds a `TXT` record with + the value `hello_world`. + +* `||example.com^$dnsrewrite=NXDOMAIN;;` responds with an `NXDOMAIN` code. + +Exception rules remove one or all rules: + +* `||example.com^$dnsrewrite` removes all DNS rewrite rules. + +* `||example.com^$dnsrewrite=1.2.3.4` removes the DNS rewrite rule that adds an + `A` record with the value `1.2.3.4`. + #### `important` The `$important` modifier applied to a rule increases its priority over any other rule without \$important modifier. Even over basic exception rules.