DNS Tunnel Manager (dnstm)

A CLI tool to deploy and manage DNS tunnel servers on Linux. Run single tunnels or scale with the built-in DNS router for multi-tunnel setups. Configure via interactive menu, CLI commands, or config files with auto-generated certificates and keys.

Supported Transports

Transport	Description
VayDNS	Next-gen DNS tunnel with Curve25519 keys and KCP
DNSTT	Classic DNS tunnel using Curve25519 keys
Slipstream	High-performance DNS tunnel with TLS encryption

Supported Backends

Backend	Description	Transports
SOCKS	Built-in microsocks SOCKS5 proxy	Slipstream, DNSTT, VayDNS
SSH	Forward to local SSH server	Slipstream, DNSTT, VayDNS
Shadowsocks	Encrypted proxy via SIP003 plugin	Slipstream only
Custom	Forward to any TCP address	Slipstream, DNSTT, VayDNS

Features

• Two operating modes: single-tunnel and multi-tunnel (DNS router)
• Interactive menu and full CLI support
• Auto-generated TLS certificates (Slipstream) and Curve25519 keys (DNSTT, VayDNS)
• Shareable dnst:// URLs for easy client setup (tunnel share)
• Firewall configuration (UFW, firewalld, iptables)
• systemd service management with security hardening
• SSH tunnel user management with sshd hardening
• Integrated microsocks SOCKS5 proxy with optional authentication

System Overview

flowchart TB
    subgraph Client
        C[DNS Client]
    end

    subgraph "DNS Resolver"
        R[Public DNS<br/>1.1.1.1 / 8.8.8.8]
    end

    subgraph Server["dnstm Server"]
        subgraph SingleMode["Single-Tunnel Mode"]
            T1[Active Transport<br/>:53]
        end

        subgraph MultiMode["Multi-Tunnel Mode"]
            DR[DNS Router<br/>:53]
            T2[Transport 1<br/>:5310]
            T3[Transport 2<br/>:5311]
            T4[Transport N<br/>:531N]
        end

        subgraph Backends["Backends"]
            SSH[SSH Server<br/>:22]
            SOCKS[microsocks<br/>SOCKS5]
            SS[Shadowsocks]
            CUSTOM[Custom]
        end
    end

    C -->|DNS Queries| R
    R -->|UDP/TCP :53| T1
    R -->|UDP/TCP :53| DR

    DR --> T2
    DR --> T3
    DR --> T4

    T1 --> Backends
    T2 --> Backends
    T3 --> Backends
    T4 --> Backends

Loading

Quick Start

DNS Setup

Configure NS records pointing to your server:

ns.example.com.  IN  A   YOUR_SERVER_IP
t.example.com.   IN  NS  ns.example.com.

Concepts

• Backend: Where traffic goes after decapsulation (socks, ssh, shadowsocks, custom)
• Transport: DNS tunnel protocol (slipstream, dnstt, or vaydns)
• Tunnel: A transport + backend + domain combination

Note: Slipstream + Shadowsocks uses SIP003 plugin mode - the shadowsocks server runs as a plugin to slipstream, providing encrypted tunneling. This requires defining a shadowsocks backend instead of using the built-in socks proxy. DNSTT and VayDNS do not support Shadowsocks backends.

Install

curl -sSL https://raw.githubusercontent.com/net2share/dnstm/main/install.sh | sudo bash

Configuration Methods

1. Interactive Menu

sudo dnstm
# Navigate: Tunnels → Add

2. CLI Commands

# Add slipstream + socks tunnel
sudo dnstm tunnel add -t slip-socks --transport slipstream --backend socks --domain t1.example.com

# Configure SOCKS5 authentication (optional)
sudo dnstm backend auth -t socks --user myuser --password mypass

# Add dnstt + ssh tunnel
sudo dnstm tunnel add -t dnstt-ssh --transport dnstt --backend ssh --domain t2.example.com

# Add slipstream + shadowsocks tunnel (creates shadowsocks backend automatically)
sudo dnstm backend add -t my-ss --type shadowsocks --password mypass123 --method aes-256-gcm
sudo dnstm tunnel add -t slip-ss --transport slipstream --backend my-ss --domain t3.example.com

# Add vaydns + socks tunnel
sudo dnstm tunnel add -t vaydns-socks --transport vaydns --backend socks --domain t4.example.com

# Add vaydns tunnel with dnstt-compatible wire format
sudo dnstm tunnel add -t vaydns-compat --transport vaydns --backend socks --domain t5.example.com --dnstt-compat

# Add slipstream + custom backend (e.g., MTProto proxy)
sudo dnstm backend add -t mtproto --type custom --address 127.0.0.1:8443
sudo dnstm tunnel add -t slip-mtproto --transport slipstream --backend mtproto --domain t6.example.com

3. Config File

sudo dnstm config load config.json

Example config.json (certs/keys auto-generated when paths are omitted):

{
  "backends": [
    {
      "tag": "socks",
      "type": "socks",
      "socks": {
        "user": "myuser",
        "password": "mypass"
      }
    },
    {
      "tag": "my-ss",
      "type": "shadowsocks",
      "shadowsocks": {
        "password": "mypass123",
        "method": "aes-256-gcm"
      }
    },
    {
      "tag": "mtproto",
      "type": "custom",
      "address": "127.0.0.1:8443"
    }
  ],
  "tunnels": [
    {
      "tag": "slip-socks",
      "transport": "slipstream",
      "backend": "socks",
      "domain": "t1.example.com",
      "port": 5310,
      "slipstream": {
        "cert": "/path/to/cert.pem",
        "key": "/path/to/key.pem"
      }
    },
    {
      "tag": "slip-ss",
      "transport": "slipstream",
      "backend": "my-ss",
      "domain": "t2.example.com",
      "port": 5311
    },
    {
      "tag": "dnstt-ssh",
      "transport": "dnstt",
      "backend": "ssh",
      "domain": "t3.example.com",
      "port": 5312,
      "dnstt": {
        "mtu": 1232
      }
    },
    {
      "tag": "vaydns-socks",
      "transport": "vaydns",
      "backend": "socks",
      "domain": "t4.example.com",
      "port": 5313,
      "vaydns": {
        "mtu": 1232,
        "idle_timeout": "10s",
        "keep_alive": "2s",
        "clientid_size": 2,
        "queue_size": 512,
        "record_type": "txt"
      }
    },
    {
      "tag": "vaydns-compat",
      "transport": "vaydns",
      "backend": "ssh",
      "domain": "t5.example.com",
      "port": 5314,
      "vaydns": {
        "dnstt_compat": true,
        "mtu": 1232
      }
    },
    {
      "tag": "slip-mtproto",
      "transport": "slipstream",
      "backend": "mtproto",
      "domain": "t6.example.com",
      "port": 5315
    }
  ],
  "route": {
    "mode": "multi",
    "default": "slip-socks"
  }
}

Share with Client

Generate a dnst:// URL to share tunnel configuration with dnstc:

# SOCKS or Shadowsocks tunnel
sudo dnstm tunnel share -t slip-socks

# SSH tunnel (requires credentials)
sudo dnstm tunnel share -t dnstt-ssh --user tunnel-user --password secret

Common Commands

sudo dnstm router status          # View router and tunnel status
sudo dnstm tunnel list            # List all tunnels
sudo dnstm tunnel share -t <tag>  # Generate shareable client config URL
sudo dnstm tunnel logs -t <tag>   # View tunnel logs
sudo dnstm router logs            # View router logs (multi-mode)
sudo dnstm update                 # Check for and install updates
sudo dnstm uninstall              # Remove all components

See CLI Reference for all available flags and options.

Operating Modes

Single-Tunnel Mode (Default)

One tunnel active at a time. The active transport binds directly to port 53.

sudo dnstm router mode single
sudo dnstm router switch -t <tag>

Multi-Tunnel Mode

All tunnels run simultaneously. DNS router handles domain-based routing.

Note: Multi-mode overhead is typically minimal. Performance varies by transport and connection method. See Benchmarks for details.

sudo dnstm router mode multi

Documentation

• Architecture - System design and operating modes
• CLI Reference - Complete command reference
• Configuration - Configuration files and options
• Client Setup - Client-side connection guides
• Development - Action-based architecture and adding commands
• Testing - Testing guide and remote test setup
• Benchmarks - Performance benchmarks

Requirements

• Linux (Debian/Ubuntu, RHEL/CentOS/Fedora)
• Root access
• systemd
• Domain with NS records pointing to your server

Building from Source

git clone https://github.com/net2share/dnstm.git
cd dnstm
go build -o dnstm .