mirrors
/
AdGuardHome
mirror of https://github.com/AdguardTeam/AdGuardHome.git
1
0
Fork 0
Code Issues Packages Projects Releases 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

97
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,6 +8,9 @@ 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)
@ -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

30
Docker.md

@ -8,17 +8,15 @@
<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)
@ -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.
@ -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,13 +144,13 @@ 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
@ -174,9 +172,9 @@ 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.

33
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. 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.
@ -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