Interactive DNS Tunnel Setup Wizard — automated server deployment for unrestricted internet access.

Deploys dnstm DNS tunnel servers with Slipstream and DNSTT protocols. Designed to help people in restricted regions stay connected to the free internet.

• 🔍 How DNS Tunneling Works
• 🏗️ Architecture
• 📦 What Gets Installed
• ✅ Prerequisites
• 🚀 Quick Start
• 📋 Setup Steps Explained
• 🌍 DNS Records Guide
• ⌨️ Usage
• ❓ In-TUI Help System
• 📱 Client Apps
• 🛠️ Management Commands
• 🗑️ Uninstall
• 📖 Manual Setup Guide
• 🔧 Troubleshooting
• 🙏 Acknowledgments
• 🔗 Related Projects
• 💖 Donate
• 📄 License
• 👤 Author
• 📖 راهنمای فارسی

DNS (Domain Name System) is the internet's phone book — every device on the planet needs it to work. DNS tunneling encodes your internet traffic inside DNS queries and responses.

💡 Why DNS? Censors can block VPNs, Tor, and direct connections, but they almost never block DNS because doing so would break the internet for everyone. Even during total internet shutdowns, DNS queries often still work through ISP resolvers.

How it works:

1. 📱 Your phone (running SlipNet) encodes internet traffic as DNS queries
2. 🔒 These queries look like normal DNS lookups (e.g., abc123.t2.yourdomain.com)
3. 🌍 The queries travel through public DNS resolvers (Google 8.8.8.8, Cloudflare 1.1.1.1, etc.)
4. 🖥️ Your server receives the queries, decodes the hidden data, and forwards it to the real internet
5. ↩️ Responses travel back the same way, encoded inside DNS responses

Because the traffic looks like ordinary DNS resolution, it passes through filters undetected.

  📱 Phone (SlipNet App)
     |
     | DNS queries (encoded traffic)
     v
  🌍 Public DNS Resolver (8.8.8.8 / 1.1.1.1 / 9.9.9.9)
     |
     | DNS delegation (NS records point to your server)
     v
  🖥️ Your Server — Port 53
     |
     v
  🔀 DNS Router (multiplexes port 53)
     |
     +---> t2.domain ---> Slipstream ---> microsocks (SOCKS5) ---> 🌐 Internet
     |                    (QUIC + TLS)
     |
     +---> d2.domain ---> DNSTT --------> microsocks (SOCKS5) ---> 🌐 Internet
     |                    (Noise + Curve25519)
     |
     +---> s2.domain ---> Slipstream ---> SSH Tunnel ------------> 🌐 Internet
     |                    (QUIC + TLS)   (port forwarding)
     |
     +---> ds2.domain --> DNSTT --------> SSH Tunnel ------------> 🌐 Internet
                          (Noise + Curve25519) (port forwarding)

When someone queries t2.yourdomain.com, the global DNS system follows this chain:

1. Client asks its resolver: "What is xyz.t2.yourdomain.com?"
2. Resolver asks Cloudflare (your domain's nameserver): "What is t2.yourdomain.com?"
3. Cloudflare sees the NS record: "For t2.yourdomain.com, ask ns.yourdomain.com"
4. Cloudflare sees the A record: "ns.yourdomain.com is at <your server IP>"
5. Resolver sends the query directly to your server on port 53
6. Your server's DNS Router receives it and routes to the correct tunnel

This is why you need both an A record (telling the internet where your server is) and NS records (delegating subdomains to your server).

🧦 SOCKS backend: Anyone who knows the domain can connect. Simpler, faster, no login required.

🔑 SSH backend: Requires username + password. Provides per-user access control. The SSH user is restricted — even if credentials leak, no one can access your server.

Before running the script, you need:

• Running Ubuntu or Debian (tested on Ubuntu 20.04 / 22.04 / 24.04)
• Root access (SSH as root or sudo)
• Public IPv4 address
• Port 53 (UDP + TCP) open in any external firewall / hosting provider panel

• Any domain works (cheap TLDs like .live, .xyz are fine)
• The domain must use Cloudflare DNS (free plan) to manage records
• You can buy domains from Namecheap, Cloudflare Registrar, or any registrar

• Usually pre-installed on Ubuntu/Debian
• If missing, the script will offer to install it for you

SSH into your server as root, then:

curl -fsSL -o dnstm-setup.sh https://raw.githubusercontent.com/SamNet-dev/dnstm-setup/master/dnstm-setup.sh
sudo bash dnstm-setup.sh

💡 Tip: Press h at any prompt for detailed help on that step.

Already set up? Add another domain to the same server as a fallback:

sudo bash dnstm-setup.sh --add-domain

This creates a new set of tunnels on the same server with a different domain. If one domain gets blocked, the other still works.

The wizard has 12 steps. Here's what each one does:

Create these records in your Cloudflare dashboard:

☝️ This tells the internet: "ns.yourdomain.com is at this IP address."

☝️ These tell the internet: "For queries about t2/d2/s2/ds2.yourdomain.com, ask ns.yourdomain.com (your server)."

# 🚀 Run the interactive setup wizard
sudo bash dnstm-setup.sh

# 🗑️ Remove all installed components
sudo bash dnstm-setup.sh --uninstall

# ❓ Show help (no root needed)
bash dnstm-setup.sh --help

# ℹ️ Show project information (no root needed)
bash dnstm-setup.sh --about

Press h at any prompt during the interactive setup to open the help menu:

  ┌──────────────────────────────────────────────────────────┐
  │ Help — Pick a Topic                                      │
  └──────────────────────────────────────────────────────────┘

  1  Domains & DNS Basics
  2  DNS Records (Cloudflare Setup)
  3  Port 53 & systemd-resolved
  4  dnstm — DNS Tunnel Manager
  5  SSH Tunnel Users
  6  Architecture & How It Works

  ────────────────────────────────────────
  7  About

  Pick a topic (1-7) or Enter to go back:

Each topic gives deep explanations of how things work, why each step is needed, and what the terminology means. Browse multiple topics and return to the setup prompt when ready.

SlipNet supports both Slipstream and DNSTT tunnels.

📥 Download: https://github.com/anonvector/SlipNet/releases

HTTP Injector supports DNSTT tunnels (the d2 subdomain). Slipstream is not supported on iOS.

📥 Download: App Store

⚠️ iOS users can only use the DNSTT tunnel (d2 subdomain). Slipstream tunnels (t2/s2) are Android-only via SlipNet.

💡 Try different resolvers if one doesn't work in your region. Some ISPs may block specific resolvers.

After setup, manage your tunnels with these commands:

# 📋 View all tunnels and their status
dnstm tunnel list

# 📊 Check DNS Router status
dnstm router status

# 📜 View DNS Router logs
dnstm router logs

# 🔍 View logs for a specific tunnel
dnstm tunnel logs --tag slip1
dnstm tunnel logs --tag dnstt1
dnstm tunnel logs --tag slip-ssh

# ⏹️ Stop / ▶️ Start a specific tunnel
dnstm tunnel stop --tag slip1
dnstm tunnel start --tag slip1

# 🔀 Stop / Start the DNS Router
dnstm router stop
dnstm router start

# 🧪 Test the SOCKS proxy locally (check port with: ss -tlnp | grep microsocks)
curl --socks5 127.0.0.1:<MICROSOCKS_PORT> https://api.ipify.org

To remove everything installed by this script:

sudo bash dnstm-setup.sh --uninstall

Removes:

• ✅ All dnstm tunnels and the DNS Router
• ✅ dnstm binary and /etc/dnstm configuration
• ✅ sshtun-user binary (if installed)
• ✅ microsocks service

Not removed (must be done manually):

• ⚠️ DNS records in Cloudflare — delete them from your dashboard
• ⚠️ systemd-resolved — re-enable with:

  chattr -i /etc/resolv.conf 2>/dev/null
  rm /etc/resolv.conf && ln -s ../run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
  systemctl unmask systemd-resolved.socket systemd-resolved.service
  systemctl enable systemd-resolved && systemctl start systemd-resolved
  

If you prefer to set things up manually step by step (without this script), follow the complete manual guide:

📝 Complete Guide to Setting Up a DNS Tunnel (Farsi)

# Check what's using port 53
ss -ulnp | grep ':53 '

# If systemd-resolved is still there, force it (stop socket too!)
systemctl stop systemd-resolved.socket systemd-resolved.service
systemctl disable systemd-resolved.socket systemd-resolved.service
systemctl mask systemd-resolved.socket systemd-resolved.service
pkill -9 systemd-resolve
# Fix resolv.conf (remove symlink, write real file, lock it)
chattr -i /etc/resolv.conf 2>/dev/null; rm -f /etc/resolv.conf
echo "nameserver 8.8.8.8" > /etc/resolv.conf
chattr +i /etc/resolv.conf

# Check tunnel status
dnstm tunnel list

# Check logs for errors
dnstm tunnel logs --tag slip1
dnstm router logs

# Try restarting
dnstm router stop
dnstm router start
dnstm tunnel start --tag slip1

# Check if microsocks is running
systemctl status microsocks

# Restart it
systemctl restart microsocks

# Test locally (check port with: ss -tlnp | grep microsocks)
curl --socks5 127.0.0.1:<MICROSOCKS_PORT> https://api.ipify.org

This project builds on the incredible work of these open-source projects:

Thank you to David Fifield and EndPositive for making internet freedom possible through their research and open-source contributions. 🫡

If this project helps you or someone you know access the free internet, consider supporting continued development:

MIT

Made By SamNet Technologies — Saman

🔗 https://github.com/SamNet-dev

  📱 گوشی (اپلیکیشن SlipNet)
     |
     | درخواست‌های DNS (ترافیک رمزگذاری شده)
     v
  🌍 DNS Resolver عمومی (8.8.8.8 / 1.1.1.1)
     |
     v
  🖥️ سرور شما — پورت 53
     |
     v
  🔀 DNS Router (مالتی‌پلکسر)
     |
     +---> t2.domain  ---> Slipstream ---> microsocks (SOCKS5) ---> 🌐 اینترنت
     +---> d2.domain  ---> DNSTT --------> microsocks (SOCKS5) ---> 🌐 اینترنت
     +---> s2.domain  ---> Slip+SSH -----> تانل SSH --------------> 🌐 اینترنت
     +---> ds2.domain --> DNSTT+SSH ----> تانل SSH --------------> 🌐 اینترنت

curl -fsSL -o dnstm-setup.sh https://raw.githubusercontent.com/SamNet-dev/dnstm-setup/master/dnstm-setup.sh
sudo bash dnstm-setup.sh

sudo bash dnstm-setup.sh --add-domain

# 📋 نمایش تمام تانل‌ها و وضعیت آنها
dnstm tunnel list

# 📊 بررسی وضعیت روتر
dnstm router status

# 📜 مشاهده لاگ‌های روتر
dnstm router logs

# 🔍 مشاهده لاگ تانل خاص
dnstm tunnel logs --tag slip1

# ⏹️ توقف / ▶️ شروع یک تانل
dnstm tunnel stop --tag slip1
dnstm tunnel start --tag slip1

# 🧪 تست پروکسی SOCKS (بررسی پورت: ss -tlnp | grep microsocks)
curl --socks5 127.0.0.1:<MICROSOCKS_PORT> https://api.ipify.org

ss -ulnp | grep ':53 '
systemctl stop systemd-resolved.socket systemd-resolved.service
systemctl mask systemd-resolved.socket systemd-resolved.service
pkill -9 systemd-resolve
chattr -i /etc/resolv.conf 2>/dev/null; rm -f /etc/resolv.conf
echo "nameserver 8.8.8.8" > /etc/resolv.conf
chattr +i /etc/resolv.conf

dnstm tunnel list
dnstm tunnel logs --tag slip1
dnstm router logs

sudo bash dnstm-setup.sh --uninstall

chattr -i /etc/resolv.conf 2>/dev/null
rm /etc/resolv.conf && ln -s ../run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
systemctl unmask systemd-resolved.socket systemd-resolved.service
systemctl enable systemd-resolved && systemctl start systemd-resolved