Preface

I have previously written an article on building a DNS server based on bind9 (see:Docker series builds a DNS server based on bind9), but this is more suitable for use when you build a test environment yourself. If we only need a local DNS forwarder, bind9 will be too bloated. I searched the Internet and found ADguard home. ADguard home is mainly a domain name protection (advertising filtering, blacklist filtering, etc.), so when I first looked for a DNS solution, I thought it was a random article, and I despised it for a while. I didn't expect that after a closer look, this is exactly the perfect forwarder I want. It also provides DOH, DOT, and even comes with an ad filtering function~~~~. At the same time, if science or magic happens to be available in the environment, it can also be upgraded from ad-free DNS to ad-free and pollution-free DNS, which can solve many problems caused by DNS pollution, such as: emby's TMDB plug-in cannot be scraped because "api.themovdb.org" is polluted~ Although it can be temporarily solved by modifying the local host file, don't forget that the ip is just one of many cdn addresses, and it is not always unchanged. Do you still need to parse and modify the host regularly? (Besides, Qnap's NAS will restore the default values every time the host is restarted, and a startup script must be used to modify the host file after the restart is complete~) With clean DNS, these are not a problem.

---

Of course, to establish a pollution-free DNS, a scientific or magical environment is required. After having a scientific or magical environment, there are many ways to access "api.themovdb.org" normally, such as pointing the system where emby is located directly to science or magic, or the system where emby is located directly uses a proxy that can be used for science or magic. Therefore, at that time, pollution-free DNS is only one of the optional methods.

In addition, DNS pollution and DNS hijacking are two different things. In China, all DNSs are polluted and there is no clean one. The so-called DOT and DOH technologies can prevent DNS hijacking, but they are actually only for operators. So if you use Alibaba or Tencent's DOH, DOT, it only means that your operator can't intercept, modify or change your DNS requests (for example, if you enter the wrong domain name, you will be directly redirected to the operator's advertising page~).

---

In the past, my QNAP emby solved the problem of TMDB API being polluted by directly specifying the http proxy at the system level, but this would cause many outbound requests not related to TMDB to use the proxy, which didn't have much impact (scientific equipment has a domain name whitelist), but it was still not pleasant; and it was also inappropriate to let all outbound traffic of the QNAP NAS go through science or magic, after all, only emby needed to use it, so these were not perfect solutions. Now, just point the dns to the unpolluted dns, and other outbound traffic will not be affected. This is the most perfect way, and patients with forced true can finally breathe a sigh of relief.

Of course, pollution-free DNS can only solve some of the problems caused by DNS pollution. As for more advanced IP-level restrictions, ASN number restrictions, and even SNI restrictions, it is powerless and can only rely on science or magic.

Deploy ADguard home

Create a directory on the host that needs to be mapped to the container

mkdir -p /docker/adguardhome/work # stores the filter rule file of ADguard home mkdir -p /docker/adguardhome/conf # stores the configuration file of ADguard home mkdir -p /docker/adguardhome/cert # stores the certificate file needed by ADguard home

Build ADguard home

The docker run format command for building ADguard home is as follows:

docker run --name adguardhome -d --restart=always \ -v /docker/adguardhome/work:/opt/adguardhome/work \ -v /docker/adguardhome/conf:/opt/adguardhome/conf \ -v /docker/adguardhome/cert:/opt/adguardhome/cert \ -p 53:53/tcp -p 53:53/udp \ # provides the standard dns service port to the outside world. If there are devices in the intranet that need to directly point the dns address to ADguard, the host mapping port needs to use port 53 (mainly udp53, tcp53 is rare, but it is best to keep it) -p 80:80/tcp -p 443:443/tcp -p 443:443/udp \ #80 is actually useless. To use DOH or DOQ, you need to use port 443. DOH uses tcp 443 and DOQ uses udp 443 -p 3000:3000/tcp \ #gui panel page -p 853:853/tcp \ #DOT port -p 5443:5443/tcp -p 5443:5443/udp \ #DNSCrypt server port -d adguard/adguardhome

The above is the complete version of the command, but in the actual environment we don't use so many ports, at most TCP/UDP port 53, TCP port 443, TCP port 3000, so the regular version of the command is as follows:

docker run --name adguardhome -d --restart=always \ -v /docker/adguardhome/work:/opt/adguardhome/work \ -v /docker/adguardhome/conf:/opt/adguardhome/conf \ -v /docker /adguardhome/cert:/opt/adguardhome/cert \ -p 53:53/tcp -p 53:53/udp \ -p 443:443/tcp \ -p 3000:3000/tcp \ -d adguard/adguardhome

After the container is running, you can use it directlyhttp://host ip:3000Visit ADguard home.

initialization

When you visit ADguard for the first time, select "Simplified Chinese" in the language option in the lower right corner, and then click "Start Configuration" in the center of the screen:

Note that the ports in the figure below refer to the ports inside the container. The listening port of the web management interface must be changed to 3000, and then click "Next" at the bottom of the page:

After setting your username and password, click "Next" at the bottom of the page (why is it in English again?):

This is the interface for helping with settings. You can also see it in the GUI panel after initialization is complete. Then just click "Next" at the bottom of the page:

Initialization is successful, just click "Open Dashboard":

Click "Login" to officially enter:

Configure ADguard home

DNS settings

Go to "Settings" - "DNS Settings":

The interface is as follows:

In the above figure, you need to modify the "upstream DNS server" according to your actual environment. For example, if it is only for domestic access, fill in the domestic public DNS, such as Tencent Cloud's 119.29.29.29, Alibaba Cloud's 223.5.5.5, etc.; if there is a scientific or magical environment and you need to build a pollution-free DNS, fill in the foreign public DNS IP here, such as Google's 8.8.8.8, Cloudflare's 1.1.1.1, or you can directly fill in the public DOH address. You can refer to the example in the red box below.

This part in the above picture also needs to be modified according to your actual environment. "Backup DNS server" means what it says. Because my "upstream DNS servers" are all from abroad, once science or magic is interrupted, the game will be over. So I filled in the domestic Alibaba Cloud DNS in the "backup DNS server" just in case.

"Bootstrap DNS server" is not necessary. It is only useful if the "upstream DNS server" uses the DOH/DOT address. And if the domestic public DOH/DOT (such as Tencent Cloud) is used, it is best to fill in the corresponding dns address (Tencent Cloud) here.

After the settings are completed, you can click "Test Upstream" in the red box below to test whether the upstream server can work properly, and then click "Apply" to save this part of the configuration.

There are other options in this section, you can study them yourself, and keeping the default value will not affect the use:

Encryption settings

Go to "Settings" - "Encryption Settings":

This part is mainly about setting the certificate required for DOT/DOH/DOQ encryption.

---

Here, you should first evaluate the method that best suits your actual environment. DOH requires a legal TCP 443 port. In the domestic environment, it must have a TCP 443 port and be able to run https. In layman's terms, it must be registered. DOQ needs to use udp 443. I have not actually studied this, and I don't know if the cloud host environment has any restrictions on this. If not, it is a good choice. DOT needs to use TCP 853 port. For cloud hosts that are not registered and home broadband with public network addresses, it is an option, but this and DOQ have a disadvantage: anyone with a discerning eye can tell what you are doing at a glance. After all, the traffic of udp 443 and TCP 853 is too obvious. Although you don't know the details of what you are doing, it is clear at a glance what you are doing. I chose DOH because I have a registered domain name and a "good citizen certificate" for the legal use of port 443. Moreover, DOH has a huge advantage over DOT and DOQ, which I will introduce later.

---

This part enables encryption and sets the specific encryption method to be used. I only need DOH, so I only leave HTTPS port 443. You can choose according to your actual situation:

Then set up the certificate:

I will use another article to talk about the specific certificate application in the future. It is nothing more than Let's Encrypt or Tencent Cloud, Alibaba Cloud free. The most convenient one is ohttps (remember that the 20 certificates applied for free by Let's Encrypt and Tencent Cloud are all from the Asian Integrity System, sharing a maximum of 20 host names. I haven't learned about Alibaba, but it's probably the same. For detailed steps to apply for and deploy ohttps certificates, please refer to the article:Home Data Center Series SSL Certificate One-Stop Management Tool OHTTPS Usage Tutorial). Assuming that everyone already has a ready-made certificate and private key, there are two ways to upload:
1. "Set certificate path" and "Set private key file":
Remember the -v parameter of the previous docker run command:
-v /docker/adguardhome/cert:/opt/adguardhome/cert
On the host/docker/adguardhome/certThe directory is used to directly place certificate files and private key files, corresponding to the container/opt/adguardhome/certDirectory, so you only need to copy xxx.crt and xxx.key directly to the host machine/docker/adguardhome/certDirectory, and then use '/opt/adguardhome/cert/xxx.crt' and/opt/adguardhome/cert/xxx.keySpecify the certificate path and save it.
2. "Paste certificate content" and "Paste private key content":
In this way, you can directly copy and paste the certificate content and private key content into ADguard. In this way, the certificate and private key content are directly stored in the AdGuardHome.yaml file in the conf directory.

Both methods are acceptable, but if you use the "paste" method, you will need to manually update the certificate content regularly, while if you use the "set" method, you can use external methods to regularly update the certificate. I will explain this in detail in another article later.

DNS client settings (optional)

This section allows you to add clients and assign specific identifiers to them:

This identifier can be called up in the "DNS Settings" section above:

It is possible to allow only certain clients to access or not allow certain clients to access.
For example, if I want to make it so that only I can access it, I can add a client and specify the identifier:

Then in "DNS Settings" only allow this user to access:

Then use when specifying the DOH address:https://example.org/dns-query/222-333-444-555-666As an address, that is, in the conventionalhttps://example.org/dns-queryJust add the client identifier at the end.

There are also corresponding designated methods for using DOT and DOQ, but a wildcard domain name certificate is required. For details, please refer to the official instructions:

Filter Settings

"Filter" - "DNS Blacklist":

Click Add Blacklist below the image above:

There are many lists in the picture above. I have selected two that start with CHN. You can check them by yourself, but it is recommended not to have too many. Then click Save in the lower right corner.

"Filter" - "DNS Rewrite":

This is actually custom domain name resolution:

"Filter" - "Blocked Services":

Here you can quickly block domain name resolution of some common networks, and set a blocking schedule:

You can research the details on your own. I have no demand for this.

Domestic and foreign DNS diversion (optional)

If you build a clean DNS, you will face a problem: when using this DNS, you will have problems accessing some domestic websites. This will involve the problem of DNS diversion between China and abroad. ADguard supports DNS diversion between China and abroad, but it requires a whitelist corresponding to domestic domain names and domestic DNS. The project "mouyase/ChinaListForAdGuardHome" on github provides a whitelist specifically for ADguard home use. Part of the content is as follows:

The whitelist download address is as follows:ChinaWhiteList.txt, you can download it by yourself and update it regularly.

After ChinaWhiteList.txt is downloaded, it can be placed on the host and mounted in any directory inside the container, such as/docker/adguardhome/confDirectory, and then use a text editor to edit the same directoryAdGuardHome.yamlIn the upstream_dns_file option (which is empty by default), add the following content:/opt/adguardhome/conf/ChinaWhiteList.txt,as follows:

Save and restart the container.

Release ADguard home service to the public

For me, I have two usages of ADguard home:
1. As a pollution-free DNS in the LAN
This is mainly used for machines that need to use emby scraping. Of course, my home broadband has a public network IP, port 53 can be used, and it can also be exposed to the Internet, but because it is a dynamic IP, it changes every few days, which is meaningless.
2. Provide DOH services to external parties
This is the most useful. Why did I choose DOH among DOQ, DOT, and DOH? Because DOH is based on https, which has a huge advantage, and you can use CDN (of course, if it is a domestic CDN, you need to have a registered domain name)! Because my home broadband outlet has a public IP but no 443 port, but Tencent Cloud's CDN can customize the source station port, so you can use Tencent Cloud CDN to point to the non-443 port of the home broadband outlet router, and then use port mapping from the router to finally point to the 443 port of ADguard home. What is finally provided to the outside world is the 443 port accelerated by Tencent through CDN, and the key is to hide the source station IP address!

In addition, regarding the choice of DOT/DOQ technology: if it is a home broadband with a public network address, use DOT; if it is a cloud host, use DOT or DOQ. You can study the details by yourself. It is a matter of domain name resolution and port mapping (cloud host is port release). However, if it is DOT or DOQ, the IP address of your host will be exposed, so you must pay attention to security precautions.

---

Because I don't want to open a port mapping for ADguard home on the router alone, I still want to directly use a unified external publishing port, so it's a little more complicated: (https to) CDN (cloudflare or Tencent Cloud CDN) -> (via public network https to) home data center export total reverse proxy -> (https to) ADguard home, certificates need to be deployed in all three locations (ADguard must be a legal certificate, the other two locations are arbitrary), and my doh domain name is also connected to cloudflare through a custom host name, so there is no need to worry about crawlers and ddos, the benefits are huge.

A simple way to determine whether the DOH configured by ADguard home is successful is to directly access the DOH address with a browser. If Bad Request is returned, it is successful:

Of course, this success does not guarantee whether it can pass the chroma verification (for example, the com domain name I hosted through cloudflare):

However, the DOH of my other Tencent cc domain name can be accessed through the browser and verified by chrome:


It's really a mystery.

Note: The reason why CloudFlare cannot pass the Chrome check has been found. There are two points to note:
1. Cloudflare's WAF treats the query request sent by Chrome as an abnormal request and questions it. It is necessary to skip the operation in the WAF rules based on the access host, URI path (/dns-query), UA proxy and other conditions.
2. When using tunnel to create Public hostnames, if you want to point directly to the https port of ADguard, you need to configure the Origin Server Name of TLS, because ADguard can only use legal certificates (so it is definitely not the self-signed certificate of the cloudflare hosted domain name). When cloudflare uses the https protocol to access the https port of ADguard through the tunnel, the domain name contained in the obtained certificate does not match the self-hosted one, and the connection cannot be established. Therefore, you need to use the Origin Server Name to specify the domain name in the ADguard certificate. This is really amazing. I never thought of the use of this option before, but now I know it, as shown in the figure:

Of course, if you do not point directly to the https port of ADguard, but access it through a reverse proxy, this step is not required.

---

Client configuration DOH/DOT server

This is one of the reasons why I chose DOH. In terms of the convenience of current client settings, DOH is the simplest. For example, win11 has built-in support:

The Chrome browser is also convenient:


In the red box in the picture above, you can fill in the DOH, DOT, or DOQ address.

Please note that, as mentioned above, after filling in the DOH, DOT, DOQ address in Chrome, Chrome will verify the legitimacy of the address. If the verification fails, the following error will be displayed:

If the verification is normal, there will be no prompt. Take Tencent Cloud DOH as an example:

Therefore, whether the self-built DOH and other addresses are valid can be seen here (it is also possible that they are valid but the verification package is intercepted).

Many Android clients can directly specify the DOT address, while iOS and macOS need to be installed using a description file. For the generation of the specific description file, please refer to the following URL:https://dns.notjakob.com/tool.html.

Afterword

I was so tired writing this article. I had to sort out many knowledge blind spots. It took me a lot of time, but it was worth it. I won't post my DOH address because it's a bit taboo.