Skip to content

Latest commit

 

History

History
152 lines (98 loc) · 7.12 KB

README.md

File metadata and controls

152 lines (98 loc) · 7.12 KB
Raw

Tunwg

End to end encrypted secure tunnel to local servers

Use

To expose port 8080:

tunwg -p 8080

or

tunwg --forward=http://localhost:8080

You can run tunwg in docker too:

docker run -it --rm --network=host -v tunwg_keys:/data ghcr.io/ntnj/tunwg tunwg --forward=http://localhost:8080

--network=host is needed to access the port 8080 on host.

Install

You can download a pre-compiled binary from Github releases for Windows, Linux and Mac (Arm/Intel)

To install from source:

go install github.com/ntnj/tunwg/tunwg@latest

Privacy

Tunwg provides end to end SSL encryption and forwards TCP stream to the tunwg instance running on your local machine. The local instance running on your machine is responsible for generating an HTTPS certificate for you and forwards the decrypted traffic to your local server. This means that your traffic is completely private to you.

You can also self-host your own server.

Features

Custom domains

To use your own domain name instead of a subdomain on tunwg.com, add a CNAME record in your DNS provider to the encoded domain on tunwg.com e.g. for test.example.com, add a CNAME entry for test to xxxxxxxx.l.tunwg.com

Use directly in Go programs

If you're writing your HTTP server in golang, you can use tunwg directly without running a separate binary.

import "github.com/ntnj/tunwg"

listener, err := tunwg.NewListener("<name>")
http.Serve(listener, httpHandler)

Persistent URLs

Since the generated subdomain is derived from your wireguard key and the forwarded address, it'll remain constant across process restarts. The wireguard key is stored in .config/tunwg/ (os.UserConfigDir/tunwg) or /data/ in docker. It can be customized with TUNWG_PATH environment variable.

Automatic SSL certificates

Automatic SSL certificate are issued through LetsEncrypt and automatically renewed. Fallback to ZeroSSL is supported in case of LetsEncrypt rate limits.

Relay traffic over HTTPS

In case your firewall blocks UDP packets, you can relay the traffic over HTTPS. To use, just add TUNWG_RELAY=true to client environment variables. This will effectively be TCP over UDP over TCP, so performance will suffer in case of packet drops. Use this option only if needed.

Expose ports on other hosts

You can forward any ports on local network which the machine running tunwg has access to, without installing tunwg on the forwarded host. e.g.

tunwg --forward=http://10.0.0.2:8000,http://10.0.0.10:9000

This is especially useful when running tunwg with docker compose to expose the ports on other containers without making any modifications to those images. e.g. docker-compose.yml

  tunwg:
    image: ghcr.io/ntnj/tunwg
    command: tunwg --forward=http://whoami

  whoami:
    image: traefik/whoami

You can then run docker compose logs tunwg to view the generated URL.

HTTP Basic Auth support

To expose private servers using tunwg, you can use the inbuilt basic auth support.

tunwg --forward=... --limit=$(htpasswd -nbB <user> <password>)

PROXY Protocol support

PROXY protocol enables local server to receive the remote user's IP address.

Security considerations

Even though the subdomain generated by tunwg seems random, they're not private. Since SSL certificates are issued for them by tunwg client, the encoded subdomain is added to certificate transparency logs. Many crawlers and attackers monitor those transparency logs, so you'll get some automated traffic to your servers after you first issue the certificate. Do not foward any local servers which may be vulnerable or expose private data without auth, and if you need to do that, use the inbuilt tunwg basic auth.

Since anyone can run a server on l.tunwg.com domain, be careful when using cookies received from the browser.

Self hosting

The instance at l.tunwg.com runs on a VPS with very limited resources and may be bandwidth limited. For critical use cases, you can self-host your own tunwg server.

go install github.com/ntnj/tunwg/tunwg@latest
TUNWG_RUN_SERVER=true TUNWG_API=example.com TUNWG_IP=<ip-of-server> TUNWG_PORT=<wireguard-port> tunwg

With docker:

tunwgs:
  image: ghcr.io/ntnj/tunwg
  network_mode: host  # or ports, 80,443,443/udp
  environment:
    TUNWG_RUN_SERVER: true
    TUNWG_PORT: 443      # udp port that is used for wireguard connections.
    TUNWG_IP: "a.b.c.d"  # ip of server
    TUNWG_API: example.com  # all subdomains should resolve to server

Clients will connect to your hosted instance if you set the same TUNWG_API environment variable there.

You can also set the TUNWG_AUTH environment variable to limit which clients can use your server. In that case, clients would need to set the same TUNWG_AUTH.

The server listens on port 443 (for HTTPS traffic) and on port 80 (to redirect to HTTPS and for http-01 SSL challenges). It also listens on UDP port TUNWG_PORT for wireguard UDP traffic. The public instance listens on UDP 443, since it's less likely to be blocked by firewalls.

The server is fully stateless and doesn't require any storage. It caches the wireguard private key and recent peers on disk to enable instant reconnection of tunnels after server restart. The tunwg client will add itself as peer again if the wireguard handshake with server is missed.

If you're running it behind a reverse proxy like caddy/nginx, you should make sure that the reverse proxy passes through TLS instead of decrypting HTTPS traffic.

Internal Details

One of the primary goals for tunwg was to securely allow new clients to join without requiring any configuration or database on server, and to allow end to end SSL.

The tunwg binary runs a user-space TCP/IP stack using gVisor netstack. It generates a wireguard private key, and derives the IP address of wireguard connection based on a hash of the public key. On startup, it sends the public key to the tunwg server which replies with its own public key, establishing a wireguard connection between client and server.

The generated domain name is an encoding of the internal wireguard IP address and the port. When tunwg server receives a request, it parses the TLS SNI to get the domain and decodes it to an IP:port pair, which it then forwards the connection to over the internal wireguard network.

Develop locally

Run server: TUNWG_TEST_LOCALHOST=true TUNWG_RUN_SERVER=true TUNWG_KEY=tunwgs TUNWG_PORT=443 TUNWG_IP=127.0.0.1 go run ./tunwg

Run client: TUNWG_TEST_LOCALHOST=true go run ./tunwg --forward=http://localhost:8000

Test: curl -k -Li --connect-to ::127.0.0.1: https://abcd.l.tunwg.com

Possible Future Improvements

  • Allow distributed servers