1 Introduction

In fact, I have always wanted to build a stable and pollution-free DNS service in the intranet, specifically for solving the DNS pollution problem, for use by some applications that only need to solve DNS pollution. For example, emby's tmdb plug-in cannot scrape film and television information normally, simply because its API address "api.themoviedb.org" is polluted by the domestic DNS. For example, this is the resolution result of the domestic DNS:

The normal resolution should be resolved to the Anycast address of AWS cloudfront:

Therefore, this part of the application does not actually require a global proxy, all it needs is a "pollution-free" DNS.

In the past, I relied on the Clash plug-in built into the Merlin firmware on the AC86U router to solve the DNS pollution problem. It hijacked UDP port 53 to forward DNS requests to an external encrypted DNS service. Although this method can also solve DNS pollution, it has major limitations:

1. High requirements for service stability: Once the Clash plug-in crashes or restarts, the DNS resolution of all intranet devices will be interrupted instantly, which has a huge impact. It is a solution with high coupling and obvious single point failure risks.
2. Limited by AC86U router：This solution strongly relies on a specific model of router and its plug-in, and I am now gradually promoting the "de-routerization" of science-related functions in home data centers: for example, the main scientific tasks are handed over to the HTTP proxy provided by shadowsocket on Apple TV (some applications that support setting up proxies can use it directly), or cooperate with redsocks2 deployed on LXC to implement the "lightweight bypass gateway" function (for applications that do not support setting up proxies, see the article for the specific construction process:Home Data Center Series: Lightweight Bypass Gateway Construction Based on HTTP Proxy: Redsocks2 + iptables Practical Guide) to facilitate later hardware replacement and centralized management: AC86U may not continue to be used in the future, and relying on it is obviously not sustainable.

Therefore, I now tend to adopt a clearer and more decoupled solution. I just bought a Racknerd 1-core 1GB memory chicken at the San Jose node for $10.99/year to use as a jump server (Racknerd_Low Configuration 1_879), and can open ports to the outside world (it doesn’t matter as a jump server, but the VPS of the Chicago node is my active-active disaster recovery node, so I will never open any ports), so the plan is as follows: deploy a DNS downstream node in another LXC container or Docker instance in the intranet of the home data center, provide standard port 53 DNS services to intranet devices, and send the received DNS requests to the DNS upstream node on San Jose in an encrypted manner; deploy an encrypted DNS upstream node on the San Jose node, which can receive encrypted DNS requests from the DNS downstream node and forward them to well-known DNS service providers such as Cloudflare and Google for resolution, completely bypassing domestic DNS pollution.

This structure not only achieves decoupling and high availability, but also allows flexible configuration of domain name or IP diversion with the help of DNS downstream nodes if necessary. Domestic requests go through domestic DNS, and foreign requests go through encrypted channels, thus achieving domestic and foreign DNS query diversion.

However, how to choose the software to implement the DNS upstream node and the DNS downstream node? After some investigation, I found that the software dnscrypt-proxy can be used as the software for both the upstream and downstream nodes.

2 Introduction to dnscrypt-proxy

dnscrypt-proxy is a powerful and highly customizable local DNS "relay" proxy tool that supports encryption, mainly used to protect the privacy and integrity of DNS queries. It is maintained by Frank Denis and supports a variety of modern DNS encryption protocols, including DNSCrypt v2 and DNS-over-HTTPS (DoH), and has flexible forwarding, filtering and policy routing capabilities. It is one of the core components for building a custom and secure DNS system.

Compared with traditional plaintext DNS requests, the encryption protocol supported by dnscrypt-proxy can effectively prevent ISPs or middlemen from monitoring and tampering with DNS queries. In addition, it also has built-in support for multiple public DNS providers (such as Cloudflare, Quad9, NextDNS, etc.), and users can specify trusted upstreams or customize DoH servers by configuring the server_names parameter.

dnscrypt-proxy supports listening to any port locally (such as standard port 53 or custom port), and can securely forward received DNS queries to remote encrypted DNS servers. Together with dnsmasq or operating system DNS settings, it can provide privacy-protected recursive resolution services for the entire network. It also has a built-in cache mechanism to increase query speed, and supports advanced features such as domain-based blacklist and whitelist filtering, EDNS client subnet policy, and anonymous DNS relay.

In addition, although the configuration file of dnscrypt-proxy is highly structured, it is very flexible and suitable for fine-tuning in various environments. It can be run on high-performance servers as an enterprise-level DNS exit node, and can also be easily deployed on low-power devices (such as Raspberry Pi, small VPS, chicken, etc.) as a lightweight home or personal DNS solution.

In summary, dnscrypt-proxy is a DNS encryption proxy tool that takes into account performance, privacy, security and flexible configuration capabilities. It is especially suitable for technical users who pursue a "pollution-free DNS" environment. It is very suitable for use when there is a need for "DNS request encryption", so it can be used as software for DNS upstream and downstream nodes.

---

In fact, in addition to dnscrypt-proxy, AdGuard Home can also meet my needs: it not only has built-in encryption upstream support such as DoH/DoQ, but also has relatively complete DNS policy management capabilities. However, I finally chose the lightweight dnscrypt-proxy for two main reasons:

First of all, my needs are actually very simple. If used as a DNS upstream node software, I just want it to forward the encrypted foreign domain name query requests sent by the DNS downstream node to a clean, encrypted DNS upstream; and when used as a DNS downstream node software, it only needs to be able to send the query requests for foreign domain names from the intranet device to the DNS upstream node in an encrypted manner. I don’t need AdGuard Home’s whole set of heavyweight features such as ad blocking, graphical interface, and rule subscription. Instead of introducing a bunch of unused components and increasing the system burden, it is better to focus on achieving the goal with the simplest and most reliable solution (I took this for granted. In the end, I still chose AdGuard Home as the downstream node. The reason will be explained later).

Secondly, the performance of the San Jose node itself is poor, and the memory and CPU are tight, so it is not realistic to run a web service such as AdGuard Home that needs to be resident for a long time. However, dnscrypt-proxy is lighter and uses less resources, and can run a long-term available pollution-free DNS upstream node stably, worry-free, and with low resource usage.

---

3 Installation of dnscrypt-proxy

3.1 Source code installation

Because the dnscrypt-proxy version provided by apt is too low (still oldstable):

The latest official version on GitHub is 2.1.8, released on March 27, 2025:

The difference between the versions is really too big. The key is that the configuration logic of version 2.1.6 is quite different from that of the previous versions (the most important thing is "server = true/false"removal of this misleading parameter), so I only recommend using the latest 2.1.8 version directly (Download the latest official version of dnscrypt-proxy from github), so only the source code installation method is shown:

# Enter the working directory cd /opt # Download the official release wget https://github.com/DNSCrypt/dnscrypt-proxy/releases/download/2.1.8/dnscrypt-proxy-linux_x86_64-2.1.8.tar.gz # Unzip tar -xzf dnscrypt-proxy-linux_x86_64-2.1.8.tar.gz cd linux-x86_64 # Copy the binary file to the system default path cp dnscrypt-proxy /usr/local/bin/ # Create a configuration file based on the official template (optional). I will provide a minimal configuration file directly later. mkdir -p /etc/dnscrypt-proxy cp /opt/linux-x86_64/example-dnscrypt-proxy.toml /etc/dnscrypt-proxy/dnscrypt-proxy.toml

3.2 Deploy using docker run format

docker run --name dnscrypt-proxy -d --restart=always \ -p 53:53/udp \ -p 443:443/tcp \ -p 443:443/udp -v /docker/dnscrypt-proxy:/config \ -e TZ=Asia/Shanghai \ klutchell/dnscrypt-proxy

Note: Need to be created in advance/docker/dnscrypt-proxydirectory and create the dnscrypt-proxy.toml configuration file in it.

4 dnscrypt-proxy.toml configuration file

4.1 Clarify the working mode and deployment location of dnscrypt-proxy

Before deploying dnscrypt-proxy, the more critical question is not whether it is a server or a client, but whether it is a client or a server.Understand what role it plays in your network architecture:

Is it running in the local network, providing DNS forwarding services for intranet devices? Or is it deployed on a public network node, providing encrypted relay functions for multiple downstream clients?

In fact, no matter where it is deployed, dnscrypt-proxyPossessing two abilities at the same time:

• It listens on one or more ports and receives DNS requests from clients (which may be terminals or dnsmasq) (behaving as a "server" behavior)
• At the same time, it will also forward these requests to upstream DNS services (such as DoH, DNSCrypt servers, etc.) according to the configuration and receive responses (showing "client" behavior)

This working mechanism of "front-end receiving requests and back-end forwarding queries" determines that dnscrypt-proxy is essentially aDNS Relay Agent.

Therefore, we should not mechanically divide it into Server or Client (this is what the old version did, so it is easy to confuse people). A more accurate perspective is:Where it is deployed + Who it serves.

For example:

• dnscrypt-proxy deployed in the local network (downstream node), usually provides DNS services for intranet devices and is a local DNS relay. In this case, its upstream may be a DoH server or even another dnscrypt-proxy that you have deployed on a public network node (which is my current deployment scenario).

• dnscrypt-proxy deployed on the public network node (upstream node)It is more like a secure DNS relay station. It listens to TCP 443 or UDP 53 port of the public IP address (if DoH is released through Cloudflare Tunnel, it can be any local port), provides DNSCrypt or DoH services to the outside world, and forwards requests to trusted upstream DNS services.

4.2 Examples of common deployment scenarios

After clarifying the relay positioning of dnscrypt-proxy, we can choose different deployment methods and configuration combinations according to actual needs. The following are several typical scenarios, which basically cover common usages such as local forwarding, remote relay, and encryption protocol provided by the server:

Scenario 1: Listening port + using encrypted upstream DNS (DoH/DNSCrypt client, suitable for downstream DNS nodes)

listen_addresses = ['0.0.0.0:53'] doh_servers = true dnscrypt_servers = false

This configuration will listen to port 53 locally, receive DNS requests from local devices, and perform encrypted queries to trusted upstream nodes (such as Cloudflare, NextDNS, or self-built upstream nodes) through DoH. It is suitable for deployment in the local network as an "encrypted DNS relay", just like the familiar slogan: "We don't produce water, we are just nature's porters", of course, it needs to be changed here: "I don't resolve domain names myself, I just forward the resolution results of other trusted upstream DNS to you."

Scenario 2: Listening port + using system DNS (minimal dependencies, suitable for offline/debugging)

listen_addresses = ['0.0.0.0:53'] doh_servers = false dnscrypt_servers = false

Without relying on any external encryption protocol, dnscrypt-proxy will call the system's default resolver (usually the configuration in /etc/resolv.conf) for ordinary DNS queries.
Suitable for debugging, restricted network or temporary offline environment, as a lightweight DNS relay.

However, this method does not provide any encryption capabilities and is prone to contamination hijacking, so it is not recommended for production environments.

Scenario 3: Listening port + providing encryption protocol (DoH/DNSCrypt server, suitable as a self-built upstream DNS node)

# Optional, use tailscale ip to provide regular DNS service based on port 53 listen_addresses = ['tailscale IP:53'] # Enable DoH service [local_doh] listen_addresses = ['your public IP:443'] path = '/dns-query' cert_file = '/path/to/cert.pem' cert_key_file = '/path/to/key.pem'

In this mode, dnscrypt-proxy is not only a DNS relay, but also an "encrypted DNS service provider". For example, you can deploy it on an overseas node, use port 443 to provide DoH services to the outside world, and use the certificate generated by ACME to enable HTTPS. The dnscrypt-proxy (downstream node) in the intranet can access it through the public network address to achieve an encrypted, obfuscated, and interference-proof DNS query channel.

You can even use Tailscale or VPN to allow intranet devices to directly access its port 53 using regular DNS queries through private network addresses (provided that listen_address is configured correctly) to achieve the simplest encrypted DNS query.

---

There are two ways for downstream DNS nodes to perform encrypted communication with upstream DNS nodes, DoH and Dnscrypt (v2). In this article, my configuration uses DoH instead of Dnscrypt (v2) because if Dnscrypt (v2) is to be used, the upstream DNS node must listen to the public IP and port, which means that ufw must allow access to the corresponding port, which conflicts with my "fully closed" security guiding ideology (no port will be opened unless absolutely necessary). DoH can be used with cloudflare tunnel, which is fully compatible with the "fully closed" guiding ideology, so only DoH is used in this article, but this does not mean that Dnscrypt is not good, everyone must understand this.

---

4.3 Configuration Example (Version 2.1.8)

4.3.1 Self-built upstream DNS node configuration (suitable for overseas VPS deployment)

Create a new configuration file:

vim /etc/dnscrypt-proxy/dnscrypt-proxy.toml

Then paste the following template containing a minimal usable configuration and save it:

# Primary DNS listening address (plaintext DNS), can be set to 0.0.0.0:53, but it is not recommended, as this will become a public DNS. It is recommended to set it to tailscale IP listen_addresses = ['tailscale IP:53'] # Specify the names of upstream servers to use (from the [sources] list), otherwise dnscrypt-proxy will not enable any upstream resolvers server_names = ['google', 'cloudflare'] # Traditional DNS servers used for bootstrapping resolution of upstream server domain names (such as DoH addresses) bootstrap_resolvers = ['1.1.1.1:53', '8.8.8.8:53'] # Network connectivity detection address, a test will be made before startup as to whether this DNS can be connected netprobe_address = '1.1.1.1:53' # Settings for local DoH service provision, which can be used as a private DoH server [local_doh] # DoH Listening address, needs to be bound to port 443 listen_addresses = ['public IP:443'] # HTTP path, usually set to /dns-query, but in order to prevent being scanned, it is recommended to change to a complex path = '/dns-query' # TLS certificate and private key path, it is recommended to use a valid certificate (such as Let's Encrypt). If you use cloudflare, you can also use cloudflare's self-signed certificate cert_file = '/etc/certs/dns.tangwudi.com/dns.tangwudi.com.crt' cert_key_file = '/etc/certs/dns.tangwudi.com/dns.tangwudi.com.key' # Remote server list source, used to dynamically load supported upstream DNS (supports DNSCrypt and DoH) [sources] ### DNSCrypt The project's master server list, containing hundreds of public upstream servers [sources.public-resolvers] urls = [ 'https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/public-resolvers.md', 'https://download.dnscrypt.info/resolvers-list/v3/public-resolvers.md' ] cache_file = 'public-resolvers.md' # Local cache file name minisign_key = 'RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3' # File signature verification public key refresh_delay = 73 # How often to update the list (minutes) prefix = '' # Prefix can be used to identify the server names in this source ### : List of anonymous relay servers, used to build Anonymized DNS query chains [sources.relays] urls = [ 'https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/relays.md', 'https://download.dnscrypt.info/resolvers-list/v3/relays.md' ] cache_file = 'relays.md' minisign_key = 'RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3' refresh_delay = 73 prefix = '' # Compatibility fixes for some upstream DNS servers [broken_implementations] # These servers have DNS message fragmentation issues and will be marked for processing or avoidance fragments_blocked = [ 'cisco', 'cisco-ipv6', 'cisco-familyshield', 'cisco-familyshield-ipv6', 'cisco-sandbox', 'cleanbrowsing-adult', 'cleanbrowsing-adult-ipv6', 'cleanbrowsing-family', 'cleanbrowsing-family-ipv6', 'cleanbrowsing-security', 'cleanbrowsing-security-ipv6' ]

• The sources section is optional, but it is one of the core features of dnscrypt-proxy (dynamically loading supported servers via remote sources). If you are using a static configuration (such as [static]), then this part can be deleted.
• [broken_implementations] Optional, but recommended to avoid resolution failures due to MTU/fragmentation issues, especially when deployed on the public network.

Note: If server_names or [static], indicating that dnscrypt-proxy will randomly select [sources] Select from the loaded servers (the default policy is reliability priority + RTT priority).

4.3.2 Downstream DNS Node Configuration

Create a new configuration file:

vim /etc/dnscrypt-proxy/dnscrypt-proxy.toml

Then paste the following template containing a minimal usable configuration and save it:

# Plain text listening address, use intranet IP listen_addresses = ['192.168.xx:53'] # Specify the remote upstream DNS name to be used server_names = ['sanjose-custom'] # Point to the custom name of your upstream node # DNS used for bootstrap resolution (the first time to resolve the upstream node DoH domain name, domestic home broadband can only use domestic domain name servers) bootstrap_resolvers = ['119.29.29.29:53', '223.5.5.5:53'] # Network detection address, optional but recommended to keep, to avoid startup failure, fill in according to your own situation netprobe_address = '119.29.29.29:53' # Statically define self-built upstream server (via DNS stamp) [static.'sanjose-custom'] stamp = 'sdns://...' # The stamp generated by your server, including the DoH address and path

4.3.3 Extended knowledge: stamp address

In the DNSCrypt protocol system, stamp is a compact, shareable string.Used to describe the connection method and parameters of an upstream DNS serverIt is similar to a complete connection configuration snapshot, including the following key information:

• The protocol type supported by the upstream server (such as DNSCrypt or DoH)
• The IP address of the server
• (Optional) Host name (for SNI or Host Header)
• Request path (DoH specific, such as /dns-query)
• Public key (for verification/encryption)
• Some flags (such as whether DNSSEC is supported, whether logging is performed, whether filtering is enabled)

Stamp is for Used by downstream DNS clients (such as another dnscrypt-proxy), used to tell it: how to connect to me, through what protocol, which address, which path, and what encryption key to use. Since the stamp is an unreadable string (a custom variant of base64 encoding), we usually need to use tools toGenerate or decodeit.

---

Why do we need Stamp?

In the early days, when the DNSCrypt protocol (v1) client connected to the upstream server, it was necessary to manually fill in a bunch of configuration items such as IP address, port, public key, path, etc., which was not only cumbersome but also inconsistent. As more and more functions were supported, such as DoH and anonymous relay, the configuration complexity increased further. In order to simplify this process, the developers proposed Stamp The concept is to package all necessary information into a standardized string. This string can be pasted manually or written directly into the .toml configuration file, becoming a lightweight, universal, and easy-to-distribute connection description method.

Especially in the scenario where you build your own DNS upstream server,Without Stamp, you cannot add your own service node to the downstream dnscrypt-proxy configuration. So once you have deployed the DNSCrypt or DoH service on your VPS or home server, you must generate a corresponding stamp for it before you can use it properly.

---

How to generate a stamp address? It's very simple. Just use the official online tool provided by dnscrypt:Stamp address official online generation tool.

The hashes in the above figure need to be generated based on the crt certificate used by the upstream node using the following command:

openssl x509 -in /path/to/your.crt -noout -pubkey \ | openssl pkey -pubin -outform DER \ | openssl dgst -sha256 -binary \ | openssl enc -base64

For example, my San Jose node generates a hash value:

5 Set dnscrypt-proxy to start as a service (source code installation)

1. Assume that you have completed the modification of the configuration file

Make sure your dnscrypt-proxy.toml file has been configured and dnscrypt-proxy can be started normally. The test command is as follows:

/path/to/dnscrypt-proxy -config /path/to/dnscrypt-proxy.toml -check

If the test passes, the following information will be output:

2. **systemd installation service file (if you install it from source code)

Create a systemd service file:

vim /etc/systemd/system/dnscrypt-proxy.service

Paste and save the following:

[Unit] Description=dnscrypt-proxy After=network.target [Service] ExecStart=/usr/local/bin/dnscrypt-proxy -config /etc/dnscrypt-proxy/dnscrypt-proxy.toml Restart=on-failure RestartSec=5 User=nobody CapabilityBoundingSet=CAP_NET_BIND_SERVICE AmbientCapabilities=CAP_NET_BIND_SERVICE NoNewPrivileges=true [Install] WantedBy=multi-user.target

3. Reload systemd configuration and enable service

systemctl daemon-reexec systemctl daemon-reload systemctl enable dnscrypt-proxy systemctl start dnscrypt-proxy

4. Check the running status

systemctl status dnscrypt-proxy

6. Afterword

Although dnscrypt-proxy can serve as both an upstream and downstream DNS node, it may not be the ideal choice if you just want to deploy a downstream node at home to provide DNS resolution services for LAN devices and do not particularly emphasize "extreme lightweight".

An obvious problem is that when you use dnscrypt-proxy as a downstream client to connect to a self-built upstream node,You can’t just fill in an HTTPS address like most DoH clients do.(For example https://dns.tangwudi.com/dns-query): As mentioned earlier in the article, you must first generate a special "stamp" address, which needs to include the service's public network IP, public key, port, path and other information. Because the stamp must contain these fields, it requires the public network IP of your upstream server (the port also needs to be open for access).This directly limits your ability to hide the real IP address of the node through Cloudflare's "Little Orange Cloud" mode.

When using DoH support such as AdGuard Home, NextDNS, or system-level (such as Android, iOS, macOS) as a downstream DNS node, you only need to fill in the standard HTTPS address. The advantages of this method are:

• Support Cloudflare Proxy to hide the real IP of the upstream server, improving security and anti-attack capabilities;
• No need to deal with the tedious stamp generation and maintenance process;
• Can be flexibly matched with access control, security check, WAF and other services provided by Cloudflare;
• For users, it is more like "what you see is what you get" without complicated formats and tool barriers.

From these perspectives, one of the biggest advantages of dnscrypt-proxy in downstream scenarios is probably that it is very lightweight and has very few dependencies (no UI, single binary, and very low resource consumption).Suitable for deployment on devices or containers with extremely limited resources, such as minimalist deployment in some embedded systems, soft routers, Raspberry Pi, etc. But this is obviously not the main limitation for most home users, especially when you already have alternatives such as AdGuard Home and NextDNS that have Web UI and log management capabilities.

So this is a bit of an upside-down feeling: the original stamp mechanism of dnscrypt-proxy is to standardize configuration and enhance security, which is very meaningful when facing public upstream services, but once you as a user build an upstream node yourself, it becomes an additional burden. Especially when you want to hide the real IP of the upstream server and use Cloudflare's CDN shell, the design of stamp requiring the public IP to be exposed will directly hinder the possibility of you putting on a protective shell. Of course, dnscrypt-proxy is not completely without advantages as a downstream node. One of its unique capabilities is:It can be used without relying on domain name resolution, and an encrypted connection can be established based only on IP, public key and portThis is very valuable in some special scenarios - for example, during the period when GFW blocked SNI on a large scale, ordinary DoH services may be interrupted due to the inability to resolve domain names or TLS handshake failures. The dnscrypt protocol can bypass these restrictions by hard-coding IP + Stamp, as a backup solution with "anti-blocking" characteristics, which is not available in other downstream solutions based on the DoH protocol.

纠结了一番之后，最终我选择了在 San Jose 的”小鸡”上运行 dnscrypt-proxy 来搭建 DNS 上游节点（并通过Cloudflare Tunnel来发布DoH）；而在家庭数据中心内部，则选择了已经部署好的 AdGuard Home 作为下游节点，使用 DoH 地址连接上游节点，并对整个内网提供传统的 53 端口 DNS 解析服务。这样既保持了上游服务的灵活性与安全性，又简化了下游配置和管理负担，兼顾了易用性和轻量化。

---

When deploying a self-built DoH service (e.g. port 443 running on dnscrypt-proxy) to Cloudflare, different deployment methods will have a significant impact on the back-to-origin behavior:

• If your upstream node Directly open port 443, and Cloudflare uses the traditional Public IP back to source, then DoH services usually work properly regardless of whether CDN (Xiaocheng Cloud) is enabled.
• If your upstream node closes port 443, selectCloudflare Tunnel as a return to origin method, and want to expose the DoH service, you need to pay extra attention to several key configurations:

1. Select HTTPS in the Tunnel service type;
2. Be sure to set the Origin Server Name, this value will be sent to the local service as SNI (Server Name Indication). Otherwise, when using Cloudflare's default strict certificate verification mechanism (especially after enabling Cloudflare), the TLS handshake may fail;
3. Depending on specific needs, you can also set HTTP Host Header, to ensure that requests sent to local services contain the correct Host header field. This is especially critical for some services that rely on virtual host configuration (such as Nginx or AdGuard Home).
   
   

In other words, when you use Tunnel mode to expose the local DNS service based on HTTPS,The “origin server name” is the core configuration item for Cloudflare Tunnel to successfully complete the back-to-origin process.: Forget to configure it and TLS is out of the question.

---