From ab8edf045893103cb6f1b3b14371690d558f5e35 Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Mon, 26 Jul 2021 19:27:08 +0300 Subject: [PATCH] Pull request: all: imp upstream docs, fix stuff Merge in DNS/adguard-home-wiki from 3307-imp-upstream-doc to master Squashed commit of the following: commit e2b6ac174454dc20cd5de634d641e20cfea8293b Author: Ainar Garipov Date: Mon Jul 26 17:49:06 2021 +0300 Configuration: add href commit 3dc4c4d7a00150208a4361043572ad414c49f48c Author: Ainar Garipov Date: Mon Jul 26 17:29:35 2021 +0300 all: imp upstream docs, fix stuff --- Configuration.md | 109 ++++++++++++++++++++++++++++++-------------- Docker.md | 46 +++++++++---------- Hosts-Blocklists.md | 41 ++++++++++------- 3 files changed, 121 insertions(+), 75 deletions(-) diff --git a/Configuration.md b/Configuration.md index 0b2ebdd..efd0a7f 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,4 +1,4 @@ -# AdGuard Home - Configuration + # AdGuard Home - Configuration Most of these settings can be changed via the web-based admin interface. However, we decided to list them all here just in case. @@ -8,13 +8,16 @@ However, we decided to list them all here just in case. * [Specifying Upstreams For Domains](#upstreams-for-domains) * [Loading Upstreams From File](#upstreams-from-file) * [Specifying Upstreams For Reverse DNS](#upstreams-for-rdns) + * [Private Addresses](#rdns-private) + * [Public Addresses](#rdns-public) + * [Client Look-Ups](#rdns-clients) * [Configuration File](#configuration-file) * [Reset Web Password](#password-reset) * [Profiling With Pprof](#pprof) -## Command-line Arguments +## Command-line Arguments Here is a list of all available command-line arguments. @@ -56,7 +59,7 @@ functionality in the service as well. -## Configuring Upstreams +## Configuring Upstreams AdGuard Home is basically a DNS proxy that sends your DNS queries to the upstream servers. You can specify multiple upstream servers in AdGuard Home @@ -79,7 +82,7 @@ Examples: * `[/example.local/]1.1.1.1`: DNS upstream for specific domains, see below. -### Specifying Upstreams For Domains +### Specifying Upstreams For Domains You can specify upstreams that will be used for specific domains using the dnsmasq-like syntax (see the documentation for the option `--server` @@ -126,7 +129,7 @@ a configuration like this: sends queries for `*.host.com` to `1.2.3.4` except for queries for `*.www.host.com`, which are sent to `6.7.8.9`, which is the default upstream. -#### Examples + #### Examples * A configuration like: @@ -149,7 +152,7 @@ sends queries for `*.host.com` to `1.2.3.4` except for queries for sends queries for `*.host.com` to `1.1.1.1:53` except for `*.maps.host.com` which are sent to `8.8.8.8:53` along with all other queries. -### Loading Upstreams From File + ### Loading Upstreams From File Using specific upstreams for some domains is a common way to accelerate internet in China. For an example, see https://github.com/felixonmars/dnsmasq-china-list @@ -166,48 +169,86 @@ may want to load them from a separate file instead of setting all upstreams in AdGuard Home settings. To do that, simply specify the path to a file with your list in the `upstream_dns_file` field of `AdGuardHome.yaml`. -### Specifying Upstreams For Reverse DNS + ### Specifying Upstreams For Reverse DNS -AdGuard Home automatically gets the names of connected devices using reverse DNS -lookup (rDNS). It sends `PTR` requests with the IP addresses of clients to DNS -servers and uses the responses for “clients' human-friendly names”. +Using the domain-specific upstream notation, you can specify dedicated upstream +DNS servers for reverse DNS (rDNS) requests. If you want **all** your `PTR` +queries to be redirected to `192.168.8.8`: -Since **v0.106.0** you can enable and disable this feature with “Enable clients' -hostname resolution” setting in the “Upstream DNS servers” section or via the -`resolve_clients` field in the configuration file. +1. Enter the following into the “Upstream DNS servers” field on the “Settings + → DNS settings” page: -Also since **v0.106.0** all the addresses from [private IP ranges][private-ip] -are only resolved via appropriate local resolvers to avoid the leaks of clients' -information. But you can also set custom upstreams for it in the “Private DNS -servers” field in the “Upstream DNS servers” section or via the -`local_ptr_upstreams` field in the configuration file. Note that the specified -upstreams are also used by DNS server to resolve `PTR` for the same IP range. + ```none + [/in-addr.arpa/]192.168.8.8 + [/ip6.arpa/]192.168.8.8 + ``` + +2. Enter the following into the “Private reverse DNS servers” field on the + same page below the previous field: + + ```none + 192.168.8.8 + ``` + + There is no need to use the domain-specific notation here, unless you want + to redirect requests for different private ranges to different upstream + servers. + +**NOTE:** All upstreams for private ranges **must** go to the “Private reverse +DNS servers” field **and not** the main “Upstream DNS servers” field. Entering +something like `[/192.in-addr.arpa/]192.168.8.8` into the main field will have +no effect. + +Read below for more details. + + #### Private Addresses + +Since **v0.106.0** all the addresses from [private IP ranges][private-ip] +are only resolved via appropriate local resolvers to avoid leaks of clients' +information. By default, AdGuard Home tries to get the addresses of the default +resolvers from the OS. You can set custom upstreams for it in the “Private +reverse DNS servers” field in the “Upstream DNS servers” section or via the +`local_ptr_upstreams` field in the configuration file. Since **v0.107.0** you can disable the usage of private reverse DNS upstream servers via the “Use private reverse DNS resolvers” checkbox in the “Upstream DNS servers” section or via the `use_private_ptr_resolvers` field in the -configuration file. If it is disabled, the unknown addresses from -locally served networks won't be resolved at all. +configuration file. If it is disabled, the unknown addresses from locally +served networks won't be resolved at all, and clients performing these queries +will receive `NXDOMAIN` responses. -But what if you want AdGuard Home to use another DNS server for a specific IP -address range? You can do it using the same syntax as for general upstream -servers, for example: + #### Public Addresses + +If you want AdGuard Home to use another DNS server for a specific IP address +range, you can do it using the same syntax as for general upstream servers. For +example, if you add this to your “Upstream DNS servers” field: ```none -[/128.in-addr.arpa/]192.168.8.8 +[/200.in-addr.arpa/]192.168.7.7 ``` -This rule instructs AdGuard Home to use `192.168.8.8` DNS server for all rDNS -requests to resolve clients' IP addresses from the `128.0.0.0/8` network. +then AdGuard Home will use the `192.168.7.7` DNS server for all rDNS requests to +resolve clients' IP addresses from the `200.0.0.0/8` network. -Note that if you want to use that address for `PTR` queries for IP addresses -outside of the locally served network ranges, you should also add this to your -main “Upstream DNS servers” field: +Note that if you want to use that address for `PTR` queries for IP addresses in +a locally served network range, for example `192.168.0.0/16`, you should add +this to the “Private reverse DNS servers” field: ```none -[/in-addr.arpa/]192.168.8.8 +[/168.192.in-addr.arpa/]192.168.7.7 ``` + #### Client Look-Ups + +AdGuard Home automatically gets the names of connected devices using reverse DNS +lookup (rDNS). It sends `PTR` requests with the IP addresses of clients to +appropriate DNS servers and uses the responses to enrich client information with +human-friendly names. + +Since **v0.106.0** you can enable and disable this feature with “Enable clients' +hostname resolution” setting in the “Upstream DNS servers” section or via the +`resolve_clients` field in the configuration file. + [DNS Stamps]: https://dnscrypt.info/stamps/ [DNS-over-HTTPS]: https://en.wikipedia.org/wiki/DNS_over_HTTPS [DNS-over-QUIC]: https://datatracker.ietf.org/doc/html/draft-ietf-dprive-dnsoquic-03 @@ -218,7 +259,7 @@ main “Upstream DNS servers” field: -## Configuration File +## Configuration File Upon the first execution, a file named `AdGuardHome.yaml` will be created, with default values written in it. You can modify the file while your AdGuard Home service is not running. Otherwise, any changes to the file will be lost because the running program will overwrite them. @@ -407,7 +448,7 @@ Removing an entry from settings file will reset it to the default value. Deletin -## Reset Web Password +## Reset Web Password AdGuard Home stores password as a BCrypt-encoded hash. @@ -434,7 +475,7 @@ Now you'll be able to log in to Web interface using your new password. -## Profiling With Pprof +## Profiling With Pprof To enable pprof, set `debug_pprof: true` in yaml configuration file and then restart AdGuard Home. Now you can get profiling information with your browser, diff --git a/Docker.md b/Docker.md index e17109f..03f932c 100644 --- a/Docker.md +++ b/Docker.md @@ -2,23 +2,21 @@  

- AdGuard Home + AdGuard Home

Privacy protection center for you and your devices

- Free and open source, powerful network-wide ads & trackers blocking DNS server. + Free and open source, powerful network-wide ads & trackers blocking DNS server.

- -
- +

- +

* [Introduction](#introduction) * [Quick Start](#quickstart) * [Update To A Newer Version](#update) - * [Running Dev Builds](#unstable) + * [Running Development Builds](#unstable) * [Additional Configuration](#configuration) * [DHCP Server](#dhcp) * [`resolved`](#resolved-daemon) @@ -38,7 +36,7 @@ repository][agh]. ## Quick Start - ### Pull the Docker image + ### Pull the Docker image This command will pull the latest stable version: @@ -46,14 +44,14 @@ This command will pull the latest stable version: docker pull adguard/adguardhome ``` - ### Create directories for persistent configuration and data + ### Create directories for persistent configuration and data The image exposes two volumes for data and configuration persistence. You should create a **data** directory on a suitable volume on your host system, e.g. `/my/own/workdir`, and a **configuration** directory on a suitable volume on your host system, e.g. `/my/own/confdir`. - ### Create and run the container + ### Create and run the container Use the following command to create a new container and run AdGuard Home: @@ -76,7 +74,7 @@ your AdGuard Home service. Don't forget to use your own **data** and **config** directories! -Ports mappings you may need: +Port mappings you might need: * `-p 53:53/tcp -p 53:53/udp`: plain DNS. @@ -97,7 +95,7 @@ Ports mappings you may need: * `-p 5443:5443/tcp -p 5443:5443/udp`: add if you are going to run AdGuard Home as a [DNSCrypt] server. - ### Control the container + ### Control the container * Start: `docker start adguardhome` @@ -131,7 +129,7 @@ Ports mappings you may need: -## Running Dev Builds +## Running Development Builds If you want to be on the bleeding edge, you might want to run the image from the `edge` or `beta` tags. In order to use it, simply replace `adguard/adguardhome` @@ -146,20 +144,20 @@ docker pull adguard/adguardhome:edge ## Additional Configuration -Upon the first run, a file named `AdGuardHome.yaml` will be created, with -default values written into it. You can modify the file while your AdGuard Home -container is not running. Otherwise, any changes to the file will be lost -because the running program will overwrite them. +Upon the first run, a file with the default values named `AdGuardHome.yaml` is +created. You can modify the file while your AdGuard Home container is not +running. Otherwise, any changes to the file will be lost because the running +program will overwrite them. -Settings are stored in [YAML], possible parameters that you can configure are -listed on [this page][conf]. +The settings are stored in the [YAML] format. The documentation describing all +configurable parameters and their values is available on [this page][conf]. [YAML]: https://yaml.org [conf]: https://github.com/AdguardTeam/Adguardhome/wiki/Configuration -## DHCP Server +## DHCP Server If you want to use AdGuardHome's DHCP server, you should pass `--network host` argument when creating the container: @@ -174,13 +172,13 @@ this case. A note from the Docker documentation: -> The host networking driver only works on Linux hosts, and is not supported on -> Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows -> Server. + > The host networking driver only works on Linux hosts, and is not supported on + > Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows + > Server. -## `resolved` +## `resolved` If you try to run AdGuardHome on a system where the `resolved` daemon is started, docker will fail to bind on port 53, because `resolved` daemon is diff --git a/Hosts-Blocklists.md b/Hosts-Blocklists.md index 53f4e75..016e342 100644 --- a/Hosts-Blocklists.md +++ b/Hosts-Blocklists.md @@ -26,7 +26,7 @@ There are three different approaches to writing hosts blocklists: This way blocklists are compatible with browser ad blockers. * [`/etc/hosts` syntax](#etc-hosts): the old, tried-and-true approach that - uses the same syntax the one operating systems use for their hosts files. + uses the same syntax that operating systems do for their hosts files. * [Domains-only syntax](#domains-only): a simple list of domain names. @@ -34,7 +34,7 @@ If you are creating a blocklist for AdGuard Home, we recommend using the [Adblock-style syntax](#adblock-style). It has a couple of important advantages over the old-style syntax: - * **Blocklists size.** Using pattern-matching allows you to have a single + * **Blocklists size.** Using pattern matching allows you to have a single rule instead of hundreds of `/etc/hosts` entries. * **Compatibility.** Your blocklist will be compatible with browser ad @@ -72,7 +72,14 @@ work. --> subdomains. `www.example.org` remains allowed. Using the unspecified IP address (`0.0.0.0`) or a local address (`127.0.0.1` - and alike) with an address is basically the same as blocking this address. + and alike) for a host is basically the same as blocking that host. + + ```none + # Returns the IP address 1.2.3.4 for exmaple.org. + 1.2.3.4 example.org + # Blocks example.com by responding with 0.0.0.0. + 0.0.0.0 example.com + ``` * `example.org`: a simple domain rule. Blocks `example.org` domain but **not** its subdomains. `www.example.org` remains allowed. @@ -103,7 +110,7 @@ modifiers = [modifier0, modifier1[, ...[, modifierN]]] * `modifiers`: parameters that clarify the rule. They may limit the scope of the rule or even completely change the way it works. - ### Special Characters + ### Special Characters * `*`: the wildcard character. It is used to represent any set of characters. This can also be an empty string or a string of any length. @@ -121,7 +128,7 @@ modifiers = [modifier0, modifier1[, ...[, modifierN]]] `ample.org|` corresponds to `example.org` but not to `example.org.com`. `|example` corresponds to `example.org` but not to `test.example`. - ### Regular Expressions + ### Regular Expressions If you want even more flexibility in making rules, you can use [regular expressions][regexp] instead of the default simplified matching syntax. If you @@ -138,7 +145,7 @@ pattern = "/" regexp "/" * `@@/example.*/$important` will unblock hosts matching the `example.*` regexp. Note that this rule also implies the `important` modifier. - ### Comments + ### Comments Any line that starts with an exclamation mark or a hash sign is a comment and it will be ignored by the filtering engine. Comments are usually placed above @@ -151,7 +158,7 @@ rules and used to describe what a rule does. # This is also a comment. ``` - ### Rule Modifiers + ### Rule Modifiers You can change the behavior of a rule by adding modifiers. Modifiers must be located at the end of the rule after the `$` character and be separated by @@ -185,7 +192,7 @@ rule **must be ignored**. This way we avoid false-positives when people are trying to use unmodified browser ad blockers' filter lists like EasyList or EasyPrivacy. -#### `client` + #### `client` The `client` modifier allows specifying clients this rule will be working for. It accepts client names (**not** ClientIDs), IP addresses, or CIDR ranges. @@ -231,7 +238,7 @@ quotes. * `||example.org^$client=192.168.0.0/24`: block `example.org` for all clients with IP addresses in the range from `192.168.0.0` to `192.168.0.255`. -#### `denyallow` + #### `denyallow` Available since **v0.106.0**. @@ -275,7 +282,7 @@ how to solve this with `denyallow`: * `||example.org^$denyallow=sub.example.org`. block `example.org` and `*.example.org` but don't block `sub.example.org`. -#### `dnstype` + #### `dnstype` Available since **v0.105.0**. @@ -312,7 +319,7 @@ $dnstype=value2 * `||example.org^$dnstype=~A|~CNAME`: only allow `A` and `CNAME` DNS queries for `example.org`, block out the rest. -#### `dnsrewrite` + #### `dnsrewrite` Available since **v0.105.0**. @@ -429,7 +436,7 @@ Exception rules remove one or all 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` + #### `important` The `important` modifier applied to a rule increases its priority over any other rule without the modifier. Even over basic exception rules. @@ -455,7 +462,7 @@ other rule without the modifier. Even over basic exception rules. the exception rule also has the `important` modifier, so it will work. -#### `badfilter` + #### `badfilter` The rules with the `badfilter` modifier disable other basic rules to which they refer. It means that the text of the disabled rule should match the text of the @@ -471,7 +478,7 @@ refer. It means that the text of the disabled rule should match the text of the `/etc/hosts`-style rules. `127.0.0.1 example.org$badfilter` will **not** disable the original `127.0.0.1 example.org` rule. -#### `ctag` + #### `ctag` The `ctag` modifier allows to block domains only for specific types of DNS client tags. You can assign tags to clients in the AdGuard Home UI. In the @@ -511,13 +518,13 @@ The list of allowed tags: * `device_gameconsole`: game consoles. * `device_laptop`: laptops, * `device_nas`: NAS (Network-attached Storages). - * `device_other`: other devices. * `device_pc`: PCs. * `device_phone`: phones. * `device_printer`: printers. * `device_securityalarm`: security alarms. * `device_tablet`: tablets. * `device_tv`: TVs. + * `device_other`: other devices. * By operating system: @@ -525,14 +532,14 @@ The list of allowed tags: * `os_ios`: iOS. * `os_linux`: Linux. * `os_macos`: macOS. - * `os_other`: other OSes. * `os_windows`: Windows. + * `os_other`: other OSes. * By user group: * `user_admin`: administrators. - * `user_child`: children. * `user_regular`: regular users. + * `user_child`: children. [adb]: https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters [regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions