Connecting through a SOCKS5 proxy
Some corporate networks and isolated environments have no direct internet access: outbound traffic is allowed only through a SOCKS5 proxy. To make the tuna CLI work on such a network, give it the proxy address: the CLI will reach the API and connect tunnels to nodes through it. SOCKS5 is supported, including username and password authentication, in tuna-cli 0.42.0 and later.
Setting the proxy
The proxy address has the format socks5://[username:password@]host[:port]. The default port is 1080.
With the --proxy flag, available on every command:
tuna http 8080 --proxy socks5://proxy.corp.local:1080
With the TUNA_PROXY environment variable:
export TUNA_PROXY=socks5://user:password@proxy.corp.local:1080
tuna http 8080
With the proxy key in the configuration file, so it applies to every run. There is no separate command for this key, so add it to the file by hand:
---
version: "1"
apiKey: tak_***
proxy: socks5://user:password@proxy.corp.local:1080
If the proxy is set in more than one place, the flag takes precedence over the variable, and the variable over the config file.
The socks5:// and socks5h:// schemes behave the same: host names are always resolved by the proxy, so the CLI works even without DNS. Any other scheme, such as http://, fails with only socks5:// is supported, and the command does not start.
The CLI does not read ALL_PROXY, HTTPS_PROXY, or NO_PROXY — only TUNA_PROXY. Otherwise, for users with a system-wide proxy set up for the browser, tuna traffic would silently take a different route.
What goes through the proxy
- All API requests and SSH session recording uploads.
- Tunnel connections to nodes:
http,tcp,ssh,app,postgres,mysql,redis,kubernetes, and others, includingtuna start. tuna diagnosechecks.
Connections to your local service go directly: the proxy is only used to reach the internet.
Background service
Pass the proxy in the tunnel command or set TUNA_PROXY before installing the service:
tuna service install -- tuna http 8080 --subdomain=web --proxy socks5://user:password@proxy.corp.local:1080
install removes --proxy from the service command line and passes the address to the service environment as TUNA_PROXY, so the proxy password does not show up in the process list.
Diagnostics
The first line of tuna diagnose output shows which proxy the checks go through. The password is hidden:
Proxy: socks5://user:xxxxx@proxy.corp.local:1080
Errors on connections through the proxy contain via proxy and the proxy address. For example, with a wrong password (in tuna diagnose, it appears in the tuna API: FAIL line):
via proxy socks5://user:xxxxx@proxy.corp.local:1080: socks connect tcp proxy.corp.local:1080->api.tuna.am:443: username/password authentication failed
If the checks to nodes fail, make sure the proxy allows connections to port 443 on the addresses listed in Using tuna in a corporate network.
Limitations
- SOCKS5 only. HTTP proxies and the
NO_PROXYexclusion list are not supported. tuna bastion sshruns the systemsshand does not use the proxy from the tuna settings. ConfigureProxyCommandin~/.ssh/configfor it.- Tuna Mesh uses WireGuard over UDP and cannot connect through a SOCKS5 proxy.
- Tuna Desktop and the Kubernetes operator do not support a proxy yet.