tailscale/tailscale repository overview

docker pull tailscale/tailscale:stable

⁠Quick reference

• Maintained by: Tailscale⁠
• Where to get help: Tailscale support⁠
• Where to file issues: https://github.com/tailscale/tailscale/issues⁠
• Supported architectures: arm, arm64, amd64, 386

⁠Supported tags

Containers are tagged based on the Tailscale Versioning scheme⁠.

• stable, latest to get the latest stable version.
  • v1.20.1, v1.20 to get a specific stable version.
• unstable to get the latest unstable version.
  • unstable-v1.33.159, unstable-v1.33 to get a specific unstable version.

⁠What is Tailscale?

Tailscale⁠ lets you connect your devices and users together in your own secure virtual private network. Tailscale enables encrypted point-to-point connections using the open source WireGuard⁠ protocol.

Read more about Tailscale⁠ and what you can do with Tailscale in containers⁠.

⁠How to use this image

This image includes all the Tailscale binaries.

To build the Dockerfile:

docker build -t tailscale/tailscale .

To run the tailscaled agent:

docker run -d --name=tailscaled -v /var/lib:/var/lib -v /dev/net/tun:/dev/net/tun --network=host --cap-add=NET_ADMIN --cap-add=NET_RAW tailscale/tailscale

We recommend you use an auth key⁠ for an ephemeral node⁠ when using Tailscale in a container, which can be accomplished by passing in a TS_AUTHKEY environment variable:

docker run -d --name=tailscaled -v /var/lib:/var/lib -v /dev/net/tun:/dev/net/tun --network=host --cap-add=NET_ADMIN --cap-add=NET_RAW --env TS_AUTHKEY=tskey-auth-ab1CDE2CNTRL-0123456789abcdef tailscale/tailscale

To see status:

docker exec tailscaled tailscale --socket /tmp/tailscaled.sock status

⁠Parameters

• TS_ACCEPT_DNS: Accept DNS configuration from the admin console. Not accepted by default.
• TS_AUTH_ONCE: Attempt to log in only if not already logged in. False by default, to forcibly log in every time the container starts.
• TS_AUTHKEY: A Tailscale auth key⁠ used to authenticate the container.
• TS_DEST_IP: Proxy all incoming Tailscale traffic to the specified destination IP.
• TS_KUBE_SECRET: If running in Kubernetes, the Kubernetes secret name where Tailscale state is stored. The default is tailscale.
• TS_HOSTNAME: Use the specified hostname for the node.
• TS_OUTBOUND_HTTP_PROXY_LISTEN: Set an address and port for the HTTP proxy⁠.
• TS_ROUTES: Advertises subnet routes⁠. Equivalent to tailscale set --advertise-routes=. To accept advertised routes, use TS_EXTRA_ARGS to pass in --accept-routes.
• TS_SOCKET: Unix socket path used by the Tailscale binary, where the tailscaled LocalAPI socket is created. The default is /var/run/tailscale/tailscaled.sock.
• TS_SOCKS5_SERVER: Set an address and port for the SOCKS5 proxy⁠.
• TS_STATE_DIR: Directory where the state of tailscaled is stored. This needs to persist across container restarts.
• TS_USERSPACE: Enable userspace networking⁠, instead of kernel networking. Enabled by default.

Extra arguments:

• TS_EXTRA_ARGS: any other CLI flags for tailscale set
• TS_TAILSCALED_EXTRA_ARGS: any other flags for tailscaled

For reference, see also the Tailscale documentation for this image⁠.

⁠Frequently Asked Questions

⁠Why do I get a new IP address every time the container restarts?

The most common uses for containers are dynamic, where containers come and go depending on load. By default tailscaled stores its state in /tmp and expects to be an ephemeral node⁠.

To support a long-lived service where the container retains its settings and identity across restarts, several things need to be done:

• The container must be provided with persistent storage, such as -v /var/lib/tailscale:/var/lib/tailscale
• Set TS_STATE_DIR to the location where the persistent storage has been mounted, like -e TS_STATE_DIR=/var/lib/tailscale

⁠Why do incoming connections work but not outgoing?

To support any arbitrary process using Linux sockets, tailscaled needs access to a /dev/net/tun device which many containers do not provide. By default the Dockerfile runs in userspace-networking⁠ mode, where incoming connections over the Wireguard tunnel are forwarded to the same port on localhost but initiating new connections would require SOCKS5 or HTTP proxies to be used.

To support outgoing connections from any socket application:

• The container must be provided with a TUN device, such as -d /dev/net/tun:/dev/net/tun
• TS_USERSPACE must be set to false, such as -e TS_USERSPACE=0

⁠License

See license information⁠.