MasterDnsVPN README

The project's README from github.com/masterking32/MasterDnsVPN. As one markdown file: README.md.

MasterDnsVPN Project 🔐

| 🇮🇷 فارسی | 🇬🇧 English | 🇷🇺 Русский | 🇨🇳 中文 | 🇪🇸 Español | 🇮🇹 Italiano |

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.

Ask DeepWiki

masterking32%2FMasterDnsVPN | Trendshift masterking32%2FMasterDnsVPN | Trendshift masterking32%2FMasterDnsVPN | Trendshift masterking32%2FMasterDnsVPN | Trendshift MasterDnsVPN | SourceForge

📊 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.


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

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:

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:

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)

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)

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

sudo ufw allow 53/udp
sudo ufw reload

For firewalld:

sudo firewall-cmd --add-port=53/udp --permanent
sudo firewall-cmd --reload

Section 2: 🚀 Installation and Launch (Client and Server)

You can install and run this project in two ways:

  1. Use the prebuilt binaries (recommended for most users)
  2. Run directly from source with Go (recommended for developers)

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.

Operating System Architecture Suitable For Direct Download
Windows 🪟 AMD64 (64-bit) Windows 10 and 11 Download Windows Client ⬇️
Windows 🪟 x86 (32-bit) Older 32-bit Windows systems Download Windows x86 Client ⬇️
Windows 🪟 ARM64 Windows on ARM devices Download Windows ARM64 Client ⬇️
macOS 🍎 ARM64 Apple Silicon Macs (M1 / M2 / M3) Download macOS Client ⬇️
macOS 🍎 AMD64 Intel Macs Download macOS Intel Client ⬇️
Linux 🐧 AMD64 (64-bit) Modern distributions (Ubuntu 22.04+, Debian 12+) Download Linux Client ⬇️
Linux 🐧 x86 (32-bit) Older 32-bit Linux systems Download Linux x86 Client ⬇️
Linux (Legacy) 🐧 AMD64 (64-bit) Older distributions (Ubuntu 20.04, Debian 11) Download Linux Legacy Client ⬇️
Linux (Legacy) 🐧 ARM64 Older ARM64 Linux systems that need broader compatibility Download Linux Legacy ARM64 Client ⬇️
Linux (ARM) 🐧 ARM64 ARM servers, Raspberry Pi, and similar boards Download Linux ARM Client ⬇️
Linux (ARM) 🐧 ARMv7 32-bit ARM boards and older embedded Linux devices Download Linux ARMv7 Client ⬇️
Linux (ARM) 🐧 ARMv6 Older ARM boards and lightweight Linux devices Download Linux ARMv6 Client ⬇️
Linux (ARM) 🐧 ARMv5 Very old ARM devices and embedded Linux systems Download Linux ARMv5 Client ⬇️
Linux 🐧 RISCV64 RISC-V Linux boards and servers Download Linux RISCV64 Client ⬇️
Linux (MIPS) 🐧 MIPS Big-endian MIPS Linux and router platforms Download Linux MIPS Client ⬇️
Linux (MIPS) 🐧 MIPSLE Little-endian MIPS Linux and router platforms Download Linux MIPSLE Client ⬇️
Linux (MIPS) 🐧 MIPS64 64-bit big-endian MIPS Linux systems Download Linux MIPS64 Client ⬇️
Linux (MIPS) 🐧 MIPS64LE 64-bit little-endian MIPS Linux systems Download Linux MIPS64LE Client ⬇️
Termux / Android 📱 ARM64 Modern Android phones running Termux Download Termux ARM64 Client ⬇️
Termux / Android 📱 ARMv7 Older Android phones running 32-bit Termux environments Download Termux ARMv7 Client ⬇️

(Use these if you do not want the automated Linux installer.)

Operating System Architecture Suitable For Direct Download
Windows 🪟 AMD64 (64-bit) Windows Server, Windows 10 and 11 Download Windows Server ⬇️
Windows 🪟 x86 (32-bit) Older 32-bit Windows systems Download Windows x86 Server ⬇️
Windows 🪟 ARM64 Windows on ARM devices [Download Windows ARM64 Server ⬇️](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Server_W

MasterDnsVPN (masterking32/MasterDnsVPN)

Searching Database…

Что это такое?MasterDnsVPN — это VPN с DNS-туннелированием: он передаёт TCP-трафик внутри DNS-запросов и ответов, чтобы выйти в интернет, когда обычные соединения заблокированы. Цель та же, что у DNSTT или SlipStream, но он использует собственный протокол с меньшими накладными расходами.
Это VPN-приложение или сетевая библиотека?Это самостоятельный инструмент «клиент/сервер», который распространяется в виде готовых исполняемых файлов для Windows и Linux. Это не библиотека для подключения в коде: вы запускаете исполняемые файлы сервера и клиента напрямую или собираете их сами с помощью Go.
Как его запустить?Сначала делегируйте поддомен на свой сервер, добавив запись A и запись NS, затем запустите на сервере скрипт автоматической установки для Linux: он всё настроит и выведет ключ шифрования. Наконец, скачайте клиент, подходящий для вашей ОС, и подключитесь с помощью этого ключа.
Нужны ли мне собственный домен и DNS-записи, чтобы им пользоваться?Да, нужно владеть доменом и делегировать туннельный поддомен на свой сервер через запись A и запись NS, прежде чем сервер сможет принимать DNS-трафик. Сборка из исходников вместо готовых исполняемых файлов дополнительно требует Go.
Какие есть подводные камни при настройке?После создания записей их распространение может занять от нескольких минут до 48 часов — в зависимости от TTL и провайдера. Если UDP-порт 53 уже занят, например службой systemd-resolved, его нужно освободить, прежде чем сервер сможет его использовать.
На каких платформах работает клиент?Готовые клиентские исполняемые файлы есть для Windows 10/11 в 64-битной и 32-битной версиях. Сервер в основном разворачивается на Linux с помощью скрипта установки, а для других платформ доступна сборка из исходников на Go.
Оно шифрует мой трафик?Да, поддерживается несколько методов шифрования: AES и ChaCha20 для безопасности, а также необязательный облегчённый режим XOR, который жертвует безопасностью ради меньших накладных расходов.
Насколько он быстрее DNSTT и SlipStream?Авторы проекта заявляют, что загрузки могут быть примерно в 9 раз быстрее, чем у DNSTT, и в 3,6 раза быстрее, чем у SlipStream, а служебных заголовков протокола примерно на 88% меньше, чем у DNSTT, благодаря собственному транспорту на основе ARQ.
Он реально работал во время настоящей цензуры?Да, в README сказано, что его использовали во время 88-дневного полного отключения интернета в Иране, когда международный канал был физически перерезан. Он остаётся одним из немногих инструментов, способных маскировать трафик под обычные DNS-запросы и выходить во внешний мир.
Что на самом деле делает балансировка между DNS-резолверами?Она распределяет трафик между несколькими DNS-резолверами, используя 8 встроенных режимов балансировки. Она проверяет их работоспособность и автоматически отключает неисправные, а когда они восстанавливаются, в фоновом режиме возвращает их в работу.
Может ли он передавать другие прокси-протоколы, например Shadowsocks или VLESS?Косвенно да: режим TCP Forwarding может туннелировать через DNS-канал любой протокол на основе TCP, включая Shadowsocks, VLESS или VMess.
Size
3.5 MB
Stars
7.1K
Age
8mo
Commits · 90 Days