README
¶
[!IMPORTANT]
This repo is a fork of tunwg.
It includes several custom features/improvements and integrations to better fit ScoreScrape's infrastructure. Many of the specific integrations are controlled by environment variables, and are disabled if not set.
I have tried my best to keep the changes as minimal as possible as to allow others to fork and use this repo without code modifications.
Notes:
Below is a list of notes/mods I have made to this repo, and should be noted in the readme
I will get around to properly adding this info to the readme and re-writing the reference at some point.
The Docker build is, by default, only a server. If you want to change this when developing locally, set:
ENV TUNWG_RUN_SERVER=false
When several client processes run on the same machine, set TUNWG_KEY to a unique name per process (or give each its own TUNWG_PATH). Keys are stored under
<TUNWG_PATH or ~/.config/tunwg>/keys/<binary name>by default, so two processes running the same binary would otherwise share one wireguard identity and knock each other offline.
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/ScoreScrape/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 forward 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/ScoreScrape/tunwg/tunwg@latest
TUNWG_RUN_SERVER=true TUNWG_API=example.com TUNWG_HOST=<ip-or-dns-name-of-server> TUNWG_AUTH=<secret> tunwg
With docker, use the docker-compose.yml in this repo:
cp .env.server.example .env # fill in TUNWG_HOST, TUNWG_API and TUNWG_AUTH
docker compose up -d
Keep the env file named .env: compose reads TUNWG_PORT for its port mapping from that exact filename.
Clients will connect to your hosted instance if you set the same TUNWG_API environment variable there.
This fork requires the TUNWG_AUTH environment variable: the server refuses all tunnel registrations while it's unset. Clients must send 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_HOST=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
Documentation
Source Files
Directories