Sign inSign up

rocheston/zeltunnel

By rocheston

•Updated 5 months ago

Image
0

192

rocheston/zeltunnel repository overview

⁠Zeltunnel

Secure TCP/UDP port tunneling over HTTPS — no VPN needed.

Zeltunnel is a lightweight, single-binary tunneling tool that wraps TCP and UDP traffic inside an encrypted HTTPS connection. Firewalls and deep-packet inspection only see ordinary HTTPS traffic on port 443 — exactly like regular web browsing. No VPN configuration, no router port-forwarding, no cloud account required.

Zeltunnel is application-protocol blind: it does not understand or inspect what you are forwarding. RDP, SSH, VNC, databases, DNS, game servers, and custom protocols all work identically. You only need to specify whether to forward TCP or UDP, a local listen address, and a remote target.

⁠How It Works

[Your Machine]  ──── HTTPS/WSS (:443) ────▶  [Zeltunnel Server]  ────▶  [Target Host]
 127.0.0.1:3390       encrypted                tunnel.example.com          2.3.3.3:3389

Local forward mode — your app connects to a local port; Zeltunnel sends traffic through the encrypted tunnel; the server connects to the remote target on your behalf.

Reverse mode — the server exposes a public port; internet users connect to it; traffic flows back through the tunnel to a service running on your machine.

⁠Quick Start

⁠1. Generate config files, certificate, and a random token
# Creates server.yml, client.yml, certs/server.crt, certs/server.key
# in the current directory — a random 256-bit token is generated automatically
docker run --rm -v $(pwd):/config rocheston/zeltunnel config init --out /config
⁠2. Edit server.yml — set your domain
server:
  public_url: "https://tunnel.example.com"
  bind_https: "0.0.0.0:443"
  tls_cert: "/config/certs/server.crt"
  tls_key:  "/config/certs/server.key"
⁠3. Run the server
docker run -d \
  -p 443:443 \
  -v $(pwd):/config \
  rocheston/zeltunnel server --config /config/server.yml
⁠4. Edit client.yml — uncomment the tunnels you need, then run
docker run -d \
  -p 3389:3389 \
  -v $(pwd):/config \
  rocheston/zeltunnel client --config /config/client.yml
⁠5. Verify everything works (no config needed)
docker run --rm rocheston/zeltunnel test

⁠Tunnel Commands

⁠Local port forward (one-shot, no config file)
# RDP — connect your RDP client to localhost:3389
docker run --rm -p 3389:3389 rocheston/zeltunnel connect \
  --server   https://tunnel.example.com \
  --token    MY_SECRET_TOKEN \
  --listen   0.0.0.0:3389 \
  --target   REMOTE_HOST:3389 \
  --protocol any

# SSH
docker run --rm -p 2222:2222 rocheston/zeltunnel connect \
  --server   https://tunnel.example.com \
  --token    MY_SECRET_TOKEN \
  --listen   0.0.0.0:2222 \
  --target   10.0.0.5:22 \
  --protocol tcp

# DNS (UDP)
docker run --rm -p 5353:5353/udp rocheston/zeltunnel connect \
  --server   https://tunnel.example.com \
  --token    MY_SECRET_TOKEN \
  --listen   0.0.0.0:5353 \
  --target   10.0.0.53:53 \
  --protocol udp
⁠Reverse tunnel — expose a local service to the internet
docker run --rm rocheston/zeltunnel reverse \
  --server        https://tunnel.example.com \
  --token         MY_SECRET_TOKEN \
  --remote-listen 0.0.0.0:8080 \
  --target        127.0.0.1:8080 \
  --protocol      tcp
⁠Token & certificate management
# Hash a token for use in server.yml
docker run --rm rocheston/zeltunnel token hash MY_SECRET_TOKEN

# Generate a self-signed TLS certificate
docker run --rm -v $(pwd)/certs:/config/certs rocheston/zeltunnel cert generate \
  --out /config/certs --server-name tunnel.example.com

# Validate a config file
docker run --rm -v $(pwd):/config rocheston/zeltunnel config check --config /config/server.yml

# Run the built-in self-test (no config needed)
docker run --rm rocheston/zeltunnel test

⁠Protocol & Transport Options

OptionValuesDescription
--protocoltcp | udp | anyWhat to forward. any creates both TCP and UDP listeners.
--transportwss | quic | autoTunnel transport. auto tries QUIC first, falls back to WSS.
⁠Transports
  • WSS (WebSocket over HTTPS, TCP/443) — always works, even through strict firewalls
  • QUIC (UDP/443) — lower latency, native UDP datagrams, optional
  • auto — tries QUIC with a 1-second timeout, silently falls back to WSS

⁠server.yml structure

server:
  public_url: "https://tunnel.example.com"
  bind_https: "0.0.0.0:443"
  tls_cert: "/config/certs/server.crt"
  tls_key:  "/config/certs/server.key"

security:
  allow_open_proxy: false
  default_bind_host: "127.0.0.1"
  max_tcp_connections_per_client: 256

auth:
  tokens:
    - id: "alice"
      token_sha256: "<output of: zeltunnel token hash MY_SECRET>"
      allowed_targets:
        - "*:*"          # allow any target (restrict per-user in production)
      allowed_reverse_listens:
        - "0.0.0.0:30000-30100"

transports:
  wss:
    enabled: true
    path: "/zt/v1/connect"
  quic:
    enabled: false
    bind: "0.0.0.0:443"

⁠Security Model

  • Token authentication — SHA-256 hashed tokens, constant-time comparison, never stored or logged in plaintext
  • Per-token ACL — each token has an explicit allowed_targets list; the server rejects all other connections
  • ACL formats — exact (2.3.3.3:3389), CIDR (10.0.0.0/8:22), wildcard hostname (*.corp.example.com:443), or open (*:*)
  • TLS everywhere — all tunnel traffic is TLS 1.3 encrypted; bring your own cert or use the built-in generator
  • Never logged — raw payload bytes, plaintext tokens, and credentials in forwarded traffic are never written to logs

Built with 💛 by Haja Mo

Tag summary

Content type

Image

Digest

sha256:4fc3eb867…

Size

34.3 MB

Last updated

5 months ago

docker pull rocheston/zeltunnel