mirrors/AdGuardHome
1
0
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2025-03-15 06:59:00 +03:00
Code Issues Projects Releases Packages Wiki Activity

Pull request: Configuration: imp upstreams and local_domain_name sections 

Merge in DNS/adguard-home-wiki from 3273-3003-configuration to master

Squashed commit of the following:

commit f42054045dcdd0c84266d55e9274f141435f80a2
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Jul 22 17:12:09 2021 +0300

    Configuration: rm comma

commit 5aa4a09211e533834d9dc0a2e7b31ba843d6d407
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Jul 22 17:03:17 2021 +0300

    Configuration: fix grammar, imp wording

commit 99e946cdacf6df8355359400fb2386c9fbe9669d
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Jul 22 14:25:54 2021 +0300

    Configuration: imp wording

commit d0935595f93282fc0ad87293d3ece9809f2d29cc
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Thu Jul 22 13:24:14 2021 +0300

    Configuration: imp upstreams and local_domain_name sections
Ainar Garipov 2021-07-22 17:15:56 +03:00
parent 7340e5c081
commit 3a4ac4b9c2
1 changed files with 182 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

268
Configuration.md

@ -1,19 +1,20 @@
# 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.
Most of these settings can be changed via the web-based admin interface.
However, we decided to list them all here just in case.
- [Command-line arguments](#command-line)
- [Configuring upstreams](#upstreams)
- [Specifying upstreams for domains](#upstreams-for-domains)
- [Loading the list of upstream servers from a file](#upstreams-from-file)
- [Specifying upstreams for rDNS](#upstreams-for-rdns)
- [Configuration file](#configuration-file)
- [Reset Web Password](#password-reset)
- [Profiling with pprof](#pprof)
* [Command-line Arguments](#command-line)
* [Configuring Upstreams](#upstreams)
* [Specifying Upstreams For Domains](#upstreams-for-domains)
* [Loading Upstreams From File](#upstreams-from-file)
* [Specifying Upstreams For Reverse DNS](#upstreams-for-rdns)
* [Configuration File](#configuration-file)
* [Reset Web Password](#password-reset)
* [Profiling With Pprof](#pprof)
<a id="command-line"></a>
## Command-line arguments
## <a href="#command-line" id="command-line" name="command-line">Command-line Arguments</a>
Here is a list of all available command-line arguments.
@ -48,91 +49,175 @@ Please note, that the command-line arguments override settings from the configur
- Re-read runtime clients from `/etc/hosts` file and `arp -a` output
- Re-read SSL certificate file (if it has changed)
Command-line arguments passed to `-s install` command will be then used by the service. For instance if you install AdGuardHome service using `sudo ./AdGuardHome -s install --no-check-update`, it will disable update check functionality in the service as well.
Command-line arguments passed to `-s install` command will be then used by the
service. For instance, if you install the AdGuard Home service using `sudo
./AdGuardHome -s install --no-check-update`, it will disable update check
functionality in the service as well.
<a id="upstreams"></a>
## Configuring upstreams
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 settings, or you can even specify a DNS server that will be used to resolve specific domains.
## <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
settings, or you can even specify a DNS server that will be used to resolve
specific domains.
Examples:
- `1.1.1.1` - regular DNS (over UDP).
- `tls://1dot1dot1dot1.cloudflare-dns.com` – encrypted [DNS-over-TLS](https://en.wikipedia.org/wiki/DNS_over_TLS).
- `https://cloudflare-dns.com/dns-query` – encrypted [DNS-over-HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS).
- `quic://dns-unfiltered.adguard.com:784` - experimental [DNS-over-QUIC](https://tools.ietf.org/html/draft-huitema-quic-dnsoquic) support.
- `tcp://1.1.1.1` – regular DNS (over TCP).
- `sdns://...` – you can use [DNS Stamps](https://dnscrypt.info/stamps/) for [DNSCrypt](https://dnscrypt.info/) or [DNS-over-HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS) resolvers.
- `[/example.local/]1.1.1.1` – you can specify DNS upstream for a specific domain(s).
* `94.140.14.140`: plain DNS (over UDP).
<a id="upstreams-for-domains"></a>
* `tls://dns-unfiltered.adguard.com`: encrypted [DNS-over-TLS].
### Specifying upstreams for domains
* `https://cloudflare-dns.com/dns-query`: encrypted [DNS-over-HTTPS].
You can specify upstreams that will be used for a specific domain(s). We use the dnsmasq-like syntax (see `--server` description [here](http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html)). This feature is intended for private nameservers which deal with intranet domains.
* `quic://dns-unfiltered.adguard.com:784`: experimental [DNS-over-QUIC] support.
**Syntax:**
* `tcp://1.1.1.1`: plain DNS (over TCP).
[/domain1/domain2/domainN/]upstreamString
* `sdns://...`: [DNS Stamps] for [DNSCrypt] or [DNS-over-HTTPS] resolvers.
If one or more domains are specified, that upstream (`upstreamString`) is used only for those domains. Usually, it is used for private nameservers. For instance, if you have a nameserver on your network which deals with `xxx.internal.local` at `192.168.0.1` then you can specify `[/internal.local/]192.168.0.1`, and AdGuard Home will send all queries to that nameserver. Everything else will be sent to the default upstreams (which are mandatory!).
* `[/example.local/]1.1.1.1`: DNS upstream for specific domains, see below.
1. An empty domain specification, // has the special meaning of "unqualified names only" ie names without any dots in them.
2. More specific domains take precedence over less specific domains, so: `[/host.com/]1.2.3.4` + `[/www.host.com/]2.3.4.5` will send queries for _.host.com to 1.2.3.4, except _.www.host.com, which will go to 2.3.4.5
3. The special server address '#' means, "use the standard servers", so: `[/host.com/]1.2.3.4` + `[/www.host.com/]#` will send queries for _.host.com to 1.2.3.4, except _.www.host.com which will be forwarded as usual.
### <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`
[here][dnsmasq-man]). This feature is intended for private nameservers which
deal with intranet domains.
The syntax is:
```none
[/domain1/domain2/domainN/]upstreamString
If one or more domains are specified, that upstream (here `upstreamString`) is
used only for those domains. Usually, it is used for private nameservers. For
instance, if you have a nameserver on your network which deals with
`xxx.internal.local` at address `192.168.0.1` then you can specify
`[/internal.local/]192.168.0.1`, and AdGuard Home will send all
`*.internal.local` queries to that nameserver. Everything else will be sent to
the default upstreams, which should be specified as well.
An empty domain specification, `//` has the special meaning of “unqualified
names only”, i.e. names without any dots in them, like `myhost` or `router`.
More specific domains take precedence over less specific domains. So,
a configuration like this:
```none
[/host.com/]1.2.3.4
[/www.host.com/]2.3.4.5
```
sends queries for `*.host.com` to `1.2.3.4`, except for queries for
`*.www.host.com`, which are sent to `2.3.4.5`.
The special server address `#` means “use the default servers”. So,
a configuration like this:
```none
6.7.8.9
[/host.com/]1.2.3.4
[/www.host.com/]#
```
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
- ```
8.8.8.8:53
[/local/]192.168.0.1:53
```
* A configuration like:
Sends queries for `*.local` domains to `192.168.0.1:53`. Other queries are sent to `8.8.8.8:53`.
```none
8.8.8.8:53
[/local/]192.168.0.1:53
```
- ```
8.8.8.8:53
[/host.com/]1.1.1.1:53
[/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` (as long as other queries).
sends queries for `*.local` domains to `192.168.0.1:53`. Other queries are
sent to `8.8.8.8:53`.
<a id="upstreams-from-file"></a>
* A configuration like:
### Loading the list of upstream servers from a file
```none
8.8.8.8:53
[/host.com/]1.1.1.1:53
[/maps.host.com/]#
```
Using specific upstreams for some domains is a common way to accelerate internet in China, for example see https://github.com/felixonmars/dnsmasq-china-list and many other dnsmasq lists.
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.
These lists can be easily converted to a list for AdGuard Home:
### <a href="#upstreams-from-file" id="upstreams-from-file" name="upstreams-from-file">Loading Upstreams From File</a>
- `server=/0-100.com/114.114.114.114` -> `[/0-100.com/]114.114.114.114`
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
or any other of the many `dnsmasq` lists. These lists can be easily converted
to a list for AdGuard Home:
The problem with these lists is that they may be too large. In this case you may want to load them from a separate file instead of setting all upstreams in AdGuard settings. Just specify the path to a file with your list in the `upstream_dns_file` field of `AdGuardHome.yaml`.
```none
Before: server=/0-100.com/114.114.114.114
After: [/0-100.com/]114.114.114.114
```
<a id="upstreams-for-rdns"></a>
The problem with these lists is that they may be too large. In this case you
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`.
### Specifying upstreams for rDNS
### <a id="upstreams-for-rdns">Specifying Upstreams For Reverse DNS</a>
AdGuardHome automatically gets the names of connected devices using Reverse DNS lookup (rDNS).
It sends a PTR request with an IP address of a client to a DNS server and uses its name for "clients friendly names".
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”.
Since **v0.106.0** you can enable and disable this feature by "Enable clients' hostname resolution" setting in the "Upstream DNS servers" section or via `resolve_clients` field in the configuration file.
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.
Also since **v0.106.0** all the addresses from [private IP range](https://tools.ietf.org/html/rfc6303) are only resolved via appropriate local resolvers to avoid the leaks of clients' information. But you can also set custom upstreams for it by "Private DNS servers" field in the "Upstream DNS servers" section or by `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.
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.
Since **v0.107.0** you can control using private reverse DNS upstream servers by "Use private rDNS resolvers" checkbox in the "Upstream DNS servers" section or by `use_private_ptr_resolvers` field in the configuration file. In case it is disabled, the unknown addresses from locally-served networks won't be resolved at all.
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.
But what if you want AdGuardHome 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:
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:
[/128.in-addr.arpa/]8.8.8.8
```none
[/128.in-addr.arpa/]192.168.8.8
```
This rule instructs AdGuardHome to use `8.8.8.8` DNS server for all rDNS requests to resolve clients' IP addresses `128.0.0.0/8`.
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.
<a id="configuration-file"></a>
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:
## Configuration file
```none
[/in-addr.arpa/]192.168.8.8
```
[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
[DNS-over-TLS]: https://en.wikipedia.org/wiki/DNS_over_TLS
[DNSCrypt]: https://dnscrypt.info/
[dnsmasq-man]: http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html
[private-ip]: https://tools.ietf.org/html/rfc6303
## <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.
@ -251,10 +336,15 @@ Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possib
- `upstream_timeout` (**since v0.107.0**) — The timeout for querying
upstream servers. Zero value will be rewritten with default one which is
10s.
- `local_domain_name` (**since v0.106.0**) — The domain name that AdGuard
Home uses for known internal hosts. The default value, which is also set
when this value is empty, is `lan`. So, if you have a machine called
`myhost` in your network, its hostname will be `myhost.lan`.
- `local_domain_name` (**since v0.106.0**): The domain name that AdGuard
Home's DHCP server uses for hostnames of its clients. The default value,
which is also set when this value is empty, is `lan`. So, if you have
a machine called `myhost` in your network, and AdGuard Home is this
network's DHCP server, the hostname of that machine is `myhost.lan`.
DNS queries of type `A` for such hosts are only allowed from locally
served networks, such as `10.0.0.0/8`, `192.168.0.0`, and so on. Other
clients receive an empty `NXDOMAIN` response.
- `resolve_clients` (**since v0.106.0**) - Enable/disable resolving clients'
addresses by sending PTR requests.
- `filters` — List of filters, each filter has the following values:
@ -314,50 +404,56 @@ Removing an entry from settings file will reset it to the default value. Deletin
[DNSCrypt]: https://github.com/AdguardTeam/AdGuardHome/wiki/DNSCrypt
[`dnscrypt`]: https://github.com/ameshkov/dnscrypt
<a id="password-reset"></a>
## Reset Web Password
## <a href="#password-reset" id="password-reset" name="password-reset">Reset Web Password</a>
AdGuard Home stores password as a BCrypt-encoded hash.
Here's what you need to do to change the password:
1. Stop AdGuard Home
2. Edit `AdGuardHome.yaml`
3. Find `password` field there
4. Replace it with the new value. You can use `htpasswd` tool or any online BCrypt generation tool (there are many available online).
5. Start AdGuard Home
1. Stop AdGuard Home.
2. Open `AdGuardHome.yaml`.
3. Find the `password` field there.
4. Replace it with the new value. You can use `htpasswd` tool or any online
BCrypt generation tool (there are many available online).
5. Restart AdGuard Home.
Now you'll be able to log in to Web interface using your new password.
Example using htpasswd:
```
```sh
htpasswd -bnBC 10 "" MY_NEW_PASS | tr -d ':'
```
<a id="pprof"></a>
## Profiling with pprof
To enable pprof, set `debug_pprof: true` in yaml configuration file and then restart AdGuardHome. Now you can get profiling information with your browser, e.g.:
## <a href="#pprof" id="pprof" name="pprof">Profiling With Pprof</a>
http://localhost:6060/debug/pprof/goroutine?debug=2
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,
for example `http://localhost:6060/debug/pprof/goroutine?debug=2` will show the
call trace of each running goroutine.
will show the call trace of each running goroutine.
This URL lets you see information about the heap usage of the AdGuard Home
process: `http://localhost:6060/debug/pprof/heap?debug=1`.
This command lets you see information about the process's heap usage:
Or, with `go tool pprof`:
http://localhost:6060/debug/pprof/heap?debug=1
or with `go tool pprof`:
go tool pprof -top http://localhost:6060/debug/pprof/heap
```sh
go tool pprof -top http://localhost:6060/debug/pprof/heap
```
For a list of supported profiles go to `http://localhost:6060/debug/pprof/`.
Alternatively, you may want to simply download the file and analyze it later:
```
```sh
wget http://localhost:6060/debug/pprof/heap
go tool -http=:8080 heap
go tool --http=':8080' heap
```