From bb57b99a267ad4e92e4812ae95b9ac86f47da52d Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Thu, 10 Feb 2022 15:35:28 +0300 Subject: [PATCH] Pull request: Clients: imp Updates AdguardTeam/AdGuardHome#4244. Squashed commit of the following: commit 9741b3dd11d7ed96b8b0db7b7e7b1af0d02c21e7 Author: Ainar Garipov Date: Thu Feb 10 13:45:10 2022 +0300 Clients: imp hosts info commit 58871afe17a79f203a1d8538cd0660a8932a8504 Author: Ainar Garipov Date: Wed Feb 9 14:32:05 2022 +0300 Clients: fmt, imp text commit 8b81c453d3a57716eac8d09a4f2c55b29b706836 Author: Ainar Garipov Date: Tue Feb 8 21:29:50 2022 +0300 Clients: imp --- Clients.md | 171 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 104 insertions(+), 67 deletions(-) diff --git a/Clients.md b/Clients.md index 198125e..5642c5e 100644 --- a/Clients.md +++ b/Clients.md @@ -1,113 +1,150 @@ - # Configuring AdGuard Home Clients + # AdGuard Home - Configuring 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. +AdGuard Home allows flexible configuration for 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) + * [Friendly Names](#friendlynames) + * [Persistent Clients](#newclient) + * [Identifying clients](#idclient) + * [Settings](#clientsettings) + * [Per-Client Blocking](#perclientblocking) -## Friendly names -AdGuard Home tries to automatically find out some basic information about -the device that's connecting to it. + +## Friendly Names + +AdGuard Home tries to automatically collect 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. +1. Inspects the hosts files (for example, `/etc/hosts` on Unix systems) and + uses hostnames found there to identify clients. -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. +1. Makes reverse DNS lookups. + +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. + +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 +you may need to restart AdGuard Home to apply the changes immediately. ![](images/top-clients-names.png) -Note, that restarting AdGuard Home may be needed if you want to see the -change immediately. +[whois]: https://en.wikipedia.org/wiki/WHOIS -## Creating a new client -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. + +## Persistent Clients + +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 the “Settings → Clients +settings” page and click the "Add client" button there. ![](images/new-client.png) -### Identifying clients + + + ### Identifying clients 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 +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 + +1. **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** *(added in v0.105)*. 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 has the 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: +1. **MAC address.** Using MAC as a client identifier is **only** possible when + AdGuard Home works as the network's [DHCP server](DHCP). - * `DNS-over-HTTPS`: `https://example.org/dns-query/my-client` - * `DNS-over-TLS`: `tls://my-client.example.org` (requires a [Wildcard certificate](https://en.wikipedia.org/wiki/Wildcard_certificate)) - * `DNS-over-QUIC`: `quic://my-client.example.org` (requires a [Wildcard certificate](https://en.wikipedia.org/wiki/Wildcard_certificate)) +1. **ClientIDs.** Special identifiers that can be used with some encrypted DNS + protocols. [See below](#clientid). - Note that the certificate for TLS and QUIC client IDs must be valid **both** - for `*.example.org` **and** `example.org`. + #### ClientID + +ClientIDs are identifiers that can be used with the following DNS protocols: +DNS-over-HTTPS, DNS-over-TLS, and DNS-over-QUIC. To use this identifier, +clients should perform queries using a special domain name. For example: + + * AdGuard Home has the domain name `example.org`. + + * In AdGuard Home you add a persistent client with the ClientID `my-client`. + + * On the client device you can now configure: + + * **DNS-over-HTTPS:** `https://example.org/dns-query/my-client`; + * **DNS-over-TLS:** `tls://my-client.example.org` (requires a [wildcard + certificate][wild]); + * **DNS-over-QUIC:** `quic://my-client.example.org` (requires a [wildcard + certificate][wild]). + +Note that the TLS certificate must be valid **both** for `*.example.org` **and** +`example.org`. + +[wild]: https://en.wikipedia.org/wiki/Wildcard_certificate -### Settings + ### Settings -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 +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) -## Configuring blocking per-client + + +## Per-Client Blocking 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 +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). + + ### `client` rules + +The first one is using the `client` modifier. This way you can limit the rule +to a particular 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` + * `@@||*^$client=127.0.0.1`: Unblock everything for localhost. -You can find more examples in [the article](Hosts-Blocklists#client) about -blocking rules syntax. + * `||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. -**`$ctag` rules** + * `||example.org^$client=192.168.0.0/24`: Block `example.org` for all clients + with the IP addresses in the range `192.168.0.0-192.168.0.255`. -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: +You can find more `client` examples in the [article](Hosts-Blocklists#client) +about the filtering rules syntax. -* `||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` + + + ### `ctag` rules + +The second way is to use another modifier called `ctag`. When you create a new +client, tags can be assigned to it. These tags can then be used in the +filtering rules. + +Examples: + + * `||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`. + +You can find more `ctag` examples as well as the full list of tags in the +[article](Hosts-Blocklists#ctag) about the filtering rules syntax.