Mosdns - The next generation DNS Resolver

Image not Found

Recently, I found a very interesting open-source project called mosdns, which is regarded as the next-generation DNS resolver from the user’s perspective. Mosdns is written in Golang, leveraging its native concurrency capability, in which it can massively reduce the overheads when it comes to resolving domains in the context of latency and efficiency. In this post, we will unveil the mystery of DNS Resolver, explore what this project can offer, and make our self-hosted DNS resolver much stronger and more secure.

For more details, please check out their GitHub Repository

Yet, at the time of writing, unfortunately, the wiki is ONLY written in Chinese. I’ve already raised a feature request to the owners and would like to contribute a well-written wiki in English.


Background of DNS

What is a DNS Resolver?

A DNS resolver, also known as a resolver, is a server on the Internet that converts domain names into IP addresses.

When you use the Internet, every time you connect to a website using its domain name (such as “”), your computer needs to know that website’s IP address (a unique series of numbers). So your computer contacts a DNS resolver and gets the current IP address of

Usually, the resolver is one part of a larger decentralized DNS (domain name system). When you send your request to the DNS resolver, the resolver accesses other servers in the DNS to obtain the address, then sends you the response.

The DNS resolver contacted by your computer is usually chosen by your ISP (Internet service provider). However, you can configure your network to use a different DNS provider, if you choose. This configuration can be modified in your operating system’s network settings, or in the administration interface of your home network router.

How DNS Resolver works?

DNS resolvers are the clients that query for DNS information from a nameserver. These programs run on a host to query a DNS nameserver, interpret the response, and return the information to the programs that request it. In DNS, the resolver implements the recursive query algorithm that traverses the inverted namespace tree until it finds the result for a query (or an error).

The following diagram from Amazon’s Route 53 documentation gives an overview of how recursive and authoritative DNS services work together to route an end user to your website or application.

To understand more about the DNS workflow, check out this blog post.

What are DoH and DoT?

The following diagram demonstrates the differences between http and https when it comes it exchanging data between client and server

DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) are both trying to solve the problem of hiding the DNS queries. DNS over HTTPS is an internet security protocol that communicates domain name server information in an encrypted way over HTTPS connections.

As most organizations are already aware, a DNS traffic filtering solution is crucial for their cybersecurity environment. But while most organizations are already using a DNS traffic filter, the dilemma brought on by DoH is that compatibility issues may arise once browsers start using DoH by default.

Here is what can be problematic. DNS traffic filtering solutions are using the settings of built-in Operating Systems to perform DNS queries. However, if the browser is no longer in use of the standard DNS port (53) for queries and instead switches to the DoH one (443), the traffic filtering solution will lose sight of those queries.

While DoH indeed brings more privacy by default, it should not be confused with compliance or security.

To understand more, please check out this blog post.


The flowchart below demonstrates the Mosdns workflow in a common use case.

How to deploy

Deploy Prerequisites (Optional)

Proxmox LXC

I found out the earist way to get mosdns deployed is to deploy it as a Proxmox LXC Container. There is an automation script that you can leverage to spin up an LXC Container on Proxmox in minutes.

GitHub Repository - tteck/Proxmox

1# provision Ubuntu LXC
2bash -c "$(wget -qLO -"

If you also need external cache storage, I would recommend you use the above script to provision two LXC containers, one for mosdns, and the other one for redis.


As suggested by the mosdns maintainers, mosdns is ONLY made up of a single executable binary file. Therefore, we can just simply head over to the release page, download the executable binary that is compatable with the platform of choice.

For those who host a dedicated Proxmox server, and followed the above step to provision LXC containers, you may download the from the release page

Environment Preparation

Get the following steps done so that mosdns can be called as /usr/bin/mosdns.

 1# acquired root access
 2sudo -i
 4# install vim and unzip
 5sudo apt-get update -y && sudo apt-get upgrade -y
 6sudo apt-get install vim unzip -y
 8# create default mosdns directory
 9mkdir -p /etc/mosdns
11# unzip the release binary
12cd /etc/mosdns
15# mv the executable binary to /usr/bin
16chmod +x mosdns
17mv mosdns /usr/bin/

Reset Port 53

By default, mosdns runs on port 5533. If you want to set bind it to port 53, the default port for DNS, do the following:

Deactivate DNSStubListener and update DNS server address. Create a new file: /etc/systemd/resolved.conf.d/mosdns.conf (create a /etc/systemd/resolved.conf.d directory if necessary) with the following contents:

1mkdir -p /etc/systemd/resolved.conf.d
3# /etc/systemd/resolved.conf.d/mosdns.conf

Specifying as DNS server address is necessary because otherwise the nameserver will be which doesn’t work without DNSStubListener.

Activate another resolv.conf file:

1sudo mv /etc/resolv.conf /etc/resolv.conf.backup
2sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf

Restart DNSStubListener:

1systemctl daemon-reload
2systemctl restart systemd-resolved

Verify port open status:

1ss -tupln

if everything goes well, you will not see port :53 from the console outputs.


Spin up mosdns

1# start mosdns
2mosdns start -c /etc/mosdns/config.yaml -d /etc/mosdns


1mosdns -h

Install as a daemon service

Mosdns service is a simple system service management tool. Mosdns can be installed as a system service to realize self-starting. Administrator or root privileges are required. Theoretically, it can be used on Windows XP+,Linux/(systemd | upstart | sysv), and OSX/Launchd platforms. Windows, Ubuntu, Debian are available.

 1# install mosdns as a daemon service
 2# mosdns service install -d <mosdns_work_dir> -c <mosdns_config_absolute_path>
 3mosdns service install -d /etc/mosdns -c /etc/mosdns/config.yaml
 4# start the service (service will not be automatically start at the first time)
 5systemctl enable mosdns --now
 6mosdns service start
 8# check service status
 9systemctl status mosdns
11# uninstall
12mosdns service stop
13mosdns service uninstall

If you make any changes in the config.yml file, please restart the daemon service accordingly.

Sample Configuration

Sample config.yml is available in TechProber/mosdns-lxc-deploy.


To sum up, Mosdns is a plugin-based DNS forwarder. Users can splice plugins as needed and customize their DNS processing logic. With mosdns, we may get a better DNS processing experience without worrying too much about DNS contamination from the local ISP.

You May Also Like