dnstc

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #go #machine-learning #deep-learning #docker #macos #kubernetes #vue #awesome-list #security #openai #open-source

(★ 10)

DNS tunnel manager for clients and end-users

dnstc Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DNS Tunnel Client (dnstc)

A cross-platform CLI tool for managing DNS tunnel connections. Supports multiple transport and backend types with both interactive TUI and CLI interfaces.

## Features

- **Transports**: Slipstream and DNSTT
- **Backends**: SOCKS, SSH (dynamic forwarding), and Shadowsocks (SIP003 plugin)
- **Import**: Import tunnel configs from `dnstm://` URLs generated by dnstm's `tunnel share`
- **Gateway proxy**: Single SOCKS port routing to the active tunnel, switchable at runtime
- **Daemon**: Systemd-managed daemon on Linux (`dnstc daemon enable` + `dnstc daemon start`)
- **Interactive TUI**: Status viewer with tunnel management and configuration
- **Binary management**: Install, update, and self-update via `dnstc install` and `dnstc update`
- **Named tunnels**: Auto-generated adjective-noun tags (e.g. `swift-tunnel`)
- **Per-tunnel ports**: Each tunnel gets its own local port, auto-assigned if not specified

## Installation

```bash
go install github.com/net2share/dnstc@latest
```

Or build from source:

```bash
git clone https://github.com/net2share/dnstc.git
cd dnstc
go build -o dnstc .
```

## Transport + Backend Combinations

| Transport  | Backend     | Description                             | Required Config                |
|------------|-------------|-----------------------------------------|--------------------------------|
| slipstream | shadowsocks | Slipstream as Shadowsocks SIP003 plugin | domain, ss-server, ss-password |
| slipstream | socks       | Slipstream standalone SOCKS proxy       | domain                         |
| slipstream | ssh         | SSH dynamic forwarding over Slipstream  | domain, ssh-user, ssh-password/key |
| dnstt      | socks       | DNSTT standalone SOCKS proxy            | domain, pubkey (64-char hex)   |
| dnstt      | ssh         | SSH dynamic forwarding over DNSTT       | domain, pubkey, ssh-user, ssh-password/key |

> **Note**: `dnstt + shadowsocks` is not a supported combination.

## Usage

### Interactive TUI

Run without arguments:

```bash
dnstc
```

Interactive menu with tunnel management, configuration, and live service status. The TUI auto-detects when a daemon starts or stops in another terminal.

### Daemon Management

The daemon runs via systemd on Linux. First enable the service, then start it:

```bash
sudo dnstc daemon enable    # Install and enable systemd service (once)
dnstc daemon start          # Start service and tunnels
dnstc daemon stop           # Stop service (IPC graceful shutdown)
dnstc daemon status         # Show daemon and tunnel status
sudo dnstc daemon disable   # Stop and remove systemd service
```

Tunnels auto-start when the service starts (including after reboot). Config changes via CLI (`tunnel add`, `tunnel remove`, `config edit`, etc.) are automatically picked up by the running daemon.

Logs are available via `journalctl -u dnstc`.

### CLI Commands

#### Install & Update

```bash
dnstc install             # Download and install required binaries
dnstc update              # Check and apply updates (binaries + self)
dnstc update --check      # Check only, don't apply
dnstc update --self       # Update dnstc only
dnstc update --binaries   # Update binaries only
```

#### Tunnel Management

```bash
# Import a tunnel from a dnstm:// URL (generated by dnstm tunnel share)
dnstc tunnel import dnstm://...

# Add a tunnel manually
dnstc tunnel add --transport slipstream --backend socks -d tunnel.example.com
dnstc tunnel add --transport dnstt --backend socks -d tunnel.example.com --pubkey <64-char-hex>
dnstc tunnel add --transport slipstream --backend shadowsocks -d tunnel.example.com \
  --ss-server 127.0.0.1:8388 --ss-password secret
dnstc tunnel add --transport slipstream --backend ssh -d tunnel.example.com \
  --ssh-user tunnel --ssh-password secret

# Add with a specific local port (auto-assigned if omitted)
dnstc tunnel add --transport slipstream --backend socks -d tunnel.example.com -p 9050

# List tunnels
dnstc tunnel list

# Show tunnel status
dnstc tunnel status -t <tag>

# Switch active tunnel (gateway routes to this tunnel)
dnstc tunnel activate -t <tag>

# Remove a tunnel
dnstc tunnel remove -t <tag> --force
```

#### Configuration

```bash
dnstc config show              # Display current config
dnstc config edit              # Open config in $EDITOR
dnstc config gateway-port -p 1080  # Set gateway proxy port
```

#### Uninstall

```bash
dnstc uninstall --force
```

Removes config, state, downloaded binaries, and systemd service.

## Architecture

```
┌──────────────────────────┐
│         Gateway          │  Single port (default :1080)
│    SOCKS proxy entry     │  Accepts client connections
└───────────┬──────────────┘
            │ routes to active tunnel
            ▼
┌──────────────────────────┐
│     Active Tunnel        │  Per-tunnel local port
│   (e.g. :41023)          │  Running transport binary
└───────────┬──────────────┘
            │ DNS queries → configured resolver
            ▼
       Remote Server
```

- The **gateway** is a TCP relay that listens on a single configurable port and forwards each connection to whichever tunnel is currently active.
- **Switching** the active tunnel takes effect on the next connection — no restart needed.
- Each **tunnel** runs as a child process (slipstream-client, dnstt-client, or sslocal) on its own local port. SSH backend tunnels additionally run an in-process SSH client with SOCKS5 dynamic forwarding.
- DNS queries are sent directly to the configured resolver (default `1.1.1.1:53`), avoiding any proxy-level reconstruction that could break tunnel protocols.

## Configuration

Stored in `~/.config/dnstc/config.json`:

```json
{
  "listen": {
    "socks": "127.0.0.1:1080"
  },
  "resolvers": ["1.1.1.1:53"],
  "tunnels": [
    {
      "tag": "swift-tunnel",
      "transport": "slipstream",
      "backend": "shadowsocks",
      "domain": "tunnel.example.com",
      "port": 41023,
      "shadowsocks": {
        "server": "127.0.0.1:8388",
        "password": "your-password",
        "method": "chacha20-ietf-poly1305"
      }
    },
    {
      "tag": "cool-proxy",
      "transport": "dnstt",
      "backend": "socks",
      "domain": "dns.example.com",
      "port": 41024,
      "dnstt": {
        "pubkey": "0123456789abcdef..."
      }
    },
    {
      "tag": "ssh-tunnel",
      "transport": "slipstream",
      "backend": "ssh",
      "domain": "tunnel.example.com",
      "port": 41025,
      "ssh": {
        "user": "tunnel",
        "password": "secret"
      }
    }
  ],
  "route": {
    "active": "swift-tunnel"
  }
}
```

- `listen.socks` — Gateway port. Auto-assigned if the default (1080) is unavailable.
- `resolvers` — DNS resolvers used by tunnels (default `1.1.1.1:53`). First entry is used.
- `tunnels[].port` — Per-tunnel local SOCKS port. Auto-assigned when adding a tunnel.
- `tunnels[].resolver` — Per-tunnel DNS resolver override.
- `route.active` — Tag of the tunnel the gateway routes to.

## File Locations

| Purpose       | Path                             |
|---------------|----------------------------------|
| Configuration | `~/.config/dnstc/config.json`    |
| Versions      | `~/.config/dnstc/versions.json`  |
| Process state | `~/.config/dnstc/state.json`     |
| IPC Socket    | `~/.config/dnstc/engine.sock`    |
| Binaries      | `~/.local/share/dnstc/bin/`      |
| Daemon logs   | `journalctl -u dnstc`            |

Automatic migration from YAML config (`config.yaml`) to JSON is performed on first run.

## Related Projects

- [dnstm](https://github.com/net2share/dnstm) — DNS Tunnel Manager (server-side)
- [go-corelib](https://github.com/net2share/go-corelib) — Shared Go library

dnstc

dnstc Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

dnstc

dnstc Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README