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.
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)
* [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)
@ -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

30
Docker.md

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

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.
* [`/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.
@ -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