MasterDnsVPN Project 🔐
MasterDnsVPN is a scientific and research-oriented project for carrying TCP traffic through DNS queries and responses. In broad goal, it is similar to projects such as DNSTT or SlipStream, but it follows a fundamentally different structure and implementation approach.
This system is designed around compatibility with many resolver behaviors and harsh network conditions, with the goal of preserving the highest possible stability and data delivery even in the worst cases.
📊 MasterDnsVPN Compared with Similar Projects
| Feature |
SlipStream |
DNSTT |
MasterDnsVPN |
| Protocol type |
Advanced DNS tunnel |
Classic DNS tunnel |
Advanced DNS tunnel / VPN |
| Transport protocol |
QUIC |
KCP + Noise |
Custom protocol + ARQ |
| Transport header overhead |
🟠 ~24B |
🔴 ~59B |
🟢 ~5–7B
≈88% lower than DNSTT
≈71% lower than SlipStream |
| Encryption style |
TLS 1.3 (inside QUIC) |
Noise (Curve25519) |
AES / ChaCha20 / XOR (if XOR is used: lightweight with lower security and no extra overhead) |
| Architecture |
Unified (QUIC handles everything) |
Multi-layered (KCP + SMUX + Noise) |
🟢 Lightweight custom design optimized for DNS |
| Speed |
🟡 High (up to ~5× faster than DNSTT) |
🔴 Medium |
🟢 Faster than others
Up to ~9× faster than DNSTT
Up to ~3.6× faster than SlipStream |
| Stability under packet loss |
🟡 Good |
🟠 Medium |
🟢 Very high (Multipath + ARQ) |
| Multi-resolver support |
Yes (multipath) |
❌ |
Yes — advanced (multi-resolver + duplication) |
| Resilience under heavy censorship |
Good |
Medium |
Very strong (a core project goal) |
| Setup complexity |
Medium |
Simple |
Easier installation
More complex only if you heavily customize advanced settings |
| SOCKS5 support |
Yes |
Yes |
Optimized for SOCKS5 / SOCKS4 with reduced SOCKS overhead |
| Shadowsocks support |
✅ |
❌ |
Indirectly: TCP Forwarding mode can carry TCP-based protocols
e.g. Shadowsocks, VLESS/VMess, etc. |
| Real multipath |
Yes (QUIC multipath) |
❌ |
Yes (multi-resolver + duplication) |
| Adaptive routing |
Limited |
❌ |
Advanced (latency/loss based) |
| Design goal |
High speed and efficiency |
Simplicity and stability |
Surviving the harshest networks — stability, speed, and efficiency |
| Implementation language |
Rust |
Go |
Main version is Go
Legacy Python version also exists |
| Built-in balancer |
🔴 |
❌ |
🟢 (8 built-in balancing modes) |
| Duplication system |
❌ |
❌ |
Yes — increases traffic to improve reliability (configurable or can be disabled) |
| MTU tolerance |
Better than DNSTT |
- |
Works even with very small MTU because protocol overhead is very low |
| Failover system |
❌ |
❌ |
✅ |
| Download speed 10MB (Local) |
🟡 0.978s |
🔴 2.492s |
🟢 0.270s |
| Upload speed 10MB (Local) |
🟡 3.249s |
🔴 16.207s |
🟢 1.746s |
| Resolver health checks and auto-disable |
❌ |
❌ |
✅ |
| Background reactivation of healthy resolvers |
❌ |
❌ |
✅ |
| Local DNS service on client (to reduce DNS hijacking) |
❌ |
❌ |
✅ (with strong DNS caching) |
| DNS resolving through SOCKS5 |
❌ |
❌ |
✅ (with DNS caching) |
| Fine-grained professional configuration |
🟠 |
🟠 |
🟢 Almost every subsystem is configurable |
| No external helper software required |
❌ |
❌ |
🟢 No extra software is required; if needed, you can still combine it with SOCKS or tools such as Shadowsocks or OpenVPN |
❌ Disclaimer
MasterDnsVPN is provided as an educational and research project only.
- Provided without warranty: This software is provided “AS-IS”, without any express or implied warranty, including merchantability, fitness for a particular purpose, or non-infringement.
- Limitation of liability: The developers and contributors of this project accept no responsibility for any direct, indirect, incidental, consequential, or other damages arising from the use of this software or the inability to use it.
- User responsibility: Using this project outside test environments may disrupt or damage network behavior. The user alone is responsible for all consequences of installation, configuration, and use.
- Legal compliance: Using this project to bypass local laws may result in civil or criminal consequences. Please review the laws and regulations of your country before use. The developers accept no responsibility for violations of local, national, or international laws by users.
- License terms: Use, copying, distribution, or modification of this software is governed by the license in the
LICENSE file of this repository. Any use outside those terms is prohibited.
Announcement and Support Channel 📢
For the latest news, releases, and project updates, follow our Telegram channel: Telegram Channel
If you like this project, please support it by starring it on GitHub (⭐). It helps the project get discovered.
Optional Financial Support 💸
masterking32.ton
- EVM-compatible networks (ETH and compatible chains):
0x517f07305D6ED781A089322B6cD93d1461bF8652
TLApdY8APWkFHHoxebxGY8JhMeChiETqFH
Every contribution and every piece of feedback is appreciated. Support directly helps ongoing development and improvement.
Key Features and Advantages ✨
A brief overview of the main capabilities of MasterDnsVPN:
- Censorship resistance and harsh-network survivability: 🛡️ Designed to work on filtered networks, unstable links, and strict MTU environments.
- Lightweight custom protocol: 🔄 Uses a custom protocol with retransmission logic to reduce overhead and increase usable DNS payload.
- Multipath and packet duplication: 📡 Sends traffic through multiple paths and supports selective duplication to increase delivery probability on unstable networks.
- Smart resolver selection and health checks: ⚡ Selects resolvers based on quality and health, and manages problematic resolvers automatically.
- MTU discovery and synchronization: 🧰 Detects the practical MTU of working paths and aligns around it to reduce fragmentation and improve stability.
- SOCKS5 / SOCKS4 support and optimization: 🧦 Optimized local proxy handling for common applications.
- Packed control blocks and lower control overhead: 📦 Groups ACK/control traffic together to reduce control chatter.
- Optional compression and request packing: 🗜️ Reduces request counts and improves efficiency under small-MTU conditions.
- Flexible encryption: 🔐 Supports multiple encryption methods to balance speed and security.
- Optional client-side local DNS and caching: 📛 Can expose a local DNS service, reduce latency, and limit hijacking opportunities.
- Scalable resource control: ⚙️ Can run on small servers or be tuned for heavier loads.
This list is only a high-level summary. The related sections below explain each area in more detail.
🌐 Battle-Tested During a Total Internet Blackout
MasterDnsVPN isn't just a theoretical project. It is battle-tested and proven to work in environments where the global internet is completely severed.
Recently, during the 88-day internet blackout in Iran, authorities didn't just block VPNs or filter websites—they completely pulled the plug on international bandwidth. With 99% of the connection to the outside world physically cut off, users were trapped inside a closed, local intranet.
Standard circumvention tools are useless when there is no international internet to connect to. Yet, during this massive shutdown, MasterDnsVPN stood out as one of the very few lifelines that actually kept users connected to the global web.
How did it survive a total shutdown?
Instead of acting like a standard VPN, MasterDnsVPN relies on smart DNS tunneling techniques to pierce through the blackout:
- Multiple Resolvers: It routes traffic through various DNS resolvers, ensuring the connection never relies on a single, easily blockable path.
- Encryption & Data Splitting: It encrypts your data and breaks it down into tiny, scattered pieces.
- Disguised as Legitimate Traffic: It wraps these data pieces inside standard, perfectly normal DNS queries.
- Bypassing Local Traps: Because the traffic looks exactly like basic, everyday DNS requests, firewalls allow it through. The data gets resolved and reaches the outside world—even if the network forces you to use their own restricted, government-controlled local resolvers.
This exact combination is what allowed MasterDnsVPN to maintain a stable connection when the outside world was completely blocked.
Setup and Getting Started 🧑💻
Section 1: 🖥️ Server Setup
Section 1.1: 🌐 Domain Setup and Preparation (Prerequisite)
To receive DNS requests directly on your server, you must delegate a subdomain to it. In short, create two records: one A record that points to your server IP, and one NS record that delegates the tunnel subdomain to that A record.
Step 1.1.1: 🅰️ Create an A Record (Server Address)
- Type:
A
- Name: a short name such as
ns
- Value: your server IPv4 address
Example: ns.example.com -> 1.2.3.4
Cloudflare note: if the domain uses Cloudflare, open the DNS page and click the cloud icon next to the A record so it becomes gray (DNS only). It must not remain proxied.
Step 1.1.2: 🏷️ Create an NS Record (Delegate the Subdomain)
- Type:
NS
- Name: the tunnel subdomain, for example
v
- Value / Target:
ns.example.com
Example: v.example.com -> ns.example.com
Cloudflare note: add the NS record normally. Cloudflare does not proxy NS records, but make sure the ns A record is already set to DNS only.
Section 1.1.3: 💡 A Short Note About MTU
Shorter domain names leave more space for actual data inside each DNS request. For better throughput, keep names short. If you use Cloudflare, still keep the relevant records in DNS only mode.
Section 1.2: 🐧 Quick Linux Server Installation
Step 1.2.1: Automatic Installation (Script)
If you want to deploy the server on Linux, the easiest method is the automatic installer script. Run this command on the server:
bash <(curl -Ls https://raw.githubusercontent.com/masterking32/MasterDnsVPN/main/server_linux_install.sh)
The script handles installation and configuration automatically. When it finishes, the server starts and the encryption key is shown in the terminal log and also written to encrypt_key.txt next to the executable. Keep this key safe.
Step 1.2.2: Important Notes After Installation
- During installation, you will be asked for a domain. It must be the same delegated subdomain you configured in the
NS record, for example v.example.com.
- After creating DNS records, wait for propagation. This may take from a few minutes to several hours, and in some cases up to 48 hours depending on TTL and the DNS provider.
- To verify the DNS setup, you can use tools such as
dig or nslookup, for example dig v.example.com NS or nslookup -type=ns v.example.com. For a direct query to the new nameserver: dig @ns.example.com v.example.com A.
- If the server firewall is enabled, allow UDP port 53. Example for
ufw:
sudo ufw allow 53/udp
sudo ufw reload
For firewalld:
sudo firewall-cmd --add-port=53/udp --permanent
sudo firewall-cmd --reload
- If port
53 is already occupied by another service, such as systemd-resolved, see the troubleshooting section “Fixing Port 53 Already in Use”.
- The encryption key (
encrypt_key.txt) is shown after installation. Copy it and store it safely because the client needs it to connect.
Section 2: 🚀 Installation and Launch (Client and Server)
You can install and run this project in two ways:
- Use the prebuilt binaries (recommended for most users)
- Run directly from source with Go (recommended for developers)
Section 2.1: Use Prebuilt Releases (✅ Recommended)
For convenience, prebuilt client and server binaries are published in the release page. Download the correct archive for your operating system and extract it.
💡 Note: Release archives usually include the binary plus sample configuration files.
Client Download Links 📥
Server Download Links 📤
(Use these if you do not want the automated Linux installer.)
MasterDnsVPN 是一款 DNS 隧道 VPN，它把 TCP 流量藏在 DNS 查询和响应中传输，在常规连接被封锁时帮你上网。它的目标与 DNSTT 或 SlipStream 相同，但采用了自己开销更低的协议。