MasterDnsVPN: a Go DNS tunnel built for lossy, censored networks

The problem MasterDnsVPN targets: TCP over DNS on hostile networks

MasterDnsVPN is a DNS tunnel. It encodes TCP traffic inside DNS queries and responses so that a client behind a restrictive network can reach a server somewhere else. The README calls it "a scientific and research-oriented project for carrying TCP traffic through DNS queries and responses" and places it in the same broad category as DNSTT and SlipStream while claiming a different internal structure.

The audience is narrow and specific. This is for people whose network blocks ordinary VPN transports but still resolves DNS, who control a server and a domain, and who are willing to run a client and a server binary themselves. It is not a consumer VPN. There is no account, no exit-node marketplace, and no mobile app in the repository listing. The top-level entries are Go source, TOML config samples, a Docker directory, shell scripts and translated READMEs. Anyone expecting an APK or an App Store listing will not find one here.

One framing note matters. The README carries a disclaimer that the software is "provided as an educational and research project only", comes with no warranty, and that using it to bypass local law may carry civil or criminal consequences. That is the project's own language, and it should shape how you read every performance claim on the page.

How the tunnel works: a custom protocol, ARQ, and a 5 to 7 byte header

The comparison table in the README is the clearest statement of the design. MasterDnsVPN uses a "Custom protocol + ARQ" transport with a header overhead of roughly 5 to 7 bytes, against about 59 bytes for DNSTT (KCP plus Noise) and about 24 bytes for SlipStream (QUIC). The project frames that gap as the main reason it can operate where MTU is small: less per-packet overhead means more room for payload inside the same DNS message.

Encryption is selectable: AES, ChaCha20, or XOR. The README is explicit that XOR is "lightweight with lower security and no extra overhead", which is an honest way of saying it is not encryption in any meaningful sense. The cryptographic dependency in go.mod is golang.org/x/crypto, and the module also pulls in klauspost/compress and pierrec/lz4, which suggests compression is part of the wire path. The README does not document the key exchange, the cipher modes, or how keys are provisioned between client and server, so the security properties of the AES and ChaCha20 paths cannot be assessed from the documentation alone.

On top of the transport sits a reliability layer. The README lists ARQ, duplication, failover, resolver health checks with auto-disable, and background reactivation of resolvers that recover. The stated goal is delivery under packet loss rather than peak throughput on a clean link. Multi-resolver support is described as "advanced (multi-resolver + duplication)", with eight built-in balancing modes and adaptive routing based on latency and loss. Duplication deliberately sends more traffic to improve reliability and can be configured or disabled, which is the trade-off you would expect: you buy delivery probability with bandwidth.

The client side also runs a local DNS service, which the README says reduces DNS hijacking, and can resolve DNS through SOCKS5 with caching. TCP forwarding mode is described as a way to carry other TCP-based protocols such as Shadowsocks or VLESS/VMess indirectly.

Installing MasterDnsVPN and running a first client session

The repository ships a server install script at the top level, server_linux_install.sh, alongside server_config.toml.simple and client_config.toml.simple. Those file names are the practical starting point: the project expects you to copy a sample config and edit it rather than generate one interactively.

On a Linux server, the documented entry point is the install script. Run it from the repository root:

chmod +x server_linux_install.sh
./server_linux_install.sh

The README does not spell out what the script does line by line, so read it before running it. What you should expect afterwards is a server process driven by a TOML file modelled on server_config.toml.simple. Copy the sample to the working name the binary reads, then edit it:

cp server_config.toml.simple server_config.toml

On the client, the same pattern applies with client_config.toml.simple. The repository also includes client_resolvers.simple, which is where the resolver list lives; the README describes multi-resolver balancing and resolver health checks, so this file is the one that determines which resolvers the client will use and how it distributes across them.

cp client_config.toml.simple client_config.toml
cp client_resolvers.simple client_resolvers.toml

For container users there is a docker/ directory in the tree. The README does not document a published image name or a compose file, so treat the directory itself as the source of truth for how the container is meant to be built and run.

One caution about the install path: the README does not document an uninstall step, a rollback procedure, or exactly which files the script writes and where. Capture the script's output and note the paths it touches before you run it on a machine you care about.

Where MasterDnsVPN breaks down, and when it is the wrong tool

The first hard limit is DNS itself. If the network blocks or intercepts DNS to the resolvers you need, a DNS tunnel has nothing to ride on. MasterDnsVPN mitigates some of this with a local DNS service and caching, and the README says it is designed around "compatibility with many resolver behaviors", but no tunnel can carry traffic over a protocol that has been shut off.

The second limit is throughput. The README's speed table is labelled "Local", and its numbers (0.270s for a 10MB download, 1.746s for a 10MB upload) describe a local test, not a real censored path. The project's own comparison puts MasterDnsVPN at "up to ~9x faster than DNSTT" and "up to ~3.6x faster than SlipStream". Those are the project's claims, not independently measured results, and the README gives no methodology, no test conditions and no hardware. Do not plan a workload around them. DNS tunneling is a narrow pipe even when it works well, and duplication mode narrows it further by design.

The third limit is the security story. XOR is offered as an option and the README warns it has lower security. The documentation does not describe the key exchange or how the AES and ChaCha20 modes are wired, so there is no basis in the repository for treating the tunnel as audited. For a research or censorship-circumvention use that may be acceptable. For protecting credentials on an untrusted network, it is not the tool you want.

The fourth limit is operational. The README does not document rollback, log formats, metrics endpoints, or how to debug a resolver that keeps getting auto-disabled. The config surface is described as fine-grained, with "almost every subsystem" configurable, and the README itself concedes setup becomes "more complex only if you heavily customize advanced settings". That is a fair description: the defaults are meant to be simple, and the moment you touch balancing, duplication and failover together, you are operating a small distributed system with no published runbook.

MasterDnsVPN versus DNSTT and SlipStream: three different bets

The README positions MasterDnsVPN against two named projects, and the differences are structural rather than cosmetic.

DNSTT is described as a classic DNS tunnel built on KCP plus Noise with a multi-layered architecture (KCP, SMUX, Noise) and roughly 59 bytes of transport header overhead. It is written in Go, supports SOCKS5, and the comparison table marks it as having no multi-resolver support, no built-in balancer, no duplication and no failover. Its stated design goal is "simplicity and stability". If you want the smallest possible moving-parts count and you are on a clean link, that simplicity is a feature, not a gap.

SlipStream is described as an advanced DNS tunnel over QUIC with TLS 1.3 inside it, roughly 24 bytes of overhead, multipath support and a Rust implementation. Its design goal is "high speed and efficiency". QUIC brings a mature congestion-control and multipath stack, but it also brings the larger header, which is exactly the cost MasterDnsVPN attacks.

MasterDnsVPN's bet is the opposite: strip the header to 5 to 7 bytes, write a custom ARQ layer, and spend the saved space on resolver duplication and adaptive routing. That buys tolerance for small MTU and heavy loss. It costs you the maturity of QUIC or Noise, and it puts the reliability logic in a codebase that the README describes as research-oriented. If your network is clean, SlipStream's QUIC stack is the more conservative choice. If your network drops packets and your MTU is tight, the overhead argument is the one that matters, and it is the reason this project exists.

Maintenance, releases and what the MIT licence does and does not cover

The repository is not archived, and the last push was on 2026-08-29. Releases are dated and carry commit hashes: v2026.06.13.234407-7de2476 on 2026-06-13, v2026.05.10.180256-27c7e11 on 2026-05-10, and v2026.05.04.123456-38b73de on 2026-05-04. The version scheme embeds a timestamp and a short hash, which makes it easy to map a binary back to a commit but tells you nothing about API stability between releases.

The go.mod targets go 1.25.0 and pins five direct dependencies: BurntSushi/toml, klauspost/compress, pierrec/lz4, golang.org/x/crypto and golang.org/x/sys. That is a small dependency surface for a project of this kind, and it means upgrades are mostly a matter of tracking the Go toolchain and those five modules. The upgrade cost that the documentation does not address is configuration drift: there is no changelog, no migration notes, and no statement about whether a client_config.toml written against one release will load in the next. Back up your TOML files before upgrading and diff the .simple samples against your working copies.

The repository is MIT licensed. MIT permits use, copying, modification and distribution provided the copyright notice and permission notice are retained, and it disclaims warranty. Two caveats worth stating plainly, without giving legal advice: the README's disclaimer adds its own language about user responsibility and legal compliance that sits alongside the licence, and the README says use is "governed by the license in the LICENSE file of this repository". Confirm the LICENSE file contents yourself rather than relying on the licence label in a repository listing.

Editorial conclusion

Adopt MasterDnsVPN if you already run a server on a domain whose DNS traffic survives your network, you are comfortable editing TOML, and you accept that the project describes itself as educational and research software with no warranty. Skip it if you want a one-click client with a hosted exit, if DNS is blocked outright on your network, or if you need an audited protocol with published cryptanalysis. Before committing, verify three things on your own hardware: that your resolver path carries the query volume, that the client_config.toml.simple keys match the build you downloaded, and that the licence file in the repository is the one you think it is.

Frequently asked questions

Official sources

1. License: MIT
2. masterking32/MasterDnsVPN on GitHub
3. Project website
4. README
5. Releases