diff --git a/Clients.md b/Clients.md new file mode 100644 index 0000000..ddbbcdb --- /dev/null +++ b/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) + +## Friendly names + +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. + +## 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. + +![](images/new-client.png) + +### 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 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` + +### 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 +of upstream DNS servers to be used for this client. + +![](images/client-settings.png) + +## Configuring blocking per-client + +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` diff --git a/Comparison.md b/Comparison.md index 04149b9..e33996e 100644 --- a/Comparison.md +++ b/Comparison.md @@ -1,5 +1,5 @@ -## Comparing AdGuard Home to other solutions +## Comparing AdGuard Home to Other Solutions ### How is this different from public AdGuard DNS servers? diff --git a/Configuration.md b/Configuration.md index e3370c1..886f6c5 100644 --- a/Configuration.md +++ b/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`. - - -## 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. - ## Configuration file diff --git a/DHCP.md b/DHCP.md index 60ca281..f75f167 100644 --- a/DHCP.md +++ b/DHCP.md @@ -1,4 +1,4 @@ - # *AdGuard Home* - DHCP Server + # AdGuard Home - DHCP Server * [Prerequisites](#prereq) * [Default Options](#default) diff --git a/DNSCrypt.md b/DNSCrypt.md index c0c1429..3eda8e2 100644 --- a/DNSCrypt.md +++ b/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) diff --git a/Docker.md b/Docker.md index fceef56..aa83125 100644 --- a/Docker.md +++ b/Docker.md @@ -1,4 +1,4 @@ -# AdGuard Home - Docker + # AdGuard Home - Docker  

diff --git a/Encryption.md b/Encryption.md index db307c3..e33e73c 100644 --- a/Encryption.md +++ b/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**: diff --git a/FAQ.md b/FAQ.md index 635a9e1..a678d45 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,4 +1,4 @@ -# AdGuard Home - FAQ + # AdGuard Home - FAQ ## Questions: diff --git a/Getting-Started.md b/Getting-Started.md index d631ff4..b4913b4 100644 --- a/Getting-Started.md +++ b/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. ## 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. diff --git a/Home.md b/Home.md index f1e4cf3..22fdf6f 100644 --- a/Home.md +++ b/Home.md @@ -1,4 +1,4 @@ -# AdGuard Home - Wiki + # AdGuard Home - Wiki  

@@ -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) -* [AdGuard Home Docker](Docker) -* [Configuration](Configuration) -* [Comparing AdGuard Home to other solutions](Comparison) -* [AdGuard Home as a DNS-over-HTTPS or DNS-over-TLS server](Encryption) -* [AdGuard Home as a DNSCrypt server](DNSCrypt) -* [AdGuard Home as a DHCP server](DHCP) -* [How to install and run AdGuard Home on Raspberry Pi](Raspberry-Pi) -* [How to install and run AdGuard Home on a Virtual Private Server](VPS) -* [OpenRC service-script](OpenRC) -* [How to write hosts blocklists](Hosts-Blocklists) + * [FAQ](FAQ) + * [How to Write Hosts Blocklists](Hosts-Blocklists) + * [Comparing AdGuard Home to Other Solutions](Comparison) +* Configuring AdGuard + * [Configuration](Configuration) + * [Configuring AdGuard Home Clients](Clients) + * [AdGuard Home as a DoH, DoT, or DoQ Server](Encryption) + * [AdGuard Home as a DNSCrypt Server](DNSCrypt) + * [AdGuard Home as a DHCP Server](DHCP) +* Installing AdGuard Home + * [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) diff --git a/Hosts-Blocklists.md b/Hosts-Blocklists.md index c016620..c145443 100644 --- a/Hosts-Blocklists.md +++ b/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) diff --git a/OpenRC.md b/OpenRC.md deleted file mode 100644 index c932b8e..0000000 --- a/OpenRC.md +++ /dev/null @@ -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 " - # - - 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 diff --git a/Raspberry-Pi.md b/Raspberry-Pi.md index 950d801..b8a5090 100644 --- a/Raspberry-Pi.md +++ b/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 -tar xvf AdGuardHome_linux_arm.tar.gz +wget https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv6.tar.gz +tar xvf AdGuardHome_linux_armv6.tar.gz ``` It will unpack into a new directory called `AdGuardHome`. diff --git a/VPS.md b/VPS.md index 95e615b..2b5eb2f 100644 --- a/VPS.md +++ b/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. diff --git a/Verify-Releases.md b/Verify-Releases.md index 9a430a0..88b9fdc 100644 --- a/Verify-Releases.md +++ b/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. diff --git a/__Sidebar.md b/__Sidebar.md index 8e770f5..3200877 100644 --- a/__Sidebar.md +++ b/__Sidebar.md @@ -1,15 +1,17 @@ ## Guides * [Getting Started](Getting-Started) -* [FAQ](FAQ) -* [Docker](Docker) -* [Configuration](Configuration) -* [Comparing AdGuard Home to other solutions](Comparison) -* [AdGuard Home as a DNS-over-HTTPS or DNS-over-TLS server](Encryption) -* [AdGuard Home as a DNSCrypt server](DNSCrypt) -* [AdGuard Home as a DHCP server](DHCP) -* [How to install and run AdGuard Home on Raspberry Pi](Raspberry-Pi) -* [How to install and run AdGuard Home on a Virtual Private Server](VPS) -* [OpenRC service-script](OpenRC) -* [How to write hosts blocklists](Hosts-Blocklists) + * [FAQ](FAQ) + * [How to Write Hosts Blocklists](Hosts-Blocklists) + * [Comparing AdGuard Home to Other Solutions](Comparison) +* Configuring AdGuard + * [Configuration](Configuration) + * [Configuring AdGuard Home Clients](Clients) + * [AdGuard Home as a DoH, DoT, or DoQ Server](Encryption) + * [AdGuard Home as a DNSCrypt Server](DNSCrypt) + * [AdGuard Home as a DHCP Server](DHCP) +* Installing AdGuard Home + * [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) diff --git a/autoupdate-available.png b/images/autoupdate-available.png similarity index 100% rename from autoupdate-available.png rename to images/autoupdate-available.png diff --git a/images/client-settings.png b/images/client-settings.png new file mode 100644 index 0000000..2689525 Binary files /dev/null and b/images/client-settings.png differ diff --git a/images/new-client.png b/images/new-client.png new file mode 100644 index 0000000..4e586d5 Binary files /dev/null and b/images/new-client.png differ diff --git a/top-clients-names.png b/images/top-clients-names.png similarity index 100% rename from top-clients-names.png rename to images/top-clients-names.png diff --git a/upstreams.png b/upstreams.png deleted file mode 100644 index 8099d48..0000000 Binary files a/upstreams.png and /dev/null differ