Pull request: 2799 trusted proxies
Merge in DNS/adguard-home-wiki from 2799-proxies to master
Squashed commit of the following:
commit 530e19fd4ae77309100ac649e05662674d1f0457
Merge: 60098db ab8edf0
Author: Eugene Burkov <e.burkov@adguard.com>
Date: Mon Jul 26 19:27:59 2021 +0300
Merge branch 'master' into 2799-proxies
commit 60098db73043ecbd26a236719f8d2d773836d34b
Author: Eugene Burkov <e.burkov@adguard.com>
Date: Mon Jul 26 18:48:12 2021 +0300
Encryption: fix lists
commit c7e8ab9821507ee37b25653bd7ecb7c9953c1ff3
Author: Eugene Burkov <e.burkov@adguard.com>
Date: Mon Jul 26 18:35:55 2021 +0300
Encryption: spaces
commit cb54cabd6c7bcf6633fc9778679982ef8f68b200
Author: Eugene Burkov <e.burkov@adguard.com>
Date: Mon Jul 26 18:22:21 2021 +0300
Encryption: imp & fmt
commit d45c2fab8ee32012f74b0ae01d04344d4c0fa7ce
Author: Eugene Burkov <e.burkov@adguard.com>
Date: Mon Jul 26 15:54:04 2021 +0300
all: trusted_proxies & using with reverse proxy
Eugene Burkov
parent
ab8edf0458
commit
95020709e7
|
|
@ -357,7 +357,10 @@ Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possib
|
|||
- **Access settings**
|
||||
- `allowed_clients` — IP addresses of allowed clients
|
||||
- `disallowed_clients` — IP addresses of clients that should be blocked
|
||||
- `blocked_hosts` — hosts that should be blocked
|
||||
- `blocked_hosts` — Hosts that should be blocked
|
||||
- `trusted_proxies` (**since v0.107.0**) – The list of IP addresses and CIDR
|
||||
networks to detect proxy servers' addresses from which AdGuard Home should
|
||||
accept and handle DNS-over-HTTPS requests.
|
||||
- **DNS cache settings**
|
||||
- `cache_size` — DNS cache size (in bytes)
|
||||
- `cache_ttl_min` — override TTL value (minimum) received from upstream server. This value can't larger than 3600 (1 hour).
|
||||
|
|
|
|||
297
Encryption.md
297
Encryption.md
|
|
@ -1,131 +1,282 @@
|
|||
# AdGuard Home - Encryption
|
||||
# AdGuard Home – Encryption
|
||||
|
||||
We are proud to say that AdGuard Home supports all modern DNS encryption protocols **out-of-the-box**:
|
||||
We are proud to say that AdGuard Home supports all modern DNS encryption
|
||||
protocols **out-of-the-box**:
|
||||
|
||||
- [DNS-over-HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS)
|
||||
- [DNS-over-TLS](https://en.wikipedia.org/wiki/DNS_over_TLS)
|
||||
- [DNS-over-QUIC](https://tools.ietf.org/html/draft-ietf-dprive-dnsoquic-01)
|
||||
* [DNS-over-HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS)
|
||||
* [DNS-over-TLS](https://en.wikipedia.org/wiki/DNS_over_TLS)
|
||||
* [DNS-over-QUIC](https://tools.ietf.org/html/draft-ietf-dprive-dnsoquic-01)
|
||||
|
||||
> AdGuard Home also supports [DNSCrypt](https://dnscrypt.info/) (both client-side and server-side). [Read this](DNSCrypt) to learn about configuring AdGuard Home as a DNSCrypt server.
|
||||
> AdGuard Home also supports [DNSCrypt](https://dnscrypt.info/) (both
|
||||
> client-side and server-side). [Read this](DNSCrypt) to learn about
|
||||
> configuring AdGuard Home as a DNSCrypt server.
|
||||
|
||||
In this guide we will explain how to setup your own "Secure DNS" server with AdGuard Home.
|
||||
In this guide we will explain how to setup your own "Secure DNS" server with
|
||||
AdGuard Home.
|
||||
|
||||
1. [Install AdGuard Home on your server](#install)
|
||||
2. [Register a domain name](#register)
|
||||
3. [Get an SSL certificate](#certificate)
|
||||
- [Install CertBot](#certbot)
|
||||
- [Get a certificate using DNS challenge](#certbot-dnschallenge)
|
||||
- [Alternative to CertBot: Lego](#lego)
|
||||
4. [Configure AdGuard Home](#configure-home)
|
||||
5. [Configure your devices](#configure-devices)
|
||||
1. [Register a domain name](#register)
|
||||
1. [Get an SSL certificate](#certificate)
|
||||
* [Install CertBot](#certbot)
|
||||
* [Get a certificate using DNS challenge](#certbot-dnschallenge)
|
||||
* [Alternative to CertBot: Lego](#lego)
|
||||
1. [Configure AdGuard Home](#configure-home)
|
||||
1. [Using with reverse proxy](#reverse-proxy)
|
||||
* [Nginx](#nginx)
|
||||
* [Cloudflare CDN](#cf-cdn)
|
||||
1. [Configure your devices](#configure-devices)
|
||||
* [Android](#android)
|
||||
* [iOS](#ios)
|
||||
* [Windows](#windows)
|
||||
* [MacOS](#macos)
|
||||
* [Other implementations](#other-imps)
|
||||
|
||||
<a id="install"></a>
|
||||
|
||||
## Install AdGuard Home on your server
|
||||
|
||||
It does not make much sense to configure DNS encryption inside of your own local network. The purpose of securing your DNS traffic is to secure it from third-parties that might be analyzing or modifying it. For instance, from your ISP.
|
||||
## <a href="#install" id="install" name="install">Install AdGuard Home on your server</a>
|
||||
|
||||
It means that you will need a server with a public dedicated IP address. There are plenty of cheap cloud servers providers: [DigitalOcean](https://digitalocean.com), [Vultr](https://vultr.com), [Linode](https://www.linode.com/), etc. Just choose one, create a cloud server there, and [install AdGuard Home](Getting-Started) on your server.
|
||||
It does not make much sense to configure DNS encryption inside of your own local
|
||||
network. The purpose of securing your DNS traffic is to secure it from
|
||||
third-parties that might be analyzing or modifying it. For instance, from your
|
||||
ISP.
|
||||
|
||||
<a id="register"></a>
|
||||
It means that you will need a server with a public dedicated IP address. There
|
||||
are plenty of cheap cloud servers providers: [DigitalOcean][digital-ocean],
|
||||
[Vultr][vultr], [Linode][linode], etc. Just choose one, create a cloud server
|
||||
there, and [install AdGuard Home](Getting-Started) on your server.
|
||||
|
||||
## Register a domain name
|
||||
|
||||
First of all, you need a domain name. If you have never registered one, here is a [simple instruction](https://www.pcworld.com/article/241722/web-apps/how-to-register-your-own-domain-name.html) that will help you with that.
|
||||
|
||||
<a id="certificate"></a>
|
||||
[digital-ocean]: https://digitalocean.com
|
||||
[vultr]: https://vultr.com
|
||||
[linode]: https://www.linode.com
|
||||
|
||||
## Get an SSL certificate
|
||||
|
||||
Both `DNS-over-HTTPS` and `DNS-over-TLS` are based on [TLS encryption](https://en.wikipedia.org/wiki/Transport_Layer_Security) so in order to use them, you will need to acquire an SSL certificate.
|
||||
|
||||
An SSL certificate can be bought from a "Certificate Authority" (CA), a company trusted by browsers and operating systems to enroll SSL certificates for domains.
|
||||
## <a href="#register" id="register" name="register">Register a domain name</a>
|
||||
|
||||
Alternatively, you can get the certificate for free from ["Let's Encrypt" CA](https://letsencrypt.org/), a free certificate authority developed by the Internet Security Research Group (ISRG).
|
||||
First of all, you need a domain name. If you have never registered one, here is
|
||||
a [simple instruction][domain-name-register] that will help you with that.
|
||||
|
||||
|
||||
|
||||
[domain-name-register]: https://www.pcworld.com/article/241722/web-apps/how-to-register-your-own-domain-name.html
|
||||
|
||||
|
||||
|
||||
## <a href="#certificate" id="certificate" name="certificate">Get an SSL certificate</a>
|
||||
|
||||
Both `DNS-over-HTTPS` and `DNS-over-TLS` are based on [TLS
|
||||
encryption][tls-wikipedia] so in order to use them, you will need to acquire an
|
||||
SSL certificate.
|
||||
|
||||
An SSL certificate can be bought from a "Certificate Authority" (CA), a company
|
||||
trusted by browsers and operating systems to enroll SSL certificates for
|
||||
domains.
|
||||
|
||||
Alternatively, you can get the certificate for free from ["Let's Encrypt"
|
||||
CA][letsencrypt], a free certificate authority developed by the Internet
|
||||
Security Research Group (ISRG).
|
||||
|
||||
In this guide I'll explain how to get a certificate from them.
|
||||
|
||||
<a id="certbot"></a>
|
||||
|
||||
### Install CertBot
|
||||
### <a href="#certbot" id="certbot" name="certbot">Install CertBot</a>
|
||||
|
||||
Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt.
|
||||
|
||||
1. Go to [https://certbot.eff.org/](https://certbot.eff.org/) and choose "None of the above" software and your operating system.
|
||||
2. Follow the installation instructions, and stop there - don't get to the "Get Started" section.
|
||||
1. Go to [certbot.eff.org][certbot] and choose "None of the above"
|
||||
software and your operating system.
|
||||
1. Follow the installation instructions, and stop there – don't get to the "Get
|
||||
Started" section.
|
||||
|
||||
<a id="certbot-dnschallenge"></a>
|
||||
### <a href="#certbot-dnschallenge" id="certbot-dnschallenge" name="certbot-dnschallenge">Get a certificate using DNS challenge</a>
|
||||
|
||||
### Get a certificate using DNS challenge
|
||||
|
||||
You have just got a domain name so I suppose using DNS challenge will be the easiest way to get a certificate.
|
||||
You have just got a domain name so I suppose using DNS challenge will be the
|
||||
easiest way to get a certificate.
|
||||
|
||||
Run this command and follow the certbot's instructions:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
sudo certbot certonly --manual --preferred-challenges=dns
|
||||
```
|
||||
|
||||
In the end you'll get two files:
|
||||
|
||||
- `fullchain.pem` -- your PEM-encoded SSL certificate
|
||||
- `privkey.pem` -- your PEM-encoded private key
|
||||
* `fullchain.pem` – your PEM-encoded SSL certificate.
|
||||
|
||||
* `privkey.pem` – your PEM-encoded private key.
|
||||
|
||||
Both will be necessary to configure AdGuard Home.
|
||||
|
||||
> You will need to use the very same procedure to renew the existing certificate.
|
||||
> You will need to use the very same procedure to renew the existing
|
||||
> certificate.
|
||||
|
||||
<a id="lego"></a>
|
||||
### <a href="#lego" id="lego" name="lego">Alternative to CertBot: Lego</a>
|
||||
|
||||
### Alternative to CertBot: Lego
|
||||
There's also a really nice and easy-to-use alternative to CertBot called
|
||||
[lego][lego-source].
|
||||
|
||||
There's also a really nice and easy-to-use alternative to CertBot called [lego](https://go-acme.github.io/lego/).
|
||||
1. Install it using [an appropriate method][lego-install].
|
||||
1. Choose your DNS provider from [the list][lego-provider]
|
||||
and follow the instruction to obtain a certificate.
|
||||
|
||||
1. Install it using [an appropriate method](https://go-acme.github.io/lego/installation/).
|
||||
2. Choose your DNS provider from [the list](https://go-acme.github.io/lego/dns/) and follow the instruction to obtain a certificate.
|
||||
|
||||
<a id="configure-home"></a>
|
||||
|
||||
## Configure AdGuard Home
|
||||
[tls-wikipedia]: https://en.wikipedia.org/wiki/Transport_Layer_Security
|
||||
[letsencrypt]: https://letsencrypt.org
|
||||
[certbot]: https://certbot.eff.org
|
||||
[lego-source]: https://go-acme.github.io/lego
|
||||
[lego-install]: https://go-acme.github.io/lego/installation
|
||||
[lego-provider]: https://go-acme.github.io/lego/dns
|
||||
|
||||
|
||||
|
||||
## <a href="#configure-home" id="configure-home" name="configure-home">Configure AdGuard Home</a>
|
||||
|
||||
1. Open AdGuard Home web interface and go to settings.
|
||||
2. Scroll down to the "Encryption" settings
|
||||
|
||||
3. Copy/paste the contents of the `fullchain.pem` file to "Certificates"
|
||||
4. Copy/paste the contents of the `privkey.pem` file to "Private key"
|
||||
5. Enter your domain name to "Server name"
|
||||
6. Click "Save settings".
|
||||
1. Scroll down to the "Encryption" settings.
|
||||
|
||||
<a id="configure-devices"></a>
|
||||
![][encryption-screenshot]
|
||||
|
||||
## Configure your devices
|
||||
3. Copy/paste the contents of the `fullchain.pem` file to "Certificates".
|
||||
3. Copy/paste the contents of the `privkey.pem` file to "Private key".
|
||||
3. Enter your domain name to "Server name".
|
||||
3. Click "Save settings".
|
||||
|
||||
### Android
|
||||
|
||||
- Android 9 supports `DNS-over-TLS` natively. To configure it, go to Settings → Network & internet → Advanced → Private DNS and enter your domain name there.
|
||||
- [AdGuard for Android](https://adguard.com/en/adguard-android/overview.html) supports `DNS-over-HTTPS`, `DNS-over-TLS`, `DNSCrypt` and `DNS-over-QUIC`.
|
||||
- [Intra](https://getintra.org/) adds `DNS-over-HTTPS` support to Android.
|
||||
|
||||
### iOS
|
||||
[encryption-screenshot]: https://user-images.githubusercontent.com/5947035/53301027-2a0c2b80-385f-11e9-81f3-bcc63de4eef1.png
|
||||
|
||||
- iOS 14 and higher support `DNS-over-TLS` and `DNS-over-HTTPS` natively via configuration profiles. In order to make things easier, AdGuard Home can generate these configuration profiles for you. Just head to "Setup Guide" -> "DNS Privacy" and scroll to iOS.
|
||||
- [AdGuard for iOS](https://adguard.com/en/adguard-ios/overview.html) supports `DNS-over-HTTPS`, `DNS-over-TLS`, `DNSCrypt` and `DNS-over-QUIC`.
|
||||
- [DNSCloak](https://itunes.apple.com/app/id1452162351) supports `DNS-over-HTTPS` but in order to configure it to use your own server, you'll need to generate a [DNS Stamp](https://dnscrypt.info/stamps) for it.
|
||||
|
||||
### Windows
|
||||
|
||||
- Windows 10 Build 19628 and higher support `DNS-over-HTTPS` natively.
|
||||
- [AdGuard for Windows](https://adguard.com/en/adguard-windows/overview.html) supports `DNS-over-HTTPS`, `DNS-over-TLS`, `DNSCrypt` and `DNS-over-QUIC`.
|
||||
## <a href="#reverse-proxy" id="reverse-proxy" name="reverse-proxy">Using with reverse proxy</a>
|
||||
|
||||
### MacOS
|
||||
We already have a [guide][reverse-proxy-faq] on configuring a reverse proxy
|
||||
server for accessing AdGuard Home web UI.
|
||||
|
||||
- MacOS Big Sur and higher support `DNS-over-TLS` and `DNS-over-HTTPS` natively via configuration profiles. In order to make things easier, AdGuard Home can generate these configuration profiles for you. Just head to "Setup Guide" -> "DNS Privacy" and scroll to iOS.
|
||||
Since v0.107.0 AdGuard Home is able to restrict DNS-over-HTTPS requests which
|
||||
came from the proxy server not included into "trusted" list. By default, it's
|
||||
configured to accept requests from IPv4 and IPv6 loopback addresses.
|
||||
|
||||
### Other implementations
|
||||
To enable AdGuard Home to handle DNS-over-HTTPS requests from a reverse proxy
|
||||
server, set the `trusted_proxies` setting in `AdGuardHome.yaml` to the IP
|
||||
address of the proxy server. If you have several proxy servers, you can use a
|
||||
CIDR instead of a simple IP address.
|
||||
|
||||
- AdGuard Home itself can be a secure DNS client on any platform.
|
||||
- [dnsproxy](https://github.com/AdguardTeam/dnsproxy) supports all known secure DNS protocols.
|
||||
- [dnscrypt-proxy](https://github.com/jedisct1/dnscrypt-proxy) supports `DNS-over-HTTPS`.
|
||||
- [Mozilla Firefox](https://www.mozilla.org/firefox/) supports `DNS-over-HTTPS`.
|
||||
### <a href="#nginx" id="nginx" name="nginx">Nginx reverse proxy</a>
|
||||
|
||||
You can find more implementations [here](https://dnscrypt.info/implementations) and [here](https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Clients).
|
||||
To configure AdGuard Home for accepting requests from Nginx reverse proxy
|
||||
server, make sure that the reverse proxy server itself is configured correctly.
|
||||
|
||||
The `nginx.conf` file should contain the appropriate directives to add the
|
||||
supported forwarding headers to the request which are `X-Real-IP` or
|
||||
`X-Forwarded-For`. This may be achieved with `ngx_http_realip_module` which is
|
||||
explained [here][ngx-http-realip-module]. In short, the module takes real IP
|
||||
address of the client and writes it to the HTTP request's header. The AdGuard
|
||||
Home will receive and interpret the value of this header as real client's
|
||||
address. The address of the reverse proxy server will be received too and also
|
||||
checked against the "trusted" proxies list.
|
||||
|
||||
For example, if the configuration of the reverse proxy server contains the
|
||||
following directives:
|
||||
|
||||
```none
|
||||
location /dns-query {
|
||||
...
|
||||
proxy_set_header X-Real-IP '1.2.3.4';
|
||||
proxy_bind 192.168.1.2;
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
AdGuard Home will get the `192.168.1.2` as the address of your proxy server and
|
||||
check it against the `trusted_proxies`. The `1.2.3.4` will be controlled by
|
||||
access settings in case the proxy is "trusted".
|
||||
|
||||
### <a href="#cf-cdn" id="cf-cdn" name="cf-cdn">Cloudflare CDN</a>
|
||||
|
||||
The Cloudflare's content delivery network acts as the reverse proxy appending
|
||||
its [own headers][cloudflare-headers] to the forwarded requests, which are
|
||||
`CF-Connecting-IP` and `True-Client-IP`. These are also supported by AdGuard
|
||||
Home so the reverse proxy servers' [addresses][cloudflare-addresses] may be
|
||||
inserted into `trusted_proxies` list directly. An official Cloudflare's
|
||||
reference on restoring the original visitor's IP may be found
|
||||
[here][cloudflare-real-ip].
|
||||
|
||||
|
||||
|
||||
[reverse-proxy-faq]: https://github.com/AdguardTeam/AdGuardHome/wiki/FAQ#how-to-configure-a-reverse-proxy-server-for-adguard-home
|
||||
[ngx-http-realip-module]: https://nginx.org/en/docs/http/ngx_http_realip_module.html
|
||||
[cloudflare-headers]: https://support.cloudflare.com/hc/en-us/articles/200170986
|
||||
[cloudflare-addresses]: https://www.cloudflare.com/ips
|
||||
[cloudflare-real-ip]: https://support.cloudflare.com/hc/en-us/articles/200170786
|
||||
|
||||
|
||||
|
||||
## <a href="#configure-devices" id="configure-devices" name="configure-devices">Configure your devices</a>
|
||||
|
||||
### <a href="#android" id="android" name="android">Android</a>
|
||||
|
||||
* Android 9 supports `DNS-over-TLS` natively. To configure it, go to Settings
|
||||
→ Network & internet → Advanced → Private DNS and enter your domain name
|
||||
there.
|
||||
|
||||
* [AdGuard for Android][ag-for-android] supports `DNS-over-HTTPS`,
|
||||
`DNS-over-TLS`, `DNSCrypt` and `DNS-over-QUIC`.
|
||||
|
||||
* [Intra][intra] adds `DNS-over-HTTPS` support to Android.
|
||||
|
||||
### <a href="#ios" id="ios" name="ios">iOS</a>
|
||||
|
||||
* iOS 14 and higher support `DNS-over-TLS` and `DNS-over-HTTPS` natively via
|
||||
configuration profiles. In order to make things easier, AdGuard Home can
|
||||
generate these configuration profiles for you. Just head to "Setup Guide" →
|
||||
"DNS Privacy" and scroll to iOS.
|
||||
|
||||
* [AdGuard for iOS][ag-for-ios] supports `DNS-over-HTTPS`, `DNS-over-TLS`,
|
||||
`DNSCrypt` and `DNS-over-QUIC`.
|
||||
|
||||
* [DNSCloak][dnscloak] supports `DNS-over-HTTPS` but in order to configure it
|
||||
to use your own server, you'll need to generate a [DNS Stamp][stamps] for
|
||||
it.
|
||||
|
||||
### <a href="#windows" id="windows" name="windows">Windows</a>
|
||||
|
||||
* Windows 10 Build 19628 and higher support `DNS-over-HTTPS` natively.
|
||||
|
||||
* [AdGuard for Windows][ag-for-windows] supports `DNS-over-HTTPS`,
|
||||
`DNS-over-TLS`, `DNSCrypt` and `DNS-over-QUIC`.
|
||||
|
||||
### <a href="#macos" id="macos" name="macos">MacOS</a>
|
||||
|
||||
* MacOS Big Sur and higher support `DNS-over-TLS` and `DNS-over-HTTPS`
|
||||
natively via configuration profiles. In order to make things easier, AdGuard
|
||||
Home can generate these configuration profiles for you. Just head to "Setup
|
||||
Guide" → "DNS Privacy" and scroll to iOS.
|
||||
|
||||
### <a href="#other-imps" id="other-imps" name="other-imps">Other implementations</a>
|
||||
|
||||
* AdGuard Home itself can be a secure DNS client on any platform.
|
||||
|
||||
* [dnsproxy][ag-dnsproxy] supports all known secure DNS protocols.
|
||||
|
||||
* [dnscrypt-proxy][dnscrypt-proxy] supports `DNS-over-HTTPS`.
|
||||
|
||||
* [Mozilla Firefox][firefox] supports `DNS-over-HTTPS`.
|
||||
|
||||
You can find more implementations [here][dnscrypt-imps1] and
|
||||
[here][dnscrypt-imps2].
|
||||
|
||||
|
||||
|
||||
[ag-for-android]: https://adguard.com/en/adguard-android/overview.html
|
||||
[intra]: https://getintra.org
|
||||
[ag-for-ios]: https://adguard.com/en/adguard-ios/overview.html
|
||||
[dnscloak]: https://itunes.apple.com/app/id1452162351
|
||||
[stamps]: https://dnscrypt.info/stamps
|
||||
[ag-for-windows]: https://adguard.com/en/adguard-windows/overview.html
|
||||
[ag-dnsproxy]: https://github.com/AdguardTeam/dnsproxy
|
||||
[dnscrypt-proxy]: https://github.com/jedisct1/dnscrypt-proxy
|
||||
[firefox]: https://www.mozilla.org/firefox
|
||||
[dnscrypt-imps1]: https://dnscrypt.info/implementations
|
||||
[dnscrypt-imps2]: https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Clients
|
||||
|
|
|
|||
Loading…
Reference in New Issue