mirrors/AdGuardHome
1
0
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2024-11-21 20:45:33 +03:00
Code Issues Projects Releases Packages Wiki Activity

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 2021-07-26 19:27:08 +03:00
parent 4ed75f2366
commit ab8edf0458
3 changed files with 121 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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.
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)
* [Loading Upstreams From File](#upstreams-from-file)
* [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)
* [Reset Web Password](#password-reset)
* [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.
@ -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
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.
### <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
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
`*.www.host.com`, which are sent to `6.7.8.9`, which is the default upstream.
#### Examples
#### Examples
* 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`
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
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
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
lookup (rDNS). It sends `PTR` requests with the IP addresses of clients to DNS
servers and uses the responses for “clients' human-friendly names”.
Using the domain-specific upstream notation, you can specify dedicated upstream
DNS servers for reverse DNS (rDNS) requests. If you want **all** your `PTR`
queries to be redirected to `192.168.8.8`:
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.
1. Enter the following into the “Upstream DNS servers” field on the “Settings
→ DNS settings” page:
Also since **v0.106.0** all the addresses from [private IP ranges][private-ip]
are only resolved via appropriate local resolvers to avoid the leaks of clients'
information. But you can also set custom upstreams for it in the “Private DNS
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.
```none
[/in-addr.arpa/]192.168.8.8
[/ip6.arpa/]192.168.8.8
```
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
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
configuration file. If it is disabled, the unknown addresses from
locally served networks won't be resolved at all.
configuration file. If it is disabled, the unknown addresses from locally
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
address range? You can do it using the same syntax as for general upstream
servers, for example:
#### <a href="#rdns-public" id="rdns-public" name="rdns-public">Public Addresses</a>
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
[/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
requests to resolve clients' IP addresses from the `128.0.0.0/8` network.
then AdGuard Home will use the `192.168.7.7` DNS server for all rDNS requests to
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
outside of the locally served network ranges, you should also add this to your
main “Upstream DNS servers” field:
Note that if you want to use that address for `PTR` queries for IP addresses in
a locally served network range, for example `192.168.0.0/16`, you should add
this to the “Private reverse DNS servers” field:
```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-over-HTTPS]: https://en.wikipedia.org/wiki/DNS_over_HTTPS
[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.
@ -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.
@ -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
restart AdGuard Home. Now you can get profiling information with your browser,

46
Docker.md

@ -2,23 +2,21 @@
&nbsp;
<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>
<h3 align="center">Privacy protection center for you and your devices</h3>
<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>
<br />
<br/>
<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>
* [Introduction](#introduction)
* [Quick Start](#quickstart)
* [Update To A Newer Version](#update)
* [Running Dev Builds](#unstable)
* [Running Development Builds](#unstable)
* [Additional Configuration](#configuration)
* [DHCP Server](#dhcp)
* [`resolved`](#resolved-daemon)
@ -38,7 +36,7 @@ repository][agh].
## <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:
@ -46,14 +44,14 @@ This command will pull the latest stable version:
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
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
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:
@ -76,7 +74,7 @@ your AdGuard Home service.
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.
@ -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
Home as a [DNSCrypt] server.
### Control the container
### Control the container
* 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
`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>
Upon the first run, a file named `AdGuardHome.yaml` will be created, with
default values written into it. You can modify the file while your AdGuard Home
container is not running. Otherwise, any changes to the file will be lost
because the running program will overwrite them.
Upon the first run, a file with the default values named `AdGuardHome.yaml` is
created. You can modify the file while your AdGuard Home container is not
running. Otherwise, any changes to the file will be lost because the running
program will overwrite them.
Settings are stored in [YAML], possible parameters that you can configure are
listed on [this page][conf].
The settings are stored in the [YAML] format. The documentation describing all
configurable parameters and their values is available on [this page][conf].
[YAML]: https://yaml.org
[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`
argument when creating the container:
@ -174,13 +172,13 @@ this case.
A note from the Docker documentation:
> 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
> Server.
> 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
> 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
started, docker will fail to bind on port 53, because `resolved` daemon is

41
Hosts-Blocklists.md

@ -26,7 +26,7 @@ There are three different approaches to writing hosts blocklists:
This way blocklists are compatible with browser ad blockers.
* [`/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.
@ -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
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.
* **Compatibility.** Your blocklist will be compatible with browser ad
@ -72,7 +72,14 @@ work. -->
subdomains. `www.example.org` remains allowed.
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
**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
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.
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`.
`|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
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.
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
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.
```
### <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
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
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.
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
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**.
@ -275,7 +282,7 @@ how to solve this with `denyallow`:
* `||example.org^$denyallow=sub.example.org`. block `example.org` and
`*.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**.
@ -312,7 +319,7 @@ $dnstype=value2
* `||example.org^$dnstype=~A|~CNAME`: only allow `A` and `CNAME` DNS queries for
`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**.
@ -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
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
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.
#### <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
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**
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
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_laptop`: laptops,
* `device_nas`: NAS (Network-attached Storages).
* `device_other`: other devices.
* `device_pc`: PCs.
* `device_phone`: phones.
* `device_printer`: printers.
* `device_securityalarm`: security alarms.
* `device_tablet`: tablets.
* `device_tv`: TVs.
* `device_other`: other devices.
* By operating system:
@ -525,14 +532,14 @@ The list of allowed tags:
* `os_ios`: iOS.
* `os_linux`: Linux.
* `os_macos`: macOS.
* `os_other`: other OSes.
* `os_windows`: Windows.
* `os_other`: other OSes.
* By user group:
* `user_admin`: administrators.
* `user_child`: children.
* `user_regular`: regular users.
* `user_child`: children.
[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