Skip to content

Latest commit

 

History

History
268 lines (181 loc) · 5.2 KB

CLIENT.md

File metadata and controls

268 lines (181 loc) · 5.2 KB

Client Setup

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

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

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)

Get the correct key:

dnstm tunnel status <name>

Slow Connection

DNSTT is slower than Slipstream due to protocol overhead. For better 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