Skip to content

Latest commit

 

History

History
80 lines (56 loc) · 3.26 KB

turncat.md

File metadata and controls

80 lines (56 loc) · 3.26 KB
Raw

turncat: Swiss-army-knife testing tool for STUNner

turncat is a STUN/TURN client to open a connection through a TURN server to an arbitrary remote address/port. The main use is to open a local tunnel endpoint to any service running inside a Kubernetes cluster via STUNner. This is very similar in functionality to kubectl port-forward, but it uses STUN/TURN to enter the cluster. This is much faster than the TCP connection used by kubectl.

Installation

On Linux and macOS, use this script to download the latest version of the turncat binary:

curl -sL https://raw.githubusercontent.com/l7mp/stunner/main/cmd/getstunner/getstunner.sh | sh -
export PATH=$HOME/.l7mp/bin:$PATH

Note

The script installs stunnerctl too.

Install the turncat binary using the standard Go toolchain and add it to $PATH.

go install github.com/l7mp/stunner/cmd/turncat@latest

You can also enforce a specific OS, CPU architecture, and STUNner version like below:

GOOS=windows GOARCH=amd64 go install github.com/l7mp/stunner/cmd/[email protected]

Building from source is as easy as it usually gets with Go:

cd stunner
go build -o turncat cmd/turncat/main.go

Usage

Listen to client connections on the UDP listener 127.0.0.1:5000 and tunnel the received packets through the TURN server located at 192.0.2.1:3478 to the UDP listener located at 192.0.2.2:53. Use the static STUN/TURN credential mechanism to authenticate with the TURN server and set the user/passwd to test/test:

./turncat --log=all:INFO,turncat:DEBUG udp://127.0.0.1:5000 turn://test:[email protected]:3478 \
    udp://192.0.2.2:53

TLS/DTLS should also work. Below --insecure allows turncat to accept self-signed TLS certificates and --verbose is equivalent to setting all loggers to DEBUG mode (-l all:DEBUG).

./turncat --verbose --insecure udp://127.0.0.1:5000 \
    turn://test:[email protected]:3478?transport=tls udp://192.0.2.2:53

Alternatively, you can specify the special TURN server meta-URI k8s://stunner/udp-gateway:udp-listener to let turncat parse the running STUNner configuration from the active Kubernetes cluster. The URI directs turncat to read the config of the STUNner Gateway called udp-gateway in the stunner namespace and connect to the TURN listener named udp-listener. The CLI flag - instructs turncat to listen on the standard input: anything you type in the terminal will be sent via STUNner to the peer udp://10.0.0.1:9001 (after you press Enter). The CLI flag -v will enable verbose logging.

./turncat -v - k8s://stunner/udp-gateway:udp-listener udp://10.0.0.1:9001

Note that the standard kubectl command line flags are available. For instance, the below will use the context prod-europe from the kubeconfig file kube-prod.conf:

./turncat --kubeconfig=kube-prod.conf --context prod-europe -v - k8s://... udp://...

License

Copyright 2021-2023 by its authors. Some rights reserved. See AUTHORS.

MIT License - see LICENSE for full text.

Acknowledgments

Initial code adopted from pion/stun and pion/turn.