Pull request: 3020 client sources

Merge in DNS/adguard-home-wiki from 3020-client-sources to master

Squashed commit of the following:

commit ab09b87744fa339e4fedb351985659485cfebb6f
Author: Eugene Burkov <E.Burkov@AdGuard.COM>
Date:   Tue Apr 26 13:38:01 2022 +0300

    all: imp fmt, grammar

commit 897546e8e91389ae713b0112b9944b97882f7582
Author: Eugene Burkov <E.Burkov@AdGuard.COM>
Date:   Mon Apr 25 13:44:23 2022 +0300

    all: desc client sources

Clients.md

@@ -20,15 +20,18 @@ device that's connecting to it.
 
 Here is what it tries to do in order to figure out the client's hostname:
 
-1.  Inspects the hosts files (for example, `/etc/hosts` on Unix systems) and
-    uses hostnames found there to identify clients.
+1.  inspects the hosts files (for example, `/etc/hosts`) and uses hostnames
+    found there to identify clients;
 
-1.  Makes reverse DNS lookups.
+1.  makes reverse DNS lookups;
 
-1.  Inspects the system ARP table.
+1.  inspects the system ARP table;
 
-1.  For public IP addresses it also makes [WHOIS][whois] queries in order to
-    find out the client's location and the company the IP belongs to.
+1.  for public IP addresses it also makes [WHOIS][whois] queries in order to
+    find out the client's location and the company the IP belongs to;
+
+1.  for IP addresses leased by AdGuard Home's DHCP server it obtains the
+    hostname from leases.
 
 If the only thing you need is to see friendly names in AdGuard Home stats then
 editing the hosts file may be the easiest way to achieve this.  Please note that
@@ -36,7 +39,11 @@ you may need to restart AdGuard Home to apply the changes.
 
 ![](images/top-clients-names.png)
 
-[whois]: https://en.wikipedia.org/wiki/WHOIS
+Since **v0.108.0** runtime clients sources can be disabled via the
+[`clients.runtime_sources`][sources] object of the configuration file.
+
+[whois]:   https://en.wikipedia.org/wiki/WHOIS
+[sources]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file
 
 
 

Configuration.md

@@ -38,7 +38,7 @@ Options:
   --check-config                     Check configuration and exit.
   --no-check-update                  Don't check for updates.
   --no-mem-optimization              Deprecated.  Disable memory optimization.
-  --no-etc-hosts                     Do not use the OS-provided hosts.
+  --no-etc-hosts                     Deprecated.  Do not use the OS-provided hosts.
   --local-frontend                   Use local frontend directories.
   -v, --verbose                      Enable verbose output.
   --glinet                           Run in GL-Inet compatibility mode.
@@ -50,8 +50,9 @@ Please note, that the command-line arguments override settings from the configur
 
 `./AdGuardHome -s reload` command does the following:
 
-- Re-read runtime clients from `/etc/hosts` file and `arp -a` output
-- Re-read SSL certificate file (if it has changed)
+ -  refresh the runtime clients data from the operating system's ARP tables;
+
+ -  re-read SSL certificate file (if it has changed).
 
 Command-line arguments passed to `-s install` command will be then used by the
 service.  For instance, if you install the AdGuard Home service using `sudo
@@ -493,6 +494,18 @@ Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possib
   - `user` — The name of the user to switch to after the startup.
   - `rlimit_nofile` — Limit on the maximum number of open files for the server
     process (on unixlike OSes).  Set to `0` to use the system's default value.
+- **Clients settings**
+  - `clients` — Persistent and runtime clients settings.
+    - `persistent` — An array of explicitly configured clients.  **Before
+      v0.108.0** the contents of this field took up the whole `clients` section.
+    - `runtime_sources` — **Since v0.108.0** this controls the certain runtime
+      clients sources.
+      - `whois` — Request WHOIS information for clients with public IP
+        addresses.
+      - `arp` — Consider the operating system's ARP table.
+      - `rdns` — Perform rDNS lookups for client's address.
+      - `dhcp` — Check AdGuard Home's DHCP leases for client's address.
+      - `hosts` — Follow the operating system's hosts files.
 - **Log settings**
   - `log_file` — Path to the log file. If empty, writes to stdout, if `syslog` -- system log (or eventlog on Windows).
   - `log_compress` — Compress determines if the rotated log files should be compressed using gzip (default: false)