DOCSEARCHbyAlgolia
Submit Docs

MasterDnsVPN Documentation

repository·main·Indexed 27 days ago

https://github.com/masterking32/masterdnsvpn

A high-performance DNS tunneling project designed to transport TCP traffic through DNS queries to bypass network censorship. Implemented primarily in Go, it features a custom protocol with ARQ, multi-resolver multipath routing, and support for AES, ChaCha20, and XOR encryption. The project provides SOCKS5 support and is optimized for low overhead and high stability in unstable network environments.

Tokens
28.4K
Snippets
32
Records
173
Agent score
88%

What's inside MasterDnsVPN

  1. Overview of MasterDnsVPN

    main

    MasterDnsVPN is a research-oriented project designed to carry TCP traffic through DNS queries and responses. It functions as an advanced DNS tunnel/VPN, similar in goal to projects like DNSTT or SlipStream, but utilizes a custom protocol and ARQ (Automatic Repeat Request) to ensure high stability and data delivery in extremely hostile network environments (e.g., total internet blackouts or heavy censorship).

    Key capabilities include:

    • Censorship Resistance: Designed for filtered networks and strict MTU environments.
    • Custom Lightweight Protocol: Uses a custom protocol with retransmission logic to minimize overhead.
    • Multi-path & Redundancy: Supports sending traffic through multiple paths and selective packet redundancy to improve reliability.
    • Smart Resolver Management: Performs health checks on DNS resolvers and automatically manages or disables problematic ones.
    • MTU Adaptation: Detects and synchronizes with the actual MTU of available paths to reduce fragmentation.
    • Optimized Proxy Support: Includes optimized handling for SOCKS5 and SOCKS4.
    • Flexible Encryption: Supports multiple encryption methods (AES, ChaCha20, XOR) to balance speed and security.
    • Local DNS Services: Provides optional client-side local DNS with caching to reduce latency and prevent hijacking.

  2. Key Features and Advantages of MasterDnsVPN

    main

    MasterDnsVPN is designed for high resilience in censored or unstable network environments. Key capabilities include:

    • Censorship Resistance: Optimized for networks with heavy filtering, unstable connections, and strict MTU constraints.
    • Custom Protocol: Uses a custom protocol with a retransmission mechanism to reduce overhead and increase DNS data throughput.
    • Multipath & Packet Duplication: Supports transmitting traffic over multiple routes and selective packet duplication to improve delivery probability in unstable networks.
    • Smart Resolver Management: Automatically selects and manages DNS resolvers based on quality and availability.
    • MTU Optimization: Detects actual MTU sizes of working routes and synchronizes with them to minimize fragmentation.
    • Proxy Support: Optimized SOCKS5 and SOCKS4 support for local application proxying.
    • Control Plane Efficiency: Combines ACK packets and control traffic to reduce the number of control messages.
    • Compression & Packing: Optional request compression and packing to improve efficiency under low MTU conditions.
    • Flexible Encryption: Supports multiple encryption methods to balance speed and security.
    • Client-side DNS & Caching: Provides local DNS services to reduce latency and limit interception capabilities.
    • Scalability: Configurable to run on small servers or scale for high-load environments.

  3. Understand MasterDnsVPN System Architecture

    main

    MasterDnsVPN is designed to bypass typical tunnel limitations by combining Session Multiplexing, Resolver Balancing, Packet Duplication, a custom ARQ (Automatic Repeat Request) layer, and a Deferred Session Runtime over UDP/DNS.

    Core Concepts

    • Session: A global connection between the client and the server.
    • Stream: An independent logical connection transported within a session.
    • Resolver Runtime: Handles resolver selection, duplication, health tracking, automatic deactivation, and review.
    • ARQ: Manages ordering, ACKs, retransmission, timeouts, and terminal management.
    • Deferred Session Runtime: Manages order-sensitive tasks such as configuration, DNS query management, and sensitive packet flows.
    • Packed Control Blocks: Groups multiple small ACK or control packets into a single block.
    • Synced MTU: A shared MTU value chosen across the entire pool of healthy resolvers.

  4. Related Community Projects

    main

    The following community-driven projects are available for use with MasterDnsVPN:

    • MDV HN Edition Android Client: Android application for connecting to MasterDnsVPN servers (by Hidden Node).
    • MasterDnsVPN GG Android Client: Another Android client (by RevocGG).
    • Persian Config Builder for MasterDnsVPN: A web-based tool for creating configuration files with a Persian interface (by datacoder-io).
    • MasterDnsWeb: A web management client for managing one or multiple MasterDnsVPN instances (by Abolix).
    • KevinNet DNS: A tool to find and verify DNS resolvers, generating ready-to-use configuration files and performing end-to-end tunnel checks (by Kevin Haji).

  5. Understand the MasterDnsVPN System Architecture

    main

    MasterDnsVPN operates by tunneling traffic over UDP/DNS to bypass standard tunnel limitations. The architecture consists of three main layers:

    1. Client Side: Applications connect via a local SOCKS5/TCP proxy or Local DNS. The client manages a ResolverRuntime (for balancing and duplication) and a ClientARQ (for reordering and session management).
    2. Public DNS Network: Acts as the transport layer using multiple DNS Resolvers (R1, R2, ... RN).
    3. Server Side: A remote server listens via UDP, manages sessions via a Session Store, handles ARQ (Automatic Repeat Request), and connects to the final target via direct dial or an external SOCKS5 proxy.

    This design allows for packet duplication and resolver balancing to ensure connectivity even during severe network instability.

  6. Key Features of MasterDnsVPN

    main

    MasterDnsVPN is designed for high-performance DNS tunneling in censored or unstable network environments. Key capabilities include:

    • Censorship Circumvention: Optimized for networks with heavy filtering, outages, and MTU restrictions.
    • Lightweight Protocol: Custom protocol with retransmission mechanisms to minimize overhead and maximize DNS data capacity.
    • Multipath & Packet Replication: Simultaneous transmission across multiple paths and selective replication to increase delivery success in unstable networks.
    • Intelligent Resolver Management: Automatic selection and health monitoring of resolvers based on quality.
    • MTU Discovery & Sync: Detects operational path MTU to reduce fragmentation and improve stability.
    • SOCKS5/SOCKS4 Support: Optimized local proxy traffic routing.
    • Control Overhead Reduction: Aggregates ACKs and control messages into single packets.
    • Optional Compression: Reduces request count and increases efficiency in low-MTU environments.
    • Flexible Encryption: Supports multiple algorithms to balance speed and security.
    • Client-side DNS Caching: Provides local DNS to reduce latency and prevent hijacking.

  7. Optimize MTU settings for performance and stability

    main

    MTU (Maximum Transmission Unit) settings significantly impact the connection.

    • High MTU: Increases address resolution failures, increases startup time, and increases fragmentation/packet loss.
    • Low MTU: Decreases speed but increases stability.

    Optimization Workflow:

    1. Start with the example configuration.
    2. Let the client test the resolvers.
    3. Analyze the MTU results and the number of working resolvers.
    4. If connection quality is low, slightly decrease MIN_UPLOAD_MTU and MIN_DOWNLOAD_MTU.
    5. If you need faster startup, narrow the MIN/MAX MTU range and reduce the difference between them.

  8. Server setup checklist

    main

    To ensure the server is correctly configured, verify the following parameters:

    1. DOMAIN: Set this to your delegated tunnel domain.
    2. DATA_ENCRYPTION_METHOD: Must match the client's configuration.
    3. ENCRYPTION_KEY_FILE: Specifies the path to the key file on the server.
    4. USE_EXTERNAL_SOCKS5:
      • Set to false for direct outbound connections.
      • Set to true if you require chaining through an external SOCKS5 proxy.
    5. FORWARD_IP and FORWARD_PORT: Required if USE_EXTERNAL_SOCKS5 is set to true.

  9. Run MasterDnsVPN Client/Server on Linux or macOS

    main
    1. Install dependencies if needed: sudo apt update && sudo apt install unzip nano.
    2. Unzip the package: unzip <package_name>.zip.
    3. Grant execution permissions: chmod +x <binary_name>.
    4. Edit configuration files: nano client_config.toml or nano server_config.toml.
    5. Run the binaries: ./MasterDnsVPN_Client_Linux_AMD64 or ./MasterDnsVPN_Server_Linux_AMD64.

  10. Prepare Domain Delegation for Server Setup

    main

    To receive direct DNS requests on your server, you must delegate a subdomain to your server by creating two DNS records:

    1. Create an A Record (Server Address):

      • Type: A
      • Name: A short name (e.g., ns)
      • Value: Your server's IPv4 address
      • Example: ns.example.com -> 1.2.3.4
      • Cloudflare Note: Ensure the record is set to DNS only (grey cloud). Do not use Proxied (orange cloud).

    2. Create an NS Record (Subdomain Delegation):

      • Type: NS
      • Name: The tunnel subdomain (e.g., v)
      • Target: The A record name created in step 1 (e.g., ns.example.com)
      • Example: v.example.com -> ns.example.com

    Optimization Tip: Use shorter domain names to leave more space for data in each DNS request, which improves throughput. If using Cloudflare, keep records as DNS only.

  11. Run MasterDnsVPN Client on Windows

    main
    1. Unzip the downloaded Windows package.
    2. Open client_config.toml in a text editor (e.g., Notepad).
    3. Replace default values with your actual domain, encryption key, and resolver list.
    4. Run the client executable.
    5. Configure your browser or applications to use the local SOCKS5 proxy at 127.0.0.1:18000.

  12. Setup and Run MasterDnsVPN Client on Windows

    main
    1. Download and extract the Windows package.
    2. Open client_config.toml in a text editor (e.g., Notepad).
    3. Replace default values with your actual domain, encryption key, and resolver list.
    4. Run the client executable.
    5. Configure your browser or application to use the local SOCKS5 proxy at 127.0.0.1:18000 (unless you modified the default port in the config).