Pull request: all: imp upstream docs, fix stuff
Merge in DNS/adguard-home-wiki from 3307-imp-upstream-doc to master
Squashed commit of the following:
commit e2b6ac174454dc20cd5de634d641e20cfea8293b
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date: Mon Jul 26 17:49:06 2021 +0300
Configuration: add href
commit 3dc4c4d7a00150208a4361043572ad414c49f48c
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date: Mon Jul 26 17:29:35 2021 +0300
all: imp upstream docs, fix stuff
Ainar Garipov
parent
4ed75f2366
commit
ab8edf0458
109
Configuration.md
109
Configuration.md
|
|
@ -1,4 +1,4 @@
|
||||||
# AdGuard Home - Configuration
|
# AdGuard Home - Configuration
|
||||||
|
|
||||||
Most of these settings can be changed via the web-based admin interface.
|
Most of these settings can be changed via the web-based admin interface.
|
||||||
However, we decided to list them all here just in case.
|
However, we decided to list them all here just in case.
|
||||||
|
|
@ -8,13 +8,16 @@ However, we decided to list them all here just in case.
|
||||||
* [Specifying Upstreams For Domains](#upstreams-for-domains)
|
* [Specifying Upstreams For Domains](#upstreams-for-domains)
|
||||||
* [Loading Upstreams From File](#upstreams-from-file)
|
* [Loading Upstreams From File](#upstreams-from-file)
|
||||||
* [Specifying Upstreams For Reverse DNS](#upstreams-for-rdns)
|
* [Specifying Upstreams For Reverse DNS](#upstreams-for-rdns)
|
||||||
|
* [Private Addresses](#rdns-private)
|
||||||
|
* [Public Addresses](#rdns-public)
|
||||||
|
* [Client Look-Ups](#rdns-clients)
|
||||||
* [Configuration File](#configuration-file)
|
* [Configuration File](#configuration-file)
|
||||||
* [Reset Web Password](#password-reset)
|
* [Reset Web Password](#password-reset)
|
||||||
* [Profiling With Pprof](#pprof)
|
* [Profiling With Pprof](#pprof)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#command-line" id="command-line" name="command-line">Command-line Arguments</a>
|
## <a href="#command-line" id="command-line" name="command-line">Command-line Arguments</a>
|
||||||
|
|
||||||
Here is a list of all available command-line arguments.
|
Here is a list of all available command-line arguments.
|
||||||
|
|
||||||
|
|
@ -56,7 +59,7 @@ functionality in the service as well.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#upstreams" id="upstreams" name="upstreams">Configuring Upstreams</a>
|
## <a href="#upstreams" id="upstreams" name="upstreams">Configuring Upstreams</a>
|
||||||
|
|
||||||
AdGuard Home is basically a DNS proxy that sends your DNS queries to the
|
AdGuard Home is basically a DNS proxy that sends your DNS queries to the
|
||||||
upstream servers. You can specify multiple upstream servers in AdGuard Home
|
upstream servers. You can specify multiple upstream servers in AdGuard Home
|
||||||
|
|
@ -79,7 +82,7 @@ Examples:
|
||||||
|
|
||||||
* `[/example.local/]1.1.1.1`: DNS upstream for specific domains, see below.
|
* `[/example.local/]1.1.1.1`: DNS upstream for specific domains, see below.
|
||||||
|
|
||||||
### <a hfer="#upstreams-for-domains" id="upstreams-for-domains" name="upstreams-for-domains">Specifying Upstreams For Domains</a>
|
### <a hfer="#upstreams-for-domains" id="upstreams-for-domains" name="upstreams-for-domains">Specifying Upstreams For Domains</a>
|
||||||
|
|
||||||
You can specify upstreams that will be used for specific domains using the
|
You can specify upstreams that will be used for specific domains using the
|
||||||
dnsmasq-like syntax (see the documentation for the option `--server`
|
dnsmasq-like syntax (see the documentation for the option `--server`
|
||||||
|
|
@ -126,7 +129,7 @@ a configuration like this:
|
||||||
sends queries for `*.host.com` to `1.2.3.4` except for queries for
|
sends queries for `*.host.com` to `1.2.3.4` except for queries for
|
||||||
`*.www.host.com`, which are sent to `6.7.8.9`, which is the default upstream.
|
`*.www.host.com`, which are sent to `6.7.8.9`, which is the default upstream.
|
||||||
|
|
||||||
#### Examples
|
#### Examples
|
||||||
|
|
||||||
* A configuration like:
|
* A configuration like:
|
||||||
|
|
||||||
|
|
@ -149,7 +152,7 @@ sends queries for `*.host.com` to `1.2.3.4` except for queries for
|
||||||
sends queries for `*.host.com` to `1.1.1.1:53` except for `*.maps.host.com`
|
sends queries for `*.host.com` to `1.1.1.1:53` except for `*.maps.host.com`
|
||||||
which are sent to `8.8.8.8:53` along with all other queries.
|
which are sent to `8.8.8.8:53` along with all other queries.
|
||||||
|
|
||||||
### <a href="#upstreams-from-file" id="upstreams-from-file" name="upstreams-from-file">Loading Upstreams From File</a>
|
### <a href="#upstreams-from-file" id="upstreams-from-file" name="upstreams-from-file">Loading Upstreams From File</a>
|
||||||
|
|
||||||
Using specific upstreams for some domains is a common way to accelerate internet
|
Using specific upstreams for some domains is a common way to accelerate internet
|
||||||
in China. For an example, see https://github.com/felixonmars/dnsmasq-china-list
|
in China. For an example, see https://github.com/felixonmars/dnsmasq-china-list
|
||||||
|
|
@ -166,48 +169,86 @@ may want to load them from a separate file instead of setting all upstreams in
|
||||||
AdGuard Home settings. To do that, simply specify the path to a file with your
|
AdGuard Home settings. To do that, simply specify the path to a file with your
|
||||||
list in the `upstream_dns_file` field of `AdGuardHome.yaml`.
|
list in the `upstream_dns_file` field of `AdGuardHome.yaml`.
|
||||||
|
|
||||||
### <a id="upstreams-for-rdns">Specifying Upstreams For Reverse DNS</a>
|
### <a href="#upstreams-for-rdns" id="upstreams-for-rdns" name="upstreams-for-rdns">Specifying Upstreams For Reverse DNS</a>
|
||||||
|
|
||||||
AdGuard Home automatically gets the names of connected devices using reverse DNS
|
Using the domain-specific upstream notation, you can specify dedicated upstream
|
||||||
lookup (rDNS). It sends `PTR` requests with the IP addresses of clients to DNS
|
DNS servers for reverse DNS (rDNS) requests. If you want **all** your `PTR`
|
||||||
servers and uses the responses for “clients' human-friendly names”.
|
queries to be redirected to `192.168.8.8`:
|
||||||
|
|
||||||
Since **v0.106.0** you can enable and disable this feature with “Enable clients'
|
1. Enter the following into the “Upstream DNS servers” field on the “Settings
|
||||||
hostname resolution” setting in the “Upstream DNS servers” section or via the
|
→ DNS settings” page:
|
||||||
`resolve_clients` field in the configuration file.
|
|
||||||
|
|
||||||
Also since **v0.106.0** all the addresses from [private IP ranges][private-ip]
|
```none
|
||||||
are only resolved via appropriate local resolvers to avoid the leaks of clients'
|
[/in-addr.arpa/]192.168.8.8
|
||||||
information. But you can also set custom upstreams for it in the “Private DNS
|
[/ip6.arpa/]192.168.8.8
|
||||||
servers” field in the “Upstream DNS servers” section or via the
|
```
|
||||||
`local_ptr_upstreams` field in the configuration file. Note that the specified
|
|
||||||
upstreams are also used by DNS server to resolve `PTR` for the same IP range.
|
2. Enter the following into the “Private reverse DNS servers” field on the
|
||||||
|
same page below the previous field:
|
||||||
|
|
||||||
|
```none
|
||||||
|
192.168.8.8
|
||||||
|
```
|
||||||
|
|
||||||
|
There is no need to use the domain-specific notation here, unless you want
|
||||||
|
to redirect requests for different private ranges to different upstream
|
||||||
|
servers.
|
||||||
|
|
||||||
|
**NOTE:** All upstreams for private ranges **must** go to the “Private reverse
|
||||||
|
DNS servers” field **and not** the main “Upstream DNS servers” field. Entering
|
||||||
|
something like `[/192.in-addr.arpa/]192.168.8.8` into the main field will have
|
||||||
|
no effect.
|
||||||
|
|
||||||
|
Read below for more details.
|
||||||
|
|
||||||
|
#### <a href="#rdns-private" id="rdns-private" name="rdns-private">Private Addresses</a>
|
||||||
|
|
||||||
|
Since **v0.106.0** all the addresses from [private IP ranges][private-ip]
|
||||||
|
are only resolved via appropriate local resolvers to avoid leaks of clients'
|
||||||
|
information. By default, AdGuard Home tries to get the addresses of the default
|
||||||
|
resolvers from the OS. You can set custom upstreams for it in the “Private
|
||||||
|
reverse DNS servers” field in the “Upstream DNS servers” section or via the
|
||||||
|
`local_ptr_upstreams` field in the configuration file.
|
||||||
|
|
||||||
Since **v0.107.0** you can disable the usage of private reverse DNS upstream
|
Since **v0.107.0** you can disable the usage of private reverse DNS upstream
|
||||||
servers via the “Use private reverse DNS resolvers” checkbox in the “Upstream
|
servers via the “Use private reverse DNS resolvers” checkbox in the “Upstream
|
||||||
DNS servers” section or via the `use_private_ptr_resolvers` field in the
|
DNS servers” section or via the `use_private_ptr_resolvers` field in the
|
||||||
configuration file. If it is disabled, the unknown addresses from
|
configuration file. If it is disabled, the unknown addresses from locally
|
||||||
locally served networks won't be resolved at all.
|
served networks won't be resolved at all, and clients performing these queries
|
||||||
|
will receive `NXDOMAIN` responses.
|
||||||
|
|
||||||
But what if you want AdGuard Home to use another DNS server for a specific IP
|
#### <a href="#rdns-public" id="rdns-public" name="rdns-public">Public Addresses</a>
|
||||||
address range? You can do it using the same syntax as for general upstream
|
|
||||||
servers, for example:
|
If you want AdGuard Home to use another DNS server for a specific IP address
|
||||||
|
range, you can do it using the same syntax as for general upstream servers. For
|
||||||
|
example, if you add this to your “Upstream DNS servers” field:
|
||||||
|
|
||||||
```none
|
```none
|
||||||
[/128.in-addr.arpa/]192.168.8.8
|
[/200.in-addr.arpa/]192.168.7.7
|
||||||
```
|
```
|
||||||
|
|
||||||
This rule instructs AdGuard Home to use `192.168.8.8` DNS server for all rDNS
|
then AdGuard Home will use the `192.168.7.7` DNS server for all rDNS requests to
|
||||||
requests to resolve clients' IP addresses from the `128.0.0.0/8` network.
|
resolve clients' IP addresses from the `200.0.0.0/8` network.
|
||||||
|
|
||||||
Note that if you want to use that address for `PTR` queries for IP addresses
|
Note that if you want to use that address for `PTR` queries for IP addresses in
|
||||||
outside of the locally served network ranges, you should also add this to your
|
a locally served network range, for example `192.168.0.0/16`, you should add
|
||||||
main “Upstream DNS servers” field:
|
this to the “Private reverse DNS servers” field:
|
||||||
|
|
||||||
```none
|
```none
|
||||||
[/in-addr.arpa/]192.168.8.8
|
[/168.192.in-addr.arpa/]192.168.7.7
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### <a href="#rdns-clients" id="rdns-clients" name="rdns-clients">Client Look-Ups</a>
|
||||||
|
|
||||||
|
AdGuard Home automatically gets the names of connected devices using reverse DNS
|
||||||
|
lookup (rDNS). It sends `PTR` requests with the IP addresses of clients to
|
||||||
|
appropriate DNS servers and uses the responses to enrich client information with
|
||||||
|
human-friendly names.
|
||||||
|
|
||||||
|
Since **v0.106.0** you can enable and disable this feature with “Enable clients'
|
||||||
|
hostname resolution” setting in the “Upstream DNS servers” section or via the
|
||||||
|
`resolve_clients` field in the configuration file.
|
||||||
|
|
||||||
[DNS Stamps]: https://dnscrypt.info/stamps/
|
[DNS Stamps]: https://dnscrypt.info/stamps/
|
||||||
[DNS-over-HTTPS]: https://en.wikipedia.org/wiki/DNS_over_HTTPS
|
[DNS-over-HTTPS]: https://en.wikipedia.org/wiki/DNS_over_HTTPS
|
||||||
[DNS-over-QUIC]: https://datatracker.ietf.org/doc/html/draft-ietf-dprive-dnsoquic-03
|
[DNS-over-QUIC]: https://datatracker.ietf.org/doc/html/draft-ietf-dprive-dnsoquic-03
|
||||||
|
|
@ -218,7 +259,7 @@ main “Upstream DNS servers” field:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#configuration-file" id="configuration-file" name="configuration-file">Configuration File</a>
|
## <a href="#configuration-file" id="configuration-file" name="configuration-file">Configuration File</a>
|
||||||
|
|
||||||
Upon the first execution, a file named `AdGuardHome.yaml` will be created, with default values written in it. You can modify the file while your AdGuard Home service is not running. Otherwise, any changes to the file will be lost because the running program will overwrite them.
|
Upon the first execution, a file named `AdGuardHome.yaml` will be created, with default values written in it. You can modify the file while your AdGuard Home service is not running. Otherwise, any changes to the file will be lost because the running program will overwrite them.
|
||||||
|
|
||||||
|
|
@ -407,7 +448,7 @@ Removing an entry from settings file will reset it to the default value. Deletin
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#password-reset" id="password-reset" name="password-reset">Reset Web Password</a>
|
## <a href="#password-reset" id="password-reset" name="password-reset">Reset Web Password</a>
|
||||||
|
|
||||||
AdGuard Home stores password as a BCrypt-encoded hash.
|
AdGuard Home stores password as a BCrypt-encoded hash.
|
||||||
|
|
||||||
|
|
@ -434,7 +475,7 @@ Now you'll be able to log in to Web interface using your new password.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#pprof" id="pprof" name="pprof">Profiling With Pprof</a>
|
## <a href="#pprof" id="pprof" name="pprof">Profiling With Pprof</a>
|
||||||
|
|
||||||
To enable pprof, set `debug_pprof: true` in yaml configuration file and then
|
To enable pprof, set `debug_pprof: true` in yaml configuration file and then
|
||||||
restart AdGuard Home. Now you can get profiling information with your browser,
|
restart AdGuard Home. Now you can get profiling information with your browser,
|
||||||
|
|
|
||||||
46
Docker.md
46
Docker.md
|
|
@ -2,23 +2,21 @@
|
||||||
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="https://cdn.adguard.com/public/Adguard/Common/adguard_home.svg" width="300px" alt="AdGuard Home" />
|
<img src="https://cdn.adguard.com/public/Adguard/Common/adguard_home.svg" width="300px" alt="AdGuard Home" />
|
||||||
</p>
|
</p>
|
||||||
<h3 align="center">Privacy protection center for you and your devices</h3>
|
<h3 align="center">Privacy protection center for you and your devices</h3>
|
||||||
<p align="center">
|
<p align="center">
|
||||||
Free and open source, powerful network-wide ads & trackers blocking DNS server.
|
Free and open source, powerful network-wide ads & trackers blocking DNS server.
|
||||||
</p>
|
</p>
|
||||||
|
<br/>
|
||||||
<br />
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="https://cdn.adguard.com/public/Adguard/Common/adguard_home.gif" width="800" />
|
<img src="https://cdn.adguard.com/public/Adguard/Common/adguard_home.gif" width="800"/>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
* [Introduction](#introduction)
|
* [Introduction](#introduction)
|
||||||
* [Quick Start](#quickstart)
|
* [Quick Start](#quickstart)
|
||||||
* [Update To A Newer Version](#update)
|
* [Update To A Newer Version](#update)
|
||||||
* [Running Dev Builds](#unstable)
|
* [Running Development Builds](#unstable)
|
||||||
* [Additional Configuration](#configuration)
|
* [Additional Configuration](#configuration)
|
||||||
* [DHCP Server](#dhcp)
|
* [DHCP Server](#dhcp)
|
||||||
* [`resolved`](#resolved-daemon)
|
* [`resolved`](#resolved-daemon)
|
||||||
|
|
@ -38,7 +36,7 @@ repository][agh].
|
||||||
|
|
||||||
## <a href="#quickstart" id="quickstart" name="quickstart">Quick Start</a>
|
## <a href="#quickstart" id="quickstart" name="quickstart">Quick Start</a>
|
||||||
|
|
||||||
### Pull the Docker image
|
### Pull the Docker image
|
||||||
|
|
||||||
This command will pull the latest stable version:
|
This command will pull the latest stable version:
|
||||||
|
|
||||||
|
|
@ -46,14 +44,14 @@ This command will pull the latest stable version:
|
||||||
docker pull adguard/adguardhome
|
docker pull adguard/adguardhome
|
||||||
```
|
```
|
||||||
|
|
||||||
### Create directories for persistent configuration and data
|
### Create directories for persistent configuration and data
|
||||||
|
|
||||||
The image exposes two volumes for data and configuration persistence. You
|
The image exposes two volumes for data and configuration persistence. You
|
||||||
should create a **data** directory on a suitable volume on your host system,
|
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`.
|
on your host system, e.g. `/my/own/confdir`.
|
||||||
|
|
||||||
### Create and run the container
|
### Create and run the container
|
||||||
|
|
||||||
Use the following command to create a new container and run AdGuard Home:
|
Use the following command to create a new container and run AdGuard Home:
|
||||||
|
|
||||||
|
|
@ -76,7 +74,7 @@ your AdGuard Home service.
|
||||||
|
|
||||||
Don't forget to use your own **data** and **config** directories!
|
Don't forget to use your own **data** and **config** directories!
|
||||||
|
|
||||||
Ports mappings you may need:
|
Port mappings you might need:
|
||||||
|
|
||||||
* `-p 53:53/tcp -p 53:53/udp`: plain DNS.
|
* `-p 53:53/tcp -p 53:53/udp`: plain DNS.
|
||||||
|
|
||||||
|
|
@ -97,7 +95,7 @@ Ports mappings you may need:
|
||||||
* `-p 5443:5443/tcp -p 5443:5443/udp`: add if you are going to run AdGuard
|
* `-p 5443:5443/tcp -p 5443:5443/udp`: add if you are going to run AdGuard
|
||||||
Home as a [DNSCrypt] server.
|
Home as a [DNSCrypt] server.
|
||||||
|
|
||||||
### Control the container
|
### Control the container
|
||||||
|
|
||||||
* Start: `docker start adguardhome`
|
* Start: `docker start adguardhome`
|
||||||
|
|
||||||
|
|
@ -131,7 +129,7 @@ Ports mappings you may need:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#unstable" id="unstable" name="unstable">Running Dev Builds</a>
|
## <a href="#unstable" id="unstable" name="unstable">Running Development Builds</a>
|
||||||
|
|
||||||
If you want to be on the bleeding edge, you might want to run the image from the
|
If you want to be on the bleeding edge, you might want to run the image from the
|
||||||
`edge` or `beta` tags. In order to use it, simply replace `adguard/adguardhome`
|
`edge` or `beta` tags. In order to use it, simply replace `adguard/adguardhome`
|
||||||
|
|
@ -146,20 +144,20 @@ docker pull adguard/adguardhome:edge
|
||||||
|
|
||||||
## <a href="#configuration" id="configuration" name="configuration">Additional Configuration</a>
|
## <a href="#configuration" id="configuration" name="configuration">Additional Configuration</a>
|
||||||
|
|
||||||
Upon the first run, a file named `AdGuardHome.yaml` will be created, with
|
Upon the first run, a file with the default values named `AdGuardHome.yaml` is
|
||||||
default values written into it. You can modify the file while your AdGuard Home
|
created. You can modify the file while your AdGuard Home container is not
|
||||||
container is not running. Otherwise, any changes to the file will be lost
|
running. Otherwise, any changes to the file will be lost because the running
|
||||||
because the running program will overwrite them.
|
program will overwrite them.
|
||||||
|
|
||||||
Settings are stored in [YAML], possible parameters that you can configure are
|
The settings are stored in the [YAML] format. The documentation describing all
|
||||||
listed on [this page][conf].
|
configurable parameters and their values is available on [this page][conf].
|
||||||
|
|
||||||
[YAML]: https://yaml.org
|
[YAML]: https://yaml.org
|
||||||
[conf]: https://github.com/AdguardTeam/Adguardhome/wiki/Configuration
|
[conf]: https://github.com/AdguardTeam/Adguardhome/wiki/Configuration
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#dhcp" id="dhcp" name="dhcp">DHCP Server</a>
|
## <a href="#dhcp" id="dhcp" name="dhcp">DHCP Server</a>
|
||||||
|
|
||||||
If you want to use AdGuardHome's DHCP server, you should pass `--network host`
|
If you want to use AdGuardHome's DHCP server, you should pass `--network host`
|
||||||
argument when creating the container:
|
argument when creating the container:
|
||||||
|
|
@ -174,13 +172,13 @@ this case.
|
||||||
|
|
||||||
A note from the Docker documentation:
|
A note from the Docker documentation:
|
||||||
|
|
||||||
> The host networking driver only works on Linux hosts, and is not supported on
|
> The host networking driver only works on Linux hosts, and is not supported on
|
||||||
> Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows
|
> Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows
|
||||||
> Server.
|
> Server.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## <a href="#resolved-daemon" id="resolved-daemon" name="resolved-daemon">`resolved`</a>
|
## <a href="#resolved-daemon" id="resolved-daemon" name="resolved-daemon">`resolved`</a>
|
||||||
|
|
||||||
If you try to run AdGuardHome on a system where the `resolved` daemon is
|
If you try to run AdGuardHome on a system where the `resolved` daemon is
|
||||||
started, docker will fail to bind on port 53, because `resolved` daemon is
|
started, docker will fail to bind on port 53, because `resolved` daemon is
|
||||||
|
|
|
||||||
|
|
@ -26,7 +26,7 @@ There are three different approaches to writing hosts blocklists:
|
||||||
This way blocklists are compatible with browser ad blockers.
|
This way blocklists are compatible with browser ad blockers.
|
||||||
|
|
||||||
* [`/etc/hosts` syntax](#etc-hosts): the old, tried-and-true approach that
|
* [`/etc/hosts` syntax](#etc-hosts): the old, tried-and-true approach that
|
||||||
uses the same syntax the one operating systems use for their hosts files.
|
uses the same syntax that operating systems do for their hosts files.
|
||||||
|
|
||||||
* [Domains-only syntax](#domains-only): a simple list of domain names.
|
* [Domains-only syntax](#domains-only): a simple list of domain names.
|
||||||
|
|
||||||
|
|
@ -34,7 +34,7 @@ If you are creating a blocklist for AdGuard Home, we recommend using the
|
||||||
[Adblock-style syntax](#adblock-style). It has a couple of important advantages
|
[Adblock-style syntax](#adblock-style). It has a couple of important advantages
|
||||||
over the old-style syntax:
|
over the old-style syntax:
|
||||||
|
|
||||||
* **Blocklists size.** Using pattern-matching allows you to have a single
|
* **Blocklists size.** Using pattern matching allows you to have a single
|
||||||
rule instead of hundreds of `/etc/hosts` entries.
|
rule instead of hundreds of `/etc/hosts` entries.
|
||||||
|
|
||||||
* **Compatibility.** Your blocklist will be compatible with browser ad
|
* **Compatibility.** Your blocklist will be compatible with browser ad
|
||||||
|
|
@ -72,7 +72,14 @@ work. -->
|
||||||
subdomains. `www.example.org` remains allowed.
|
subdomains. `www.example.org` remains allowed.
|
||||||
|
|
||||||
Using the unspecified IP address (`0.0.0.0`) or a local address (`127.0.0.1`
|
Using the unspecified IP address (`0.0.0.0`) or a local address (`127.0.0.1`
|
||||||
and alike) with an address is basically the same as blocking this address.
|
and alike) for a host is basically the same as blocking that host.
|
||||||
|
|
||||||
|
```none
|
||||||
|
# Returns the IP address 1.2.3.4 for exmaple.org.
|
||||||
|
1.2.3.4 example.org
|
||||||
|
# Blocks example.com by responding with 0.0.0.0.
|
||||||
|
0.0.0.0 example.com
|
||||||
|
```
|
||||||
|
|
||||||
* `example.org`: a simple domain rule. Blocks `example.org` domain but
|
* `example.org`: a simple domain rule. Blocks `example.org` domain but
|
||||||
**not** its subdomains. `www.example.org` remains allowed.
|
**not** its subdomains. `www.example.org` remains allowed.
|
||||||
|
|
@ -103,7 +110,7 @@ modifiers = [modifier0, modifier1[, ...[, modifierN]]]
|
||||||
* `modifiers`: parameters that clarify the rule. They may limit the scope of
|
* `modifiers`: parameters that clarify the rule. They may limit the scope of
|
||||||
the rule or even completely change the way it works.
|
the rule or even completely change the way it works.
|
||||||
|
|
||||||
### <a href="#special-characters" id="special-characters" name="special-characters">Special Characters</a>
|
### <a href="#special-characters" id="special-characters" name="special-characters">Special Characters</a>
|
||||||
|
|
||||||
* `*`: the wildcard character. It is used to represent any set of characters.
|
* `*`: the wildcard character. It is used to represent any set of characters.
|
||||||
This can also be an empty string or a string of any length.
|
This can also be an empty string or a string of any length.
|
||||||
|
|
@ -121,7 +128,7 @@ modifiers = [modifier0, modifier1[, ...[, modifierN]]]
|
||||||
`ample.org|` corresponds to `example.org` but not to `example.org.com`.
|
`ample.org|` corresponds to `example.org` but not to `example.org.com`.
|
||||||
`|example` corresponds to `example.org` but not to `test.example`.
|
`|example` corresponds to `example.org` but not to `test.example`.
|
||||||
|
|
||||||
### <a href="#regular-expressions" id="regular-expressions" name="regular-expressions">Regular Expressions</a>
|
### <a href="#regular-expressions" id="regular-expressions" name="regular-expressions">Regular Expressions</a>
|
||||||
|
|
||||||
If you want even more flexibility in making rules, you can use [regular
|
If you want even more flexibility in making rules, you can use [regular
|
||||||
expressions][regexp] instead of the default simplified matching syntax. If you
|
expressions][regexp] instead of the default simplified matching syntax. If you
|
||||||
|
|
@ -138,7 +145,7 @@ pattern = "/" regexp "/"
|
||||||
* `@@/example.*/$important` will unblock hosts matching the `example.*` regexp.
|
* `@@/example.*/$important` will unblock hosts matching the `example.*` regexp.
|
||||||
Note that this rule also implies the `important` modifier.
|
Note that this rule also implies the `important` modifier.
|
||||||
|
|
||||||
### <a href="#comments" id="comments" name="comments">Comments</a>
|
### <a href="#comments" id="comments" name="comments">Comments</a>
|
||||||
|
|
||||||
Any line that starts with an exclamation mark or a hash sign is a comment and it
|
Any line that starts with an exclamation mark or a hash sign is a comment and it
|
||||||
will be ignored by the filtering engine. Comments are usually placed above
|
will be ignored by the filtering engine. Comments are usually placed above
|
||||||
|
|
@ -151,7 +158,7 @@ rules and used to describe what a rule does.
|
||||||
# This is also a comment.
|
# This is also a comment.
|
||||||
```
|
```
|
||||||
|
|
||||||
### <a href="#modifiers" id="modifiers" name="modifiers">Rule Modifiers</a>
|
### <a href="#modifiers" id="modifiers" name="modifiers">Rule Modifiers</a>
|
||||||
|
|
||||||
You can change the behavior of a rule by adding modifiers. Modifiers must be
|
You can change the behavior of a rule by adding modifiers. Modifiers must be
|
||||||
located at the end of the rule after the `$` character and be separated by
|
located at the end of the rule after the `$` character and be separated by
|
||||||
|
|
@ -185,7 +192,7 @@ rule **must be ignored**. This way we avoid false-positives when people are
|
||||||
trying to use unmodified browser ad blockers' filter lists like EasyList or
|
trying to use unmodified browser ad blockers' filter lists like EasyList or
|
||||||
EasyPrivacy.
|
EasyPrivacy.
|
||||||
|
|
||||||
#### <a href="#client" id="client" name="client">`client`</a>
|
#### <a href="#client" id="client" name="client">`client`</a>
|
||||||
|
|
||||||
The `client` modifier allows specifying clients this rule will be working for.
|
The `client` modifier allows specifying clients this rule will be working for.
|
||||||
It accepts client names (**not** ClientIDs), IP addresses, or CIDR ranges.
|
It accepts client names (**not** ClientIDs), IP addresses, or CIDR ranges.
|
||||||
|
|
@ -231,7 +238,7 @@ quotes.
|
||||||
* `||example.org^$client=192.168.0.0/24`: block `example.org` for all clients
|
* `||example.org^$client=192.168.0.0/24`: block `example.org` for all clients
|
||||||
with IP addresses in the range from `192.168.0.0` to `192.168.0.255`.
|
with IP addresses in the range from `192.168.0.0` to `192.168.0.255`.
|
||||||
|
|
||||||
#### <a href="#denyallow" id="denyallow" name="denyallow">`denyallow`</a>
|
#### <a href="#denyallow" id="denyallow" name="denyallow">`denyallow`</a>
|
||||||
|
|
||||||
Available since **v0.106.0**.
|
Available since **v0.106.0**.
|
||||||
|
|
||||||
|
|
@ -275,7 +282,7 @@ how to solve this with `denyallow`:
|
||||||
* `||example.org^$denyallow=sub.example.org`. block `example.org` and
|
* `||example.org^$denyallow=sub.example.org`. block `example.org` and
|
||||||
`*.example.org` but don't block `sub.example.org`.
|
`*.example.org` but don't block `sub.example.org`.
|
||||||
|
|
||||||
#### <a href="#dnstype" id="dnstype" name="dnstype">`dnstype`</a>
|
#### <a href="#dnstype" id="dnstype" name="dnstype">`dnstype`</a>
|
||||||
|
|
||||||
Available since **v0.105.0**.
|
Available since **v0.105.0**.
|
||||||
|
|
||||||
|
|
@ -312,7 +319,7 @@ $dnstype=value2
|
||||||
* `||example.org^$dnstype=~A|~CNAME`: only allow `A` and `CNAME` DNS queries for
|
* `||example.org^$dnstype=~A|~CNAME`: only allow `A` and `CNAME` DNS queries for
|
||||||
`example.org`, block out the rest.
|
`example.org`, block out the rest.
|
||||||
|
|
||||||
#### <a href="#dnsrewrite" id="dnsrewrite" name="dnsrewrite">`dnsrewrite`</a>
|
#### <a href="#dnsrewrite" id="dnsrewrite" name="dnsrewrite">`dnsrewrite`</a>
|
||||||
|
|
||||||
Available since **v0.105.0**.
|
Available since **v0.105.0**.
|
||||||
|
|
||||||
|
|
@ -429,7 +436,7 @@ Exception rules remove one or all rules:
|
||||||
* `@@||example.com^$dnsrewrite=1.2.3.4` removes the DNS rewrite rule that adds
|
* `@@||example.com^$dnsrewrite=1.2.3.4` removes the DNS rewrite rule that adds
|
||||||
an `A` record with the value `1.2.3.4`.
|
an `A` record with the value `1.2.3.4`.
|
||||||
|
|
||||||
#### <a href="#important" id="important" name="important">`important`</a>
|
#### <a href="#important" id="important" name="important">`important`</a>
|
||||||
|
|
||||||
The `important` modifier applied to a rule increases its priority over any
|
The `important` modifier applied to a rule increases its priority over any
|
||||||
other rule without the modifier. Even over basic exception rules.
|
other rule without the modifier. Even over basic exception rules.
|
||||||
|
|
@ -455,7 +462,7 @@ other rule without the modifier. Even over basic exception rules.
|
||||||
|
|
||||||
the exception rule also has the `important` modifier, so it will work.
|
the exception rule also has the `important` modifier, so it will work.
|
||||||
|
|
||||||
#### <a href="#badfilter" id="badfilter" name="badfilter">`badfilter`</a>
|
#### <a href="#badfilter" id="badfilter" name="badfilter">`badfilter`</a>
|
||||||
|
|
||||||
The rules with the `badfilter` modifier disable other basic rules to which they
|
The rules with the `badfilter` modifier disable other basic rules to which they
|
||||||
refer. It means that the text of the disabled rule should match the text of the
|
refer. It means that the text of the disabled rule should match the text of the
|
||||||
|
|
@ -471,7 +478,7 @@ refer. It means that the text of the disabled rule should match the text of the
|
||||||
`/etc/hosts`-style rules. `127.0.0.1 example.org$badfilter` will **not**
|
`/etc/hosts`-style rules. `127.0.0.1 example.org$badfilter` will **not**
|
||||||
disable the original `127.0.0.1 example.org` rule.
|
disable the original `127.0.0.1 example.org` rule.
|
||||||
|
|
||||||
#### <a href="#ctag" id="ctag" name="ctag">`ctag`</a>
|
#### <a href="#ctag" id="ctag" name="ctag">`ctag`</a>
|
||||||
|
|
||||||
The `ctag` modifier allows to block domains only for specific types of DNS
|
The `ctag` modifier allows to block domains only for specific types of DNS
|
||||||
client tags. You can assign tags to clients in the AdGuard Home UI. In the
|
client tags. You can assign tags to clients in the AdGuard Home UI. In the
|
||||||
|
|
@ -511,13 +518,13 @@ The list of allowed tags:
|
||||||
* `device_gameconsole`: game consoles.
|
* `device_gameconsole`: game consoles.
|
||||||
* `device_laptop`: laptops,
|
* `device_laptop`: laptops,
|
||||||
* `device_nas`: NAS (Network-attached Storages).
|
* `device_nas`: NAS (Network-attached Storages).
|
||||||
* `device_other`: other devices.
|
|
||||||
* `device_pc`: PCs.
|
* `device_pc`: PCs.
|
||||||
* `device_phone`: phones.
|
* `device_phone`: phones.
|
||||||
* `device_printer`: printers.
|
* `device_printer`: printers.
|
||||||
* `device_securityalarm`: security alarms.
|
* `device_securityalarm`: security alarms.
|
||||||
* `device_tablet`: tablets.
|
* `device_tablet`: tablets.
|
||||||
* `device_tv`: TVs.
|
* `device_tv`: TVs.
|
||||||
|
* `device_other`: other devices.
|
||||||
|
|
||||||
* By operating system:
|
* By operating system:
|
||||||
|
|
||||||
|
|
@ -525,14 +532,14 @@ The list of allowed tags:
|
||||||
* `os_ios`: iOS.
|
* `os_ios`: iOS.
|
||||||
* `os_linux`: Linux.
|
* `os_linux`: Linux.
|
||||||
* `os_macos`: macOS.
|
* `os_macos`: macOS.
|
||||||
* `os_other`: other OSes.
|
|
||||||
* `os_windows`: Windows.
|
* `os_windows`: Windows.
|
||||||
|
* `os_other`: other OSes.
|
||||||
|
|
||||||
* By user group:
|
* By user group:
|
||||||
|
|
||||||
* `user_admin`: administrators.
|
* `user_admin`: administrators.
|
||||||
* `user_child`: children.
|
|
||||||
* `user_regular`: regular users.
|
* `user_regular`: regular users.
|
||||||
|
* `user_child`: children.
|
||||||
|
|
||||||
[adb]: https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters
|
[adb]: https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters
|
||||||
[regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
|
[regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue