mirror of
https://github.com/AdguardTeam/AdGuardHome.git
synced 2024-11-23 21:45:46 +03:00
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
parent
9d5dda92bd
commit
bb57b99a26
1 changed files with 104 additions and 67 deletions
171
Clients.md
171
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)
|
||||
|
||||
## <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:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Note, that restarting AdGuard Home may be needed if you want to see the
|
||||
change immediately.
|
||||
[whois]: https://en.wikipedia.org/wiki/WHOIS
|
||||
|
||||
## <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.
|
||||
|
||||
## <a href="#newclient" id="newclient" name="newclient">Persistent Clients</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 the “Settings → Clients
|
||||
settings” page and click the "Add client" button there.
|
||||
|
||||
|
||||
|
||||
### <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.
|
||||
|
||||
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`.
|
||||
#### <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`.
|
||||
|
||||
* 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
|
||||
|
||||
|
||||
|
||||
### <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
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## <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.
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue