Skip to content
tslink

Install and upgrade tslink

tslink is a Docker managed plugin, so Docker installs, upgrades and configures it. This guide covers all three.

Before you start

  • A Linux host with Docker Engine 19.03 or later, or Docker in a Linux VM such as OrbStack or Docker Desktop.
  • Root access on the host.
  • Access to ghcr.io, or to a registry that mirrors ghcr.io/matchory/tslink.

Install

Docker plugins have no multi-architecture images, so every tag names its architecture. Check yours:

uname -m

x86_64 means amd64; aarch64 or arm64 means arm64. Then pick a tag:

TagWhat it is
<version>-<arch>, such as v1.2.0-amd64
A release. Use this in production, so every host runs the same version.
latest-<arch>
The newest release
main-<arch>
The current main branch

Install the plugin under the alias tslink:

docker plugin install --alias tslink --grant-all-permissions \
  ghcr.io/matchory/tslink:<version>-amd64

Docker enables the plugin once it’s installed, and the plugin creates its data directory, /var/lib/docker-plugins/tailscale, as it starts. Versions up to v0.3.4 don’t enable without that directory: for them, create it first with sudo install -d -m 0755 /var/lib/docker-plugins/tailscale.

Note

Docker stores the alias with the tag latest, so networks and stack files always use the driver name tslink:latest, whatever version and architecture you installed. Plugin commands accept plain tslink, but a network’s driver name has to be complete.

Upgrade

An upgrade restarts every tailscaled on the host. Containers keep their nodes, but their tailnet traffic stops for a few seconds while that happens.

  1. If you can, move the containers off the host first. On a Swarm, drain the node:

    docker node update --availability drain <node>

  2. Disable the plugin, upgrade it, and enable it again:

    docker plugin disable -f tslink
docker plugin upgrade --grant-all-permissions --skip-remote-check tslink ghcr.io/matchory/tslink:<version>-amd64
docker plugin set tslink shared.source=<shared directory>
docker plugin enable tslink

    Keep --skip-remote-check. Without it, docker plugin upgrade asks whether to switch to a different image, which a new version always is. Without a terminal, as in configuration management, CI or a script piped to ssh, it reads the answer from standard input, treats an empty one as “no”, and exits with status 0 having changed nothing. In a script piped to it, it even takes the script’s next line as its answer, so the commands after it never run.

    docker plugin upgrade keeps the plugin’s settings, but resets the sources of its mounts to their defaults. If you set shared.source, set it again before you enable the plugin, as above; otherwise leave that line out. If you forget, the host falls back to certificates of its own and gets them from Let’s Encrypt again.

  3. On a Swarm, make the node active again:

    docker node update --availability active <node>
Note

On a test host that wasn’t drained, these commands brought its Swarm tasks back within 4 to 11 seconds, and the containers kept their nodes. Upgrading a seven-node Swarm from v0.3.0 to v0.3.1, one host at a time and without draining, brought each host’s tasks back within 1 to 5 seconds. Still, upgrade a host that serves nothing important first, and check that its containers keep their nodes, before you move on to production.

Tailscale comes with the plugin, so to upgrade Tailscale, upgrade tslink. See binaries.

Change a setting

Disable the plugin, set the values, and enable it again. docker plugin set takes several KEY=VALUE pairs at once:

docker plugin disable tslink
docker plugin set tslink TS_AUTHKEY=tskey-auth-…
docker plugin enable tslink

docker plugin disable refuses while containers use the plugin. Stop them first, or use docker plugin disable -f. Plugin settings lists every setting.

Check that it works

docker plugin ls --filter enabled=true

The list contains tslink:latest, with ENABLED set to true.

Next steps