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

For the latest news, releases, and project updates, follow our Telegram channel: Telegram Channel

• TON network:

masterking32.ton

• EVM-compatible networks (ETH and compatible chains):

0x517f07305D6ED781A089322B6cD93d1461bF8652

• TRC20 network (TRON):

TLApdY8APWkFHHoxebxGY8JhMeChiETqFH

Every contribution and every piece of feedback is appreciated. Support directly helps ongoing development and improvement.

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.

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.

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.

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

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

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.

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.

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

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.

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

This Docker image runs the MasterDnsVPN server in a containerized environment and supports multi-architecture builds.

It automatically:

• Boots a default configuration if none exists
• Injects your domain on first startup
• Stores persistent data in /data

• linux/amd64
• linux/arm/v5
• linux/arm/v7
• linux/arm64/v8
• linux/mips64le

Run the container with Docker:

docker run -d \
  --name masterdnsvpn \
  --restart unless-stopped \
  -e DOMAIN=v.example.com \
  -v $(pwd)/data:/data \
  -p 53:53/tcp \
  -p 53:53/udp \
  ghcr.io/masterking32/masterdnsvpn:latest

services:
  masterdnsvpn:
    image: ghcr.io/masterking32/masterdnsvpn:latest
    restart: unless-stopped
    environment:
      - DOMAIN=v.example.com
    volumes:
      - ./data:/data
    ports:
      - "53:53/tcp"
      - "53:53/udp"

⚠️ If DOMAIN is not set on first boot, the container will stop with an error.

Stored in /data:

• server_config.toml
• encrypt_key.txt

You can mount it as volume:

-v ./data:/data

For MikroTik containers:

• Use latest v7 MikroTik RouterOS
• Destination NAT port UDP/TCP 53 to your container
• Full MikroTik container setup: https://help.mikrotik.com/docs/spaces/ROS/pages/84901929/Container

Example:

/container mounts
add dst=/data list=MasterDnsVPN src=/containers/mounts/MasterDnsVPN

/container envs
add key=DOMAIN list=MasterDnsVPN value=v.example.com

/container add check-certificate=no dns=1.1.1.1 envlists=MasterDnsVPN hostname=MasterDnsVPN interface=MasterDnsVPN layer-dir="" mountlists=MasterDnsVPN name=MasterDnsVPN remote-image=ghcr.io/masterking32/masterdnsvpn:latest root-dir=/containers/data/MasterDnsVPN start-on-boot=yes

• DNS port 53 is required (UDP/TCP)
• Do NOT run another DNS service on the same host
• Designed for production use but still lightweight
• No systemd or host modifications required

• After downloading the Windows package, extract it.
• Open client_config.toml with a text editor such as Notepad.
• Replace the default values with your real domain, encryption key, and resolver list.
• Run the client executable.
• Configure your browser or app to use the local SOCKS5 proxy at 127.0.0.1:18000 unless you changed the defaults.

After downloading the package on Linux:

sudo apt update
sudo apt install unzip nano

Extract the archive:

unzip MasterDnsVPN_Client_Linux_AMD64.zip
ls

Give execute permission if needed:

chmod +x MasterDnsVPN_Client_Linux_AMD64
chmod +x MasterDnsVPN_Server_Linux_AMD64

Edit the configuration:

nano client_config.toml
nano server_config.toml

Then run:

./MasterDnsVPN_Client_Linux_AMD64
./MasterDnsVPN_Server_Linux_AMD64

⚠️ This section is intended for developers or users who want to run the current Go source directly.

• Go 1.24 or newer

git clone https://github.com/masterking32/MasterDnsVPN.git
cd MasterDnsVPN

go build -o masterdnsvpn-client ./cmd/client
go build -o masterdnsvpn-server ./cmd/server

On Windows:

git clone https://github.com/masterking32/MasterDnsVPN.git
cd MasterDnsVPN

go build -o masterdnsvpn-client.exe .\cmd\client
go build -o masterdnsvpn-server.exe .\cmd\server

On Linux and macOS:

cp client_config.toml.simple client_config.toml
cp server_config.toml.simple server_config.toml
cp client_resolvers.simple client_resolvers.txt

On Windows:

Copy-Item client_config.toml.simple client_config.toml
Copy-Item server_config.toml.simple server_config.toml
Copy-Item client_resolvers.simple client_resolvers.txt

./masterdnsvpn-server -config server_config.toml
./masterdnsvpn-client -config client_config.toml

On Windows:

.\masterdnsvpn-server.exe -config server_config.toml
.\masterdnsvpn-client.exe -config client_config.toml

Both binaries support these arguments:

Example:

./masterdnsvpn-server -config server_config.toml -log server.log
./masterdnsvpn-client -config client_config.toml -log client.log

Accepted formats in client_resolvers.txt:

• IP
• IP:PORT
• CIDR
• CIDR:PORT

Example:

8.8.8.8
1.1.1.1:53
9.9.9.0/24
208.67.222.0/24:5353

These items are required on the client:

1. ENCRYPTION_KEY must match the content of the server’s encrypt_key.txt
2. DOMAINS must match the server domain
3. client_resolvers.txt must contain working resolvers
4. For normal use, keep PROTOCOL_TYPE = "SOCKS5"

These settings are critical on the server:

1. Set DOMAIN to your delegated tunnel domain
2. DATA_ENCRYPTION_METHOD must match the client
3. ENCRYPTION_KEY_FILE defines the path to the server key file
4. If you want direct outbound connections, keep USE_EXTERNAL_SOCKS5 = false
5. If you want to chain through an upstream SOCKS5 proxy, set USE_EXTERNAL_SOCKS5 = true and fill FORWARD_IP / FORWARD_PORT

ℹ️ Note: the sample server config contains a key named CONFIG_VERSION, but the current Go code does not read it into ServerConfig. For that reason it is not included in the table below and has no effect on real server behavior.