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 <A.Garipov@AdGuard.COM>
Date:   Mon Jul 26 17:49:06 2021 +0300

    Configuration: add href

commit 3dc4c4d7a00150208a4361043572ad414c49f48c
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Mon Jul 26 17:29:35 2021 +0300

    all: imp upstream docs, fix stuff

Configuration.md

@@ -8,6 +8,9 @@ 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)
@@ -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`.
 
-### <a id="upstreams-for-rdns">Specifying Upstreams For Reverse DNS</a>
+   ###  <a href="#upstreams-for-rdns" id="upstreams-for-rdns" name="upstreams-for-rdns">Specifying Upstreams For Reverse DNS</a>
 
-AdGuard Home automatically gets the names of connected devices using reverse DNS
+Using the domain-specific upstream notation, you can specify dedicated upstream
-lookup (rDNS).  It sends `PTR` requests with the IP addresses of clients to DNS
+DNS servers for reverse DNS (rDNS) requests.  If you want **all** your `PTR`
-servers and uses the responses for “clients' human-friendly names”.
+queries to be redirected to `192.168.8.8`:
 
-Since **v0.106.0** you can enable and disable this feature with “Enable clients'
+1.  Enter the following into the “Upstream DNS servers” field on the “Settings
-hostname resolution” setting in the “Upstream DNS servers” section or via the
+    → DNS settings” page:
-`resolve_clients` field in the configuration file.
 
-Also since **v0.106.0** all the addresses from [private IP ranges][private-ip]
+    ```none
-are only resolved via appropriate local resolvers to avoid the leaks of clients'
+    [/in-addr.arpa/]192.168.8.8
-information.  But you can also set custom upstreams for it in the “Private DNS
+    [/ip6.arpa/]192.168.8.8
-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.
+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.
+
+  ####  <a href="#rdns-private" id="rdns-private" name="rdns-private">Private Addresses</a>
+
+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
+configuration file.  If it is disabled, the unknown addresses from locally
-locally served networks won't be resolved at all.
+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
+  ####  <a href="#rdns-public" id="rdns-public" name="rdns-public">Public Addresses</a>
-address range?  You can do it using the same syntax as for general upstream
+
-servers, for example:
+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
+then AdGuard Home will use the `192.168.7.7` DNS server for all rDNS requests to
-requests to resolve clients' IP addresses from the `128.0.0.0/8` network.
+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
+Note that if you want to use that address for `PTR` queries for IP addresses in
-outside of the locally served network ranges, you should also add this to your
+a locally served network range, for example `192.168.0.0/16`, you should add
-main “Upstream DNS servers” field:
+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
 ```
 
+  ####  <a href="#rdns-clients" id="rdns-clients" name="rdns-clients">Client Look-Ups</a>
+
+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

Docker.md

@@ -8,9 +8,7 @@
 <p align="center">
     Free and open source, powerful network-wide ads & trackers blocking DNS server.
 </p>
-
 <br/>
-
 <p align="center">
     <img src="https://cdn.adguard.com/public/Adguard/Common/adguard_home.gif" width="800"/>
 </p>
@@ -18,7 +16,7 @@
  *  [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)
@@ -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.
 
@@ -131,7 +129,7 @@ Ports mappings you may need:
 
 
 
-##  <a href="#unstable" id="unstable" name="unstable">Running Dev Builds</a>
+##  <a href="#unstable" id="unstable" name="unstable">Running Development Builds</a>
 
 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,13 +144,13 @@ docker pull adguard/adguardhome:edge
 
 ## <a href="#configuration" id="configuration" name="configuration">Additional Configuration</a>
 
-Upon the first run, a file named `AdGuardHome.yaml` will be created, with
+Upon the first run, a file with the default values named `AdGuardHome.yaml` is
-default values written into it.  You can modify the file while your AdGuard Home
+created.  You can modify the file while your AdGuard Home container is not
-container is not running.  Otherwise, any changes to the file will be lost
+running.  Otherwise, any changes to the file will be lost because the running
-because the running program will overwrite them.
+program will overwrite them.
 
-Settings are stored in [YAML], possible parameters that you can configure are
+The settings are stored in the [YAML] format.  The documentation describing all
-listed on [this page][conf].
+configurable parameters and their values is available on [this page][conf].
 
 [YAML]: https://yaml.org
 [conf]: https://github.com/AdguardTeam/Adguardhome/wiki/Configuration

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.
@@ -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