mirrors/AdGuardHome
1
0
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2024-11-27 17:26:39 +03:00
Code Issues Projects Releases Packages Wiki Activity

Pull request: Clients: imp 

Updates AdguardTeam/AdGuardHome#4244.

Squashed commit of the following:

commit 9741b3dd11d7ed96b8b0db7b7e7b1af0d02c21e7
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Feb 10 13:45:10 2022 +0300

    Clients: imp hosts info

commit 58871afe17a79f203a1d8538cd0660a8932a8504
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Wed Feb 9 14:32:05 2022 +0300

    Clients: fmt, imp text

commit 8b81c453d3a57716eac8d09a4f2c55b29b706836
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Tue Feb 8 21:29:50 2022 +0300

    Clients: imp
Ainar Garipov 2022-02-10 15:35:28 +03:00
parent 9d5dda92bd
commit bb57b99a26
1 changed files with 104 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

157
Clients.md

@ -1,76 +1,99 @@
# Configuring AdGuard Home Clients # AdGuard Home - Configuring Clients
AdGuard Home allows flexible configuration for the devices that are connected to it. 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 On a basic level, you may just want to be able to distinguish them and see
names instead of naked IP addresses. Additionally, AdGuard Home allows you applying friendly names instead of naked IP addresses. Additionally, AdGuard Home allows
different rules depending on the client. you applying different rules depending on the client.
* [Friendly names](#friendlynames) * [Friendly Names](#friendlynames)
* [Creating a new client](#newclient) * [Persistent Clients](#newclient)
* [Identifying clients](#idclient) * [Identifying clients](#idclient)
* [Settings](#clientsettings) * [Settings](#clientsettings)
* [Configuring filtering per-client](#perclientblocking) * [Per-Client Blocking](#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. ## <a href="#friendlynames"id="friendlynames" name="friendlynames">Friendly Names</a>
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: 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. 1. Inspects the hosts files (for example, `/etc/hosts` on Unix systems) and
2. Makes a reverse DNS lookup. uses hostnames found there to identify clients.
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, 1. Makes reverse DNS lookups.
then editing the hosts file may be the easiest way to achieve this.
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) ![](images/top-clients-names.png)
Note, that restarting AdGuard Home may be needed if you want to see the [whois]: https://en.wikipedia.org/wiki/WHOIS
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" ## <a href="#newclient" id="newclient" name="newclient">Persistent Clients</a>
and click "Add client" there.
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) ![](images/new-client.png)
### <a id="idclient" href="#idclient">Identifying clients</a>
### <a href="#idclient" id="idclient" name="idclient">Identifying clients</a>
First of all, you need to decide how you would like to identify the client. First of all, you need to decide how you would like to identify the client.
There are several options to do this. 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. 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 range of IP addresses (in the example it is `192.168.0.*`) to the same
client. client.
3. **MAC address**. Using MAC as a client identifier is only possible when
AdGuard Home works as a [DHCP server](DHCP). 1. **MAC address.** Using MAC as a client identifier is **only** possible when
4. **Client ID** *(added in v0.105)*. This method is supposed to be used for AdGuard Home works as the network's [DHCP server](DHCP).
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 1. **ClientIDs.** Special identifiers that can be used with some encrypted DNS
example: protocols. [See below](#clientid).
#### <a href="#clientid" id="clientid" name="clientid">ClientID</a>
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`. * AdGuard Home has the domain name `example.org`.
* In AdGuard Home you add a client with the client ID `my-client`.
* In AdGuard Home you add a persistent client with the ClientID `my-client`.
* On the client device you can now configure: * On the client device you can now configure:
* `DNS-over-HTTPS`: `https://example.org/dns-query/my-client` * **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-TLS:** `tls://my-client.example.org` (requires a [wildcard
* `DNS-over-QUIC`: `quic://my-client.example.org` (requires a [Wildcard certificate](https://en.wikipedia.org/wiki/Wildcard_certificate)) certificate][wild]);
* **DNS-over-QUIC:** `quic://my-client.example.org` (requires a [wildcard
certificate][wild]).
Note that the certificate for TLS and QUIC client IDs must be valid **both** Note that the TLS certificate must be valid **both** for `*.example.org` **and**
for `*.example.org` **and** `example.org`. `example.org`.
[wild]: https://en.wikipedia.org/wiki/Wildcard_certificate
### <a id="clientsettings" href="#clientsettings">Settings</a> ### <a href="#clientsettings" id="clientsettings" name="clientsettings">Settings</a>
Each client can be configured individually. You may choose what to block, what 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 settings should be used, or you could even configure a completely different set
@ -78,36 +101,50 @@ of upstream DNS servers to be used for this client.
![](images/client-settings.png) ![](images/client-settings.png)
## <a id="perclientblocking" href="#perclientblocking">Configuring blocking per-client</a>
## <a href="#perclientblocking" id="perclientblocking" name="perclientblocking">Per-Client Blocking</a>
There are two ways of how you can configure blocking on the per-client basis. 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". 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: Examples:
* `@@||*^$client=127.0.0.1` — unblock everything for localhost * `@@||*^$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 * `||example.org^$client='Frank\'s laptop'`: Block `example.org` for the
blocking rules syntax. 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 You can find more `client` examples in the [article](Hosts-Blocklists#client)
a new client, special "tags" can be assigned to it. These tags can then about the filtering rules syntax.
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 ### `ctag` rules
except those tagged as `device_phone`
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.