Client Setup

April 2, 2026 · View on GitHub

Quick Setup with dnstc

The easiest way to connect is using dnstc (DNS Tunnel Client). Generate a shareable URL on the server and import it on the client:

# On the server — generate a shareable URL
sudo dnstm tunnel share -t my-tunnel

# For SSH backend tunnels, include credentials
sudo dnstm tunnel share -t my-tunnel --user tunnel-user --password secret

This outputs a dnst:// URL containing all connection info (transport, domain, certificates/keys, backend credentials).

# On the client — import and connect
dnstc tunnel import dnst://...
dnstc up

Manual Setup

For manual client setup without dnstc, follow the sections below.

Prerequisites

Download client binaries:

Connection Info

Get connection details from the server:

dnstm tunnel status <name>

This shows:

  • Domain
  • Port
  • Certificate fingerprint (Slipstream)
  • Public key (DNSTT, VayDNS)
  • Password and method (Shadowsocks)

Certificate/Key Files

Certificate and key files are stored per-tunnel on the server:

  • Slipstream certificates: /etc/dnstm/tunnels/<tag>/cert.pem
  • DNSTT public keys: /etc/dnstm/tunnels/<tag>/server.pub
  • VayDNS public keys: /etc/dnstm/tunnels/<tag>/server.pub

Slipstream + Shadowsocks

1. Get Connection Info

# On server
dnstm tunnel status <name>

Note the domain, password, and encryption method.

2. Copy Certificate

scp root@server:/etc/dnstm/tunnels/<tag>/cert.pem ./cert.pem

3. Start Tunnel and Connect

# Start slipstream tunnel (creates local TCP port)
slipstream-client -d DOMAIN -r 8.8.8.8:53 --cert cert.pem -l 5201 &

# Connect sslocal through the tunnel
sslocal -s 127.0.0.1:5201 -k "PASSWORD" -m METHOD -b 127.0.0.1:1080

4. Test

curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

Slipstream SOCKS

1. Copy Certificate

scp root@server:/etc/dnstm/tunnels/<tag>/cert.pem ./cert.pem

2. Connect

slipstream-client -d DOMAIN -r 8.8.8.8:53 --cert cert.pem -l 1080

The tunnel acts directly as a SOCKS5 proxy (connects to microsocks on server).

3. Test

curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

Slipstream SSH

1. Copy Certificate

scp root@server:/etc/dnstm/tunnels/<tag>/cert.pem ./cert.pem

2. Start Tunnel

slipstream-client -d DOMAIN -r 8.8.8.8:53 --cert cert.pem -l 2222

3. SSH Through Tunnel

ssh -p 2222 user@127.0.0.1

4. SOCKS Proxy via SSH

ssh -D 1080 -p 2222 user@127.0.0.1

Then use 127.0.0.1:1080 as SOCKS5 proxy.

5. Test with curl

# Start SSH with dynamic port forwarding in background
ssh -D 1080 -f -N -p 2222 user@127.0.0.1

# Test connection
curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

DNSTT SOCKS

1. Get Public Key

From server:

dnstm tunnel status <name>

Copy the public key (64 hex digits).

2. Connect

dnstt-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY DOMAIN 127.0.0.1:1080

Or with key file:

scp root@server:/etc/dnstm/tunnels/<tag>/server.pub ./
dnstt-client -udp 8.8.8.8:53 -pubkey-file server.pub DOMAIN 127.0.0.1:1080

3. Test

curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

DNSTT SSH

1. Get Public Key

dnstm tunnel status <name>

2. Start Tunnel

dnstt-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY DOMAIN 127.0.0.1:2222

3. SSH Through Tunnel

ssh -p 2222 user@127.0.0.1

4. Alternative: SSH via ProxyCommand

ssh -o ProxyCommand="dnstt-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY DOMAIN 127.0.0.1:%p" user@localhost

5. SOCKS Proxy via SSH

ssh -D 1080 -p 2222 user@127.0.0.1

6. Test with curl

# Start SSH with dynamic port forwarding in background
ssh -D 1080 -f -N -p 2222 user@127.0.0.1

# Test connection
curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

VayDNS SOCKS

1. Get Public Key

From server:

dnstm tunnel status <name>

Copy the public key (64 hex digits).

2. Connect

vaydns-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY -domain DOMAIN -socks 127.0.0.1:1080

Or with key file:

scp root@server:/etc/dnstm/tunnels/<tag>/server.pub ./
vaydns-client -udp 8.8.8.8:53 -pubkey-file server.pub -domain DOMAIN -socks 127.0.0.1:1080

When connecting to a VayDNS tunnel with dnstt-compat mode enabled, you can use either vaydns-client with -dnstt-compat or the standard dnstt-client:

# Using vaydns-client in compat mode
vaydns-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY -domain DOMAIN -dnstt-compat -socks 127.0.0.1:1080

# Using dnstt-client (since server is in dnstt-compat mode)
dnstt-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY DOMAIN 127.0.0.1:1080

3. Test

curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

VayDNS SSH

1. Get Public Key

dnstm tunnel status <name>

2. Start Tunnel

vaydns-client -udp 8.8.8.8:53 -pubkey PUBLIC_KEY -domain DOMAIN -socks 127.0.0.1:2222

3. SSH Through Tunnel

ssh -p 2222 user@127.0.0.1

4. SOCKS Proxy via SSH

ssh -D 1080 -p 2222 user@127.0.0.1

5. Test with curl

ssh -D 1080 -f -N -p 2222 user@127.0.0.1
curl -x socks5h://127.0.0.1:1080 https://httpbin.org/ip

DNS Resolvers

Use any public DNS resolver. Recommended order:

  • 8.8.8.8 (Google) - most reliable
  • 9.9.9.9 (Quad9)
  • 1.1.1.1 (Cloudflare)

If UDP is blocked, use DNS-over-TLS or DNS-over-HTTPS:

  • DNSTT: -dot 8.8.8.8:853 or -doh https://dns.google/dns-query

Troubleshooting

Connection Timeout

  1. Verify server is running:

    dnstm router status

  2. Check server logs:

    dnstm tunnel logs <name>

  3. Try a different DNS resolver (8.8.8.8 vs 1.1.1.1)

Certificate Mismatch (Slipstream)

Copy the latest certificate from server:

scp root@server:/etc/dnstm/tunnels/<tag>/cert.pem ./cert.pem

Wrong Public Key (DNSTT, VayDNS)

Get the correct key:

dnstm tunnel status <name>

Slow Connection

DNSTT is slower than Slipstream due to protocol overhead. VayDNS improves on DNSTT with KCP transport. For best performance, use Slipstream transports.

Slipstream Connection Disconnects

Check the client output for errors. Common issues:

  • Certificate mismatch: re-copy the certificate
  • DNS propagation: try a different resolver
  • Server not running: check dnstm router status