Skip to main content

DNS encryption

AdGuard Home supports all modern DNS encryption protocols out-of-the-box:

note

AdGuard Home supports both client-side and server-side DNSCrypt. Learn how to configure AdGuard Home as a DNSCrypt server.

This guide explains how to setup an encrypted DNS server with AdGuard Home.

Server installation​

The purpose of securing the DNS traffic is to secure it from third parties that might be analyzing or modifying it, e.g., from ISP.

It means that you will need a server with a public dedicated IP address. There are plenty of cheap cloud servers providers: DigitalOcean, Vultr, Linode, etc. Just choose one, create a cloud server there, and install AdGuard Home 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 that will help you with that.

Get an SSL certificate​

Both DNS-over-HTTPS and DNS-over-TLS are based on TLS encryption, so you will need an SSL certificate to use them.

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 the Let’s Encrypt CA, a free certificate authority developed by the Internet Security Research Group (ISRG).

This guide explains how to get a certificate from them.

Using CertBot​

Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt.

  1. Go to certbot.eff.org and choose None of the above software and your operating system.
  2. Follow the installation instructions and stop before reaching the Get Started section.

Get a certificate using DNS challenge​

You have a domain name, using DNS challenge is the easiest way to get a certificate.

Run this command and follow the certbot’s instructions:

sudo certbot certonly --manual --preferred-challenges=dns --preferred-chain="ISRG Root X1"

In the end, you’ll get two files:

  • fullchain.pem: your PEM-encoded SSL certificate
  • privkey.pem: your PEM-encoded private key

Both will be necessary to configure AdGuard Home.

Important

You will need to use the very same procedure to renew the existing certificate.

Using Lego​

There’s also a really nice and easy-to-use alternative to CertBot called LEGO.

  1. Install it using an appropriate method.
  2. Choose your DNS provider from the list and follow the instructions to obtain a certificate.

Also, here’s a simple script that you can use to automate certificates generation and renewal.

Configure AdGuard Home​

  1. Open AdGuard Home web interface and go to Settings.

  2. Choose the Encryption section.

    Encryption settings screenshot

  3. Copy/paste the contents of the fullchain.pem file to input the field under Certificates or specify path to the file.

  4. Copy/paste the contents of the privkey.pem file to input the field under Private key or specify path to the file.

  5. Enter your domain name to Server name.

  6. Get the successful validation messages and click Save settings.

note

AdGuard Home will automatically reload certificates and/or private keys specified by file path when they change. A reload may also be triggered by a SIGHUP signal.

Using with reverse proxy​

We already have a guide on configuring a reverse proxy server for accessing AdGuard Home web UI.

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.

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.

Nginx reverse proxy​

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

Another header you might want to proxy is the Host header, which is required to make AdGuard Home recognize requests from clients that have a ClientID in their hostnames.

For example, if the configuration of the reverse proxy server contains the following directives:

location /dns-query {
  # …
  proxy_set_header Host $host;
  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".

Cloudflare CDN​

The Cloudflare’s content delivery network acts as the reverse proxy appending its own 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 may be inserted into trusted_proxies list directly. See the official Cloudflare’s reference on restoring the original visitor’s IP.

Other Headers​

Other HTTP headers may be supported by AdGuard Home in the future. However, any headers-related feature requests should first be tried to be resolved by configuring the reverse proxy itself.

For example, to modify the HTTP Strict Transport Security mechanism to include the experimental preload directive, something like the following piece of configuration might be used:

location /dns-query {
  # …
  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
  # …
}

Configuring devices​

Android​

  • Android 9 and above 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 supports DNS-over-HTTPS, DNS-over-TLS, DNSCrypt and DNS-over-QUIC.
  • Intra adds DNS-over-HTTPS support to Android.

iOS​

  • iOS 14 and above 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 supports DNS-over-HTTPS, DNS-over-TLS, DNSCrypt and DNS-over-QUIC.
  • DNSCloak supports DNS-over-HTTPS but in order to configure it to use your own server, you’ll need to generate a DNS Stamp for it.

Windows​

  • Windows 10 Build 19628 and higher support DNS-over-HTTPS natively.
  • AdGuard for Windows supports DNS-over-HTTPS, DNS-over-TLS, DNSCrypt and DNS-over-QUIC.

macOS​

  • 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.

Other implementations​

  • AdGuard Home itself can be a secure DNS client on any platform.
  • dnsproxy supports all known secure DNS protocols.
  • dnscrypt-proxy supports DNS-over-HTTPS.
  • Mozilla Firefox supports DNS-over-HTTPS.

Configuring DNSCrypt​

AdGuard Home is able to work as a DNSCrypt server. However, this feature is only available via configuration file, and can’t be set up using the Web UI. This guide explains how to do this.

Generating a configuration file​

Here is how to generate a DNSCrypt configuration file and point AdGuard Home to it:

Important

Make sure that your TLS settings are valid and encryption is enabled.

  1. Get the latest version of the dnscrypt utility for your system. Extract the archive and navigate to the resulting directory.

    • On Unix, using a POSIX-compatible shell:

      (Here and below, linux-amd64 is used as an example. Make sure to download and use the one for your platform.)

      1. Extract the files:

        tar -f ./dnscrypt-linux-amd64-v2.2.3.tar.gz -v -x -z

        Output example:

        linux-amd64/
        linux-amd64/README.md
        linux-amd64/LICENSE
        linux-amd64/dnscrypt

      2. Navigate to the extracted directory:

        cd ./linux-amd64/

      3. Generate the configuration file:

        ./dnscrypt generate --provider-name '2.dnscrypt-cert.example.org' --out ./dnscrypt.yaml

        Output example:

        2022/01/02 12:34:56 [info] Generating configuration for 2.dnscrypt-cert.example.org
        2022/02/02 12:34:56 [info] Configuration has been written to ./dnscrypt.yaml
        2022/02/02 12:34:56 [info] Go to https://dnscrypt.info/stamps to generate an SDNS stamp
        2022/02/02 12:34:56 [info] You can run a DNSCrypt server using the following command:
        2022/02/02 12:34:56 [info] dnscrypt server -c ./dnscrypt.yaml -f 8.8.8.8

    • On Windows, using PowerShell:

      (Here and below, windows-amd64 is used as an example. Make sure to download and use the one for your CPU architecture.)

      1. Extract the files:

        Expand-Archive -Path .\dnscrypt-windows-amd64-v2.2.3.zip

      2. Navigate to the extracted directory:

        Set-Location -Path .\dnscrypt-windows-amd64-v2.2.3\windows-amd64\

      3. Generate the configuration file:

        .\dnscrypt.exe generate --provider-name '2.dnscrypt-cert.example.org' --out .\dnscrypt.yaml

        Output example:

        2022/01/02 12:34:56 [info] Generating configuration for 2.dnscrypt-cert.example.org
        2022/02/02 12:34:56 [info] Configuration has been written to .\dnscrypt.yaml
        2022/02/02 12:34:56 [info] Go to https://dnscrypt.info/stamps to generate an SDNS stamp
        2022/02/02 12:34:56 [info] You can run a DNSCrypt server using the following command:
        2022/02/02 12:34:56 [info] dnscrypt server -c .\dnscrypt.yaml -f 8.8.8.8

    Where example.org is the name of your host and ./dnscrypt.yaml is the name of the configuration output file.

    You may add the path to the binary into your PATH/$env:PATH.

  2. In the configuration file (typically AdGuardHome.yaml), add the following lines:

    'tls':
      # N.B. The encryption must be enabled.
      'enabled': true
      # …
      'port_dnscrypt': 5443
      'dnscrypt_config_file': './dnscrypt.yaml'

    Where 5443 is the port for your DNSCrypt server and ./dnscrypt.yaml is the name of the configuration file generated in step 2.

    Important

    Stop AdGuard Home before changing the configuration file.

    tip

    On Windows, it is recommended to use the full path to the configuration file. For example, C:\Users\Me\Files\dnscrypt.yaml.

Generating a DNSCrypt stamp​

Here is how to generate a DNSCrypt stamp and check your installation:

  1. Go to https://dnscrypt.info/stamps/.

  2. Enter the data from your DNSCrypt configuration file. The Provider public key is the value of the public_key field in your DNSCrypt configuration file.

    note

    Enter the host with your custom port.

  3. Now you have a stamp that looks something like this:

    sdns://AQcAAAAAAAAADTEyNy4wLjAuMTo0NDMg8R3bzEgX5UOEX93Uy4gYSbZCJvPeOXYlZp2HuRm8T7AbMi5kbnNjcnlwdC1jZXJ0LmV4YW1wbGUub3Jn

    Check your installation by running:

    ./dnscrypt lookup-stamp \
        --domain 'example.com' \
        --stamp 'sdns://AQcAAAAAAAAADTEyNy4wLjAuMTo0NDMg8R3bzEgX5UOEX93Uy4gYSbZCJvPeOXYlZp2HuRm8T7AbMi5kbnNjcnlwdC1jZXJ0LmV4YW1wbGUub3Jn' \
        --type 'a'

    Or, on Windows:

    .\dnscrypt.exe lookup-stamp `
        --domain 'example.com' `
        --stamp 'sdns://AQcAAAAAAAAADTEyNy4wLjAuMTo0NDMg8R3bzEgX5UOEX93Uy4gYSbZCJvPeOXYlZp2HuRm8T7AbMi5kbnNjcnlwdC1jZXJ0LmV4YW1wbGUub3Jn' `
        --type 'a'

    Where example.com is the domain name to lookup.

Configuring devices to use DNSCrypt​

All platforms​

  • dnscrypt-proxy (reference implementation). DNSCrypt-Proxy is a command-line proxy for Linux, BSD, Windows, macOS, Android, and more.

Android​

iOS​

Windows​

See the DNSCrypt website and DNS privacy project’s list for more.