Userspace networking mode (for containers)
Userspace networking mode allows running Tailscale where you don’t have access to create a VPN tunnel device. This often happens in container environments.
Tailscale works on Linux systems using a device driver called /dev/net/tun, which allows us to instantiate the VPN tunnel as though it were any other network interface like Ethernet or Wi-Fi. This lets any Linux application — from a web browser to the
ping CLI command — send its traffic through the Tailscale interface.
However, not all Linux systems support /dev/net/tun. For example, some container-based app platforms such as Heroku or Google Cloud Run do not. For those environments, userspace networking mode offers a different way of running, where tailscaled functions as a SOCKS5 or HTTP proxy which other processes in the container can connect through.
Which kind of proxy do you need?
A SOCKS5 proxy is a more general and flexible proxy that can work with any traffic.
An HTTP proxy is only for that protocol, so it only proxies HTTP and HTTPS traffic, e.g., to webpages.
You can enable userspace networking from the Tailscale CLI by passing the
--tun=userspace-networking flag to tailscaled before calling
tailscale up. To use a SOCKS5 proxy and an HTTP proxy on the same port:
tailscaled --tun=userspace-networking --socks5-server=localhost:1055 --outbound-http-proxy-listen=localhost:1055 & tailscale up --authkey=<your auth key>
Userspace networking mode is primarily designed for serverless environments. We recommend using it with ephemeral nodes / auth keys (as shown above).
You can enable userspace networking mode on Ubuntu, RHEL, or any
derivative by adding the flag
--tun=userspace-networking to the
FLAGS variable in
# Extra flags you might want to pass to tailscaled. FLAGS="--tun=userspace-networking"
Once Tailscale is authenticated, your application can connect using a SOCKS5 or HTTP proxy or both. Many widely used networking packages support these proxies already, generally by setting the
HTTP_PROXYenvironment variables. For many applications, you’ll need a command like this:
ALL_PROXY=socks5://localhost:1055/ HTTP_PROXY=http://localhost:1055/ http_proxy=http://localhost:1055/ ./my-app
Some libraries use
http_proxy instead of
HTTP_PROXY. You may need to experiment to find the right setting for your app.
Done! Your application should now be able to communicate with Tailscale devices on your network.
For instructions on how to use Tailscale on specific serverless platforms, see the articles below: