From 2f7c7f4a791e731b1541a1a8acfb902ffa35500d Mon Sep 17 00:00:00 2001
From: Ainar Garipov <a.garipov@adguard.com>
Date: Thu, 9 Dec 2021 14:58:47 +0300
Subject: [PATCH] Pull request: Hosts-Blocklists: imp section about client
 names

Merge in DNS/adguard-home-wiki from 3867-persistent-client-rules to master

Squashed commit of the following:

commit c41a7cc4bc64ba0a2a9ec9b369c5a1d9fa122313
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Dec 9 14:33:14 2021 +0300

    Hosts-Blocklists: imp section about client names
---
 Docker.md           |  2 +-
 Hosts-Blocklists.md | 40 ++++++++++++++++++++++++++--------------
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/Docker.md b/Docker.md
index 03f932c..ddb7c99 100644
--- a/Docker.md
+++ b/Docker.md
@@ -48,7 +48,7 @@ docker pull adguard/adguardhome
 
 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
+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
diff --git a/Hosts-Blocklists.md b/Hosts-Blocklists.md
index cf9448e..0cf55e4 100644
--- a/Hosts-Blocklists.md
+++ b/Hosts-Blocklists.md
@@ -153,7 +153,7 @@ rules and used to describe what a rule does.
 
 **Example:**
 
-```
+```none
 ! This is a comment.
 # This is also a comment.
 ```
@@ -194,8 +194,19 @@ EasyPrivacy.
 
   ####  <a href="#client" id="client" name="client">`client`</a>
 
-The `client` modifier allows specifying clients this rule will be working for.
-It accepts client names (**not** ClientIDs), IP addresses, or CIDR ranges.
+The `client` modifier allows specifying clients this rule is applied to.  There
+are two main ways to identify a client:
+
+ *  By their IP address or CIDR prefix.  This way works for all kinds of
+    clients.
+
+ *  By their name.  This way only works for persistent clients, that is clients
+    which you have manually added on the “Settings → Client settings” page.
+
+    **NOTE:** ClientIDs are not currently supported, only names are.  If you
+    have added a client with the name “My Client” and ClientID `my-client`,
+    spell your modifier as `$client='My Client'` as opposed to
+    `$client=my-client`.
 
 The syntax is:
 
@@ -203,9 +214,8 @@ The syntax is:
 $client=value1|value2|...
 ```
 
-You can also specify excluded clients by adding a `~` character before the
-client IP or name.  In this case, the rule will not be applied to this client's
-DNS requests.
+You can also exclude clients by adding a `~` character before the value.  In
+this case, the rule is not be applied to this client's DNS requests.
 
 ```none
 $client=~value1
@@ -216,8 +226,7 @@ you should enclose the name in quotes.  Both single and double ASCII quotes are
 supported.  Use the backslash (`\`) to escape quotes (`"` and `'`), commas
 (`,`), and pipes (`|`).
 
-Please note that when excluding a client, you must keep `~` **out** of the
-quotes.
+**NOTE:** When excluding a client, you **must** keep `~` out of the quotes.
 
 **Examples:**
 
@@ -359,8 +368,11 @@ user has this in their filter rules:
 
 then the response will be something like:
 
-```
+```sh
 $ nslookup example.com my.adguard.local
+```
+
+```none
 Server:		my.adguard.local
 Address:	127.0.0.1#53
 
@@ -374,7 +386,7 @@ 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:
 
-```
+```none
 ||example.com^$dnsrewrite=NOERROR;A;1.2.3.4
 ||example.com^$dnsrewrite=NOERROR;A;1.2.3.5
 ```
@@ -405,7 +417,7 @@ Currently supported RR types with examples:
     be `contiguous` and, where a `value-list` is expected`, only one value is
     currently supported:
 
-    ```
+    ```none
     ipv4hint=127.0.0.1             // Supported.
     ipv4hint="127.0.0.1"           // Unsupported.
     ipv4hint=127.0.0.1,127.0.0.2   // Unsupported.
@@ -551,7 +563,7 @@ The list of allowed tags:
 
 For each host a single line should be present with the following information:
 
-```
+```none
 IP_address canonical_hostname [aliases...]
 ```
 
@@ -566,7 +578,7 @@ spellings, shorter hostnames, or generic hostnames (for example, `localhost`).
 
 **Example:**
 
-```
+```none
 # This is a comment
 127.0.0.1 example.org example.info
 127.0.0.1 example.com
@@ -583,7 +595,7 @@ A simple list of domain names, one name per line.
 
 Example:
 
-```
+```none
 # This is a comment
 example.com
 example.org