Pull request: Added clients article

Merge in DNS/adguard-home-wiki from clients to master

Squashed commit of the following:

commit ecdd99cac9ff15dfd3f8f72192ca38ac418cd77c
Author: Andrey Meshkov <am@adguard.com>
Date:   Fri Jan 22 17:47:48 2021 +0300

    Fix review comments

commit 285f7221702b9e5faa15e90a34ab95a24bac3771
Author: Andrey Meshkov <am@adguard.com>
Date:   Fri Jan 22 16:58:40 2021 +0300

    Added clients article

Clients.md

@@ -0,0 +1,104 @@
+ # Configuring AdGuard Home Clients
+
+AdGuard Home allows flexible configuration for the devices that are connected to it. 
+On a basic level, you may just want to be able to distinguish them and see friendly 
+names instead of naked IP addresses. Additionally, AdGuard Home allows you applying 
+different rules depending on the client.
+
+* [Friendly names](#friendlynames)
+* [Creating a new client](#newclient)
+    * [Identifying clients](#idclient)
+    * [Settings](#clientsettings)
+* [Configuring filtering per-client](#perclientblocking)
+
+## <a id="friendlynames" href="#friendlynames">Friendly names</a>
+
+AdGuard Home tries to automatically find out some basic information about 
+the 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 file and uses hostnames found there to identify clients.
+2. Makes a reverse DNS lookup.
+3. Inspects the system ARP table.
+4. For public IP addresses it also makes a [whois](https://en.wikipedia.org/wiki/WHOIS) query in order to find out the client's location and the company the IP belongs to.
+
+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.
+
+![](images/top-clients-names.png)
+
+Note, that restarting AdGuard Home may be needed if you want to see the 
+change immediately.
+
+## <a id="newclient" href="#newclient">Creating a new client</a>
+
+If you want more than just to see the client names, you may want to 
+configure each client manually. If that's the case, head to "Clients settings" 
+and click "Add client" there.
+
+![](images/new-client.png)
+
+### <a id="idclient" href="#idclient">Identifying clients</a>
+
+First of all, you need to decide how you would like to identify the client.
+
+There are several options to do this.
+
+1. **IP address** - for instance, `192.168.0.1`. This is the easiest 
+way to do this, but it may be not good enough if the IP address changes too often.
+2. **CIDR range** - for instance, `192.168.0.1/24`. Allows attributing a 
+whole range of IP addresses (in the example it is `192.168.0.*`) to the same client.
+3. **MAC address** - using MAC as a client identifier is only possible when 
+AdGuard Home works as a [DHCP server](DHCP).
+4. **Client ID** - this method is supposed to be used for encrypted DNS protocols 
+(DoH, DoT or DoQ). Once this identifier is used, you can use a special domain 
+name while configuring your client. Here's an example:
+    * AdGuard Home domain name `example.org`.
+    * In AdGuard Home you add a client with the client ID `my-client`.
+    * On the client device you can now configure:
+        * `DNS-over-TLS`: `tls://my-client.example.org`
+        * `DNS-over-QUIC`: `quic://my-client.example.org`
+        * `DNS-over-HTTPS`: `https://example.org/dns-query-my-client`
+
+### <a id="clientsettings" href="#clientsettings">Settings</a>
+
+Each client can be configured individually. You may choose what to block, what 
+settings should be used, or you could even configure a completely different set 
+of upstream DNS servers to be used for this client.
+
+![](images/client-settings.png)
+
+## <a id="perclientblocking" href="#perclientblocking">Configuring blocking per-client</a>
+
+There are two ways of how you can configure blocking on the per-client basis.
+
+Both of them are based on using AdGuard blocklist rules syntax for the rules 
+you're adding to "Custom filtering rules".
+
+**`$client` rules**
+
+The first one is using `$client` modifier. This way you can limit the rule 
+to a client (or clients).
+
+Examples:
+
+* `@@||*^$client=127.0.0.1` — unblock everything for localhost
+* `||example.org^$client='Frank\'s laptop'` — block `example.org` for the 
+client named `Frank's laptop` only. Note that quote (`'`) in the name must be escaped.
+* `||example.org^$client=192.168.0.0/24` -- block `example.org` for all clients 
+with IP addresses in the range `192.168.0.0-192.168.0.255`
+
+You can find more examples in [the article](Hosts-Blocklists#client) about 
+blocking rules syntax.
+
+**`$ctag` rules**
+
+The second way is to use another modifier called `$ctag`. When you create 
+a new client, special "tags" can be assigned to it. These tags can then 
+be used in the filtering rules:
+
+* `||example.org^$ctag=device_pc|device_phone` - block `example.org` for 
+clients tagged as `device_pc` or `device_phone`
+* `||example.org^$ctag=~device_phone` - block `example.org` for all clients 
+except those tagged as `device_phone`

Comparison.md

@@ -1,5 +1,5 @@
 <a id="comparison"></a>
-## Comparing AdGuard Home to other solutions
+## Comparing AdGuard Home to Other Solutions
 
 <a id="comparison-adguard-dns"></a>
 ### How is this different from public AdGuard DNS servers?

Configuration.md

@@ -7,7 +7,6 @@ Most of these settings can be changed via the web-based admin interface. However
   - [Specifying upstreams for domains](#upstreams-for-domains)
   - [Loading the list of upstream servers from a file](#upstreams-from-file)
   - [Specifying upstreams for rDNS](#upstreams-for-rdns)
-- [Configuring clients friendly names](#friendly-names)
 - [Configuration file](#configuration-file)
 - [Reset Web Password](#password-reset)
 - [Profiling with pprof](#pprof)
@@ -123,29 +122,6 @@ You can do it using the same syntax as for general upstream servers, for example
 
 This rule instructs AdGuardHome to use `192.168.0.1` DNS server for all rDNS requests to resolve clients' IP addresses `192.168.0.0/16`.
 
-<a id="friendly-names"></a>
-
-## Configuring clients friendly names
-
-It may be useful to set up a friendly name for each IP address that clients use to connect to AdGuard Home. To do this, follow these steps:
-
-1.  Open `/etc/hosts` file in your text editor and add a name for each IP address, for example:
-
-        192.168.0.2    Mom
-        192.168.0.3    Dad
-        192.168.0.4    Sister
-        192.168.0.5    Brother
-
-    Note that on Windows file path to "hosts" file is different: `c:\windows\system32\drivers\etc\hosts`
-
-2.  Restart AdGuard Home
-
-As a result you will see that the clients names are now shown:
-
-![](top-clients-names.png)
-
-In the future, we plan to add more configuration options in this area.
-
 <a id="configuration-file"></a>
 
 ## Configuration file

DHCP.md

@@ -1,4 +1,4 @@
- #  *AdGuard Home* - DHCP Server
+ # AdGuard Home - DHCP Server
 
  *  [Prerequisites](#prereq)
  *  [Default Options](#default)

DNSCrypt.md

@@ -1,4 +1,4 @@
- #  *AdGuard Home* - *DNSCrypt*
+ # AdGuard Home* - DNSCrypt
 
 1. [Generating A Configuration File](#generate-config)
 2. [Generating A *DNSCrypt* Stamp](#generate-stamp)

Docker.md

@@ -1,4 +1,4 @@
-# AdGuard Home - Docker
+ # AdGuard Home - Docker
 
  
 <p align="center">

Encryption.md

@@ -1,4 +1,4 @@
-# AdGuard Home - Encryption
+ # AdGuard Home - Encryption
 
 We are proud to say that AdGuard Home supports all modern DNS encryption protocols **out-of-the-box**:
 

FAQ.md

@@ -1,4 +1,4 @@
-# AdGuard Home - FAQ
+ # AdGuard Home - FAQ
 
 ## Questions:
 

Getting-Started.md

@@ -1,4 +1,4 @@
-# AdGuard Home - Getting Started
+ # AdGuard Home - Getting Started
 
 In order to start using AdGuard Home, you need to do a few things:
 
@@ -94,7 +94,7 @@ Here are the other commands you might need to control the service.
 <a id="update"></a>
 ## How to update
 
-![](autoupdate-available.png)
+![](images/autoupdate-available.png)
 
 When a new version is released, AdGuard Home's UI shows a notification message and 'Update Now' button. Simply click on this button and AdGuard Home will be automatically upgraded to the latest version. Your current AdGuard Home executable file is saved inside 'backup' directory along with the current configuration file, so you can revert the changes, if necessary.
 

Home.md

@@ -1,4 +1,4 @@
-# AdGuard Home - Wiki
+ # AdGuard Home - Wiki
 
  
 <p align="center">
@@ -19,20 +19,20 @@
 
 Welcome to the AdGuard Home wiki!
 
-The wiki was just recently created, so there isn't much content (yet).
-
 ## Guides
 
 * [Getting Started](Getting-Started)
-* [FAQ](FAQ)
+    * [FAQ](FAQ)
-* [AdGuard Home Docker](Docker)
+    * [How to Write Hosts Blocklists](Hosts-Blocklists)
-* [Configuration](Configuration)
+    * [Comparing AdGuard Home to Other Solutions](Comparison)
-* [Comparing AdGuard Home to other solutions](Comparison)
+* Configuring AdGuard
-* [AdGuard Home as a DNS-over-HTTPS or DNS-over-TLS server](Encryption)
+    * [Configuration](Configuration)
-* [AdGuard Home as a DNSCrypt server](DNSCrypt)
+    * [Configuring AdGuard Home Clients](Clients)
-* [AdGuard Home as a DHCP server](DHCP)
+    * [AdGuard Home as a DoH, DoT, or DoQ Server](Encryption)
-* [How to install and run AdGuard Home on Raspberry Pi](Raspberry-Pi)
+    * [AdGuard Home as a DNSCrypt Server](DNSCrypt)
-* [How to install and run AdGuard Home on a Virtual Private Server](VPS)
+    * [AdGuard Home as a DHCP Server](DHCP)
-* [OpenRC service-script](OpenRC)
+* Installing AdGuard Home
-* [How to write hosts blocklists](Hosts-Blocklists)
+    * [Docker](Docker)
+    * [How to Install and Run AdGuard Home on a Raspberry Pi](Raspberry-Pi)
+    * [How to Install and Run AdGuard Home on a Virtual Private Server](VPS)
 * [Verifying Releases](Verify-Releases)

Hosts-Blocklists.md

@@ -1,4 +1,4 @@
-# AdGuard Home - How to write hosts blocklists
+ # AdGuard Home - How to Write Hosts Blocklists
 
 * [Introduction](#introduction)
 * [Rules examples](#examples)

OpenRC.md

@@ -1,61 +0,0 @@
-# AdGuard Home - OpenRC service-script
-
-A service-script for OpenRC-based systems, for example if you run AdGuard Home in Alpine (without using Docker).
-
-## Installation
-
-Install OpenRC:
-
-    apk update
-    apk add openrc
-
-Then copy the script below to /etc/init.d/adguardhome
-
-    #!/sbin/openrc-run
-    #
-    # openrc service-script for AdGuardHome
-    #
-    # place in /etc/init.d/
-    # start on boot: "rc-update add adguardhome"
-    # control service: "service adguardhome <start|stop|restart|status|checkconfig>"
-    #
-
-    description="AdGuard Home: Network-level blocker"
-
-    pidfile="/run/$RC_SVCNAME.pid"
-    command="/opt/AdGuardHome/AdGuardHome"
-    command_args="-s run"
-    command_background=true
-
-    extra_commands="checkconfig"
-
-    depend() {
-        need net
-        provide dns
-        after firewall
-    }
-
-    checkconfig() {
-        "$command" --check-config || return 1
-    }
-
-    stop() {
-        if [ "${RC_CMD}" = "restart" ] ; then
-            checkconfig || return 1
-        fi
-
-        ebegin "Stopping $RC_SVCNAME"
-        start-stop-daemon --stop --exec "$command" \
-            --pidfile "$pidfile" --quiet
-        eend $?
-    }
-
-## Usage
-
-Enable running AdGuard Home on boot:
-
-    rc-update add adguardhome
-
-Controlling AdGuard Home:
-
-    service adguardhome <start|stop|restart|status|checkconfig>

Raspberry-Pi.md

@@ -1,4 +1,4 @@
-# How to set up your own AdGuard Home on Raspberry Pi
+ # How to Install and Run AdGuard Home on a Raspberry Pi
 
 You can install AdGuard Home on your [Raspberry Pi](https://www.raspberrypi.org) and use it to filter out ads. This also saves data traffic.
 
@@ -58,8 +58,8 @@ Go to [AdGuard Home page](https://github.com/AdguardTeam/AdGuardHome#installatio
 Let's download AdGuard Home and unpack it:
 ```bash
 cd $HOME
-wget https://static.adguard.com/adguardhome/release/AdGuardHome_linux_arm.tar.gz
+wget https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv6.tar.gz
-tar xvf AdGuardHome_linux_arm.tar.gz
+tar xvf AdGuardHome_linux_armv6.tar.gz
 ```
 It will unpack into a new directory called `AdGuardHome`.
 

VPS.md

@@ -1,3 +1,5 @@
+ # How to Install and Run AdGuard Home on a Virtual Private Server
+
 To run AdGuard Home on a VPS, you need a server with Debian 8 or 9, x64 or x32. 
 
 >Among possible solutions are [Vultr](https://www.vultr.com/), [1&1](https://www.1and1.co.uk/dynamic-cloud-server#configure-server), [Cloudways](https://www.cloudways.com/), [HostGator](https://hostgator.com/), [Digital Ocean](https://www.digitalocean.com/), [Bytemark](https://www.bytemark.co.uk/cloud-hosting/) and many more. AdGuard is not affiliated with any of these or other VPS services.

Verify-Releases.md

@@ -1,4 +1,4 @@
-# Verifying AdGuard Home Releases
+ # Verifying AdGuard Home Releases
 
 Since AdGuard Home v0.103.4 we sign the executable files we build so you can verify they are really created by us and no one else.
 Inside an archive file there's a small file with `.sig` extension which contains the signature data.

__Sidebar.md

@@ -1,15 +1,17 @@
 ## Guides
 
 * [Getting Started](Getting-Started)
-* [FAQ](FAQ)
+    * [FAQ](FAQ)
-* [Docker](Docker)
+    * [How to Write Hosts Blocklists](Hosts-Blocklists)
-* [Configuration](Configuration)
+    * [Comparing AdGuard Home to Other Solutions](Comparison)
-* [Comparing AdGuard Home to other solutions](Comparison)
+* Configuring AdGuard
-* [AdGuard Home as a DNS-over-HTTPS or DNS-over-TLS server](Encryption)
+    * [Configuration](Configuration)
-* [AdGuard Home as a DNSCrypt server](DNSCrypt)
+    * [Configuring AdGuard Home Clients](Clients)
-* [AdGuard Home as a DHCP server](DHCP)
+    * [AdGuard Home as a DoH, DoT, or DoQ Server](Encryption)
-* [How to install and run AdGuard Home on Raspberry Pi](Raspberry-Pi)
+    * [AdGuard Home as a DNSCrypt Server](DNSCrypt)
-* [How to install and run AdGuard Home on a Virtual Private Server](VPS)
+    * [AdGuard Home as a DHCP Server](DHCP)
-* [OpenRC service-script](OpenRC)
+* Installing AdGuard Home
-* [How to write hosts blocklists](Hosts-Blocklists)
+    * [Docker](Docker)
+    * [How to Install and Run AdGuard Home on a Raspberry Pi](Raspberry-Pi)
+    * [How to Install and Run AdGuard Home on a Virtual Private Server](VPS)
 * [Verifying Releases](Verify-Releases)