Skip to content

CLI.md

Latest commit

 

History

History
375 lines (276 loc) · 11.4 KB

CLI.md

File metadata and controls

375 lines (276 loc) · 11.4 KB

CLI Reference

All commands require root privileges (sudo).

Interactive Mode

Run without arguments for the full interactive menu:

sudo dnstm

Subcommands open their interactive submenu when run without a subcommand:

sudo dnstm tunnel                         # Opens tunnel interactive menu
sudo dnstm backend                        # Opens backend interactive menu
sudo dnstm router                         # Opens router interactive menu

Top-level commands enter interactive mode (with progress views) when run without flags:

sudo dnstm install                        # Interactive install with progress view
sudo dnstm update                         # Interactive update with progress view
sudo dnstm uninstall                      # Interactive uninstall with progress view

Adding any flag switches to CLI mode:

sudo dnstm install --force                # CLI mode, no interactive prompts
sudo dnstm update --check                 # CLI mode, just prints results

Leaf commands require their arguments — missing required args produce an error with usage info.

Install Command

Install all components and configure the system.

dnstm install                              # Interactive install with confirmation
dnstm install --force                      # Install without confirmation prompts
dnstm install --mode single                # Explicitly set single-tunnel mode
dnstm install --mode multi                 # Install with multi-tunnel mode
Flag Description
--force, -f Skip confirmation prompts
--mode, -m Operating mode: single (default) or multi

This command:

  • Creates the dnstm system user
  • Initializes router configuration and directories
  • Sets operating mode (single or multi)
  • Creates default backends (socks, ssh)
  • Creates DNS router service
  • Downloads and installs transport binaries
  • Installs and starts the microsocks SOCKS5 proxy
  • Configures firewall rules (port 53 UDP/TCP)

Note: Other commands require installation to be completed first.

Router Commands

Manage the DNS tunnel router.

dnstm router status                        # Show router status
dnstm router start                         # Start all tunnels
dnstm router stop                          # Stop all tunnels
dnstm router logs [-n lines]               # Show DNS router logs
dnstm router mode [single|multi]           # Show or switch mode
dnstm router switch -t <tag>               # Switch active tunnel (single mode)

Tunnel Commands

Manage DNS tunnels (previously called instances).

dnstm tunnel list                          # List all tunnels
dnstm tunnel add [flags]                   # Add new tunnel
dnstm tunnel remove -t <tag> [--force]     # Remove tunnel
dnstm tunnel start -t <tag>               # Start tunnel
dnstm tunnel stop -t <tag>                # Stop tunnel
dnstm tunnel restart -t <tag>             # Restart tunnel
dnstm tunnel logs -t <tag> [-n lines]     # Show tunnel logs
dnstm tunnel status -t <tag>              # Show tunnel status with cert/key info
dnstm tunnel share -t <tag> [flags]       # Generate shareable dnst:// URL

Tunnel Add Flags

dnstm tunnel add -t my-tunnel \
  --transport slipstream \
  --backend ss-primary \
  --domain t.example.com
Flag Description
--tag, -t Tunnel tag (auto-generated if omitted)
--transport Transport type: slipstream or dnstt
--backend, -b Backend tag to forward traffic to
--domain, -d Domain name
--port, -p Port number (auto-allocated if not specified)
--mtu MTU for DNSTT (default: 1232)

Tunnel Share Flags

Generate a dnst:// URL containing all connection info needed by the client (dnstc).

# Share a SOCKS/Shadowsocks tunnel
dnstm tunnel share -t slip-socks

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

# Share with SSH key authentication
dnstm tunnel share -t dnstt-ssh --user tunnel-user --key /root/.ssh/client_key

# Skip embedding certificate (Slipstream only)
dnstm tunnel share -t slip-socks --no-cert
Flag Description
--tag, -t Tunnel tag
--user SSH username (required for SSH backend)
--password SSH password (required if no key, SSH backend)
--key Path to SSH private key (alternative to password)
--no-cert Skip embedding TLS certificate (Slipstream)

The generated URL encodes transport config (domain, cert/pubkey), backend config (type, credentials), and can be imported directly with dnstc tunnel import.

Backend Commands

Manage backend services that tunnels forward traffic to.

dnstm backend list                         # List all backends
dnstm backend available                    # Show available backend types
dnstm backend add [flags]                  # Add new backend
dnstm backend remove -t <tag>              # Remove backend
dnstm backend status -t <tag>              # Show backend status

Backend Add Flags

# Add a Shadowsocks backend
dnstm backend add \
  --type shadowsocks \
  -t ss-primary \
  --password "my-password" \
  --method aes-256-gcm

# Add a custom target backend
dnstm backend add \
  --type custom \
  -t web-server \
  --address 127.0.0.1:8080
Flag Description
--type Backend type: shadowsocks or custom
--tag, -t Unique identifier for the backend (auto-generated if omitted)
--address, -a Target address (for custom backends)
--password, -p Shadowsocks password (auto-generated if empty)
--method, -m Shadowsocks encryption method

Backend Types

Type Description Addable
socks Built-in SOCKS5 proxy (microsocks at 127.0.0.1:1080) No (built-in)
ssh Built-in SSH server (127.0.0.1:22) No (built-in)
shadowsocks Shadowsocks server (slipstream only, uses SIP003 plugin) Yes
custom Custom target address Yes

Notes:

  • SOCKS and SSH backends are created automatically during installation and cannot be added manually.
  • DNSTT transport does not support the shadowsocks backend type.

Config Commands

Manage configuration files.

dnstm config export [-o file]              # Export current config to stdout or file
dnstm config load <file>                   # Load and deploy config from file
dnstm config validate <file>               # Validate config file without deploying

Config Export

# Export to stdout
dnstm config export

# Export to file
dnstm config export -o backup.json

Config Load

# Load from file (validates and saves to /etc/dnstm/config.json)
dnstm config load my-config.json

Config Validate

# Validate without deploying
dnstm config validate my-config.json

Mode Command

Show or switch operating mode (subcommand of router).

dnstm router mode              # Show current mode
dnstm router mode single       # Switch to single-tunnel mode
dnstm router mode multi        # Switch to multi-tunnel mode

Single-tunnel mode:

  • One tunnel active at a time
  • Transport binds directly to external IP:53
  • Lower overhead (no DNS router process)

Multi-tunnel mode:

  • All tunnels run simultaneously
  • DNS router handles domain-based routing
  • Each domain routes to its designated tunnel

Switch Command

Switch active tunnel in single-tunnel mode (subcommand of router).

dnstm router switch -t <tag>   # Switch to named tunnel

In interactive mode (sudo dnstm router), the switch option shows a tunnel picker.

SSH Users

Manage SSH tunnel users. Available from the interactive menu (hidden from CLI help).

sudo dnstm                 # Main menu → SSH Users
sudo dnstm ssh-users       # Direct access (hidden from --help)

Update Command

Check for and install updates to dnstm and transport binaries.

dnstm update                           # Check and install updates (interactive)
dnstm update --check                   # Check only, don't install
dnstm update --force                   # Skip confirmation prompts
dnstm update --self                    # Only update dnstm itself
dnstm update --binaries                # Only update transport binaries
Flag Description
--check Dry-run: show available updates without installing
--force Skip confirmation prompts
--self Only update dnstm itself
--binaries Only update transport binaries

The update process:

  • Checks for newer dnstm version on GitHub
  • Compares installed binary versions against pinned versions
  • Stops affected services before updating
  • Downloads and installs new versions
  • Restarts previously running services

Uninstall

Remove all dnstm components. Can be run from interactive menu or CLI.

dnstm uninstall [--force]

This removes:

  • All tunnel services
  • DNS router and microsocks services
  • Configuration files (/etc/dnstm/)
  • Transport binaries

Note: The dnstm binary is kept for easy reinstallation. To fully remove: rm /usr/local/bin/dnstm

Examples

Quick Setup

# Install and initialize
sudo dnstm install --mode single

# Add Shadowsocks backend
sudo dnstm backend add \
  --type shadowsocks \
  -t ss-primary \
  --password "my-password"

# Add Slipstream tunnel
sudo dnstm tunnel add -t main \
  --transport slipstream \
  --backend ss-primary \
  --domain t.example.com

# Check status
sudo dnstm router status

Multiple Tunnels

# Install in multi mode
sudo dnstm install --mode multi

# Add tunnels with different transports
sudo dnstm tunnel add -t slipstream-1 \
  --transport slipstream \
  --backend ss-primary \
  --domain t1.example.com

sudo dnstm tunnel add -t dnstt-1 \
  --transport dnstt \
  --backend socks \
  --domain t2.example.com

Switch Between Tunnels

# Switch to single mode
sudo dnstm router mode single

# Switch active tunnel
sudo dnstm router switch -t slipstream-1

Export and Restore Configuration

# Export current config
sudo dnstm config export -o backup.json

# Validate before deploying
dnstm config validate backup.json

# Load on another server
sudo dnstm config load backup.json