View and Rotate a Docker Swarm Unlock Key Safely

docker swarm unlock-key shows the current Swarm autolock key, prints it bare for a tool, or replaces it with a freshly generated one. Give it ten minutes for a careful read-only check, or fifteen for a rotation with records and verification. Anyone who gets hold of this key can unlock a manager after a Docker restart, so treat it accordingly.

This guide covers the Docker CLI installed on this machine: docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, reporting Docker CLI version 29.8.1. The local manual documents two options: --quiet (or -q) and --rotate.

1. Check the command without touching the swarm

Help output is safe and changes nothing. Run it as the account you normally use for Docker administration:

$ command -v docker
/usr/bin/docker
$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker swarm unlock-key --help
Usage:  docker swarm unlock-key [OPTIONS]

Manage the unlock key

Options:
  -q, --quiet    Only display token
      --rotate   Rotate unlock key

This is a Swarm management operation, so the real commands must run against a manager, not a worker. If the Docker socket needs elevated access, prefix the individual command with sudo; do not make the socket or the key world-readable just to dodge that permission check.

2. View the current key

Run the bare command to print the current key alongside instructions for using docker swarm unlock:

$ docker swarm unlock-key
To unlock a swarm manager after it restarts, run the docker swarm unlock command and provide the following key:

SWMKEY-1-REDACTED

The real value is longer than this and is secret. The command does not create a new key; it reads the current one from the manager, provided the swarm has a working quorum and your context points at it.

• Never paste it anywhere shared. Not a ticket, shell transcript, chat room or source repository.
• Store it properly. Use the approved password manager or other restricted secret store.
• Watch for accidental capture. Terminal recordings and CI logs count as exposed if this command has ever run inside them.

If the output says the daemon is not a manager, check the host and context before trying anything else:

$ docker context show
$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'

The exact diagnostic varies by daemon and context, but the useful check is the same: confirm the selected Engine is in the expected swarm and has manager control. A worker cannot administer the key, and a missing quorum can also block management operations, so do not read a worker error as evidence the key has gone missing.

3. Print only the key when a tool needs it

--quiet strips the explanatory text and prints only the key:

$ docker swarm unlock-key --quiet
SWMKEY-1-REDACTED

-q is the short form. This suits a deliberately controlled hand-off to a secret-management workflow, but it is not automatically safe: standard output can still be captured by a terminal recorder, a pipeline, a job log or a shell wrapper. Avoid commands such as docker swarm unlock-key -q > unlock-key.txt unless you have already arranged a restricted destination and a deletion policy.

Do not use command substitution in a shared shell or pass the key as a process argument. Both leave the secret sitting in shell history, process inspection output or debugging logs. If you need automation, use the secret store's own input mechanism and confirm it suppresses command output.

4. Prepare before rotating

Before rotating, check:

• You are on the intended manager with a healthy manager quorum behind it.
• The current key is already stored in the approved restricted location.
• Operators know the window. Anyone who might need to unlock a restarted manager knows the maintenance window and recovery contact.
• You have not mixed this up with a join token. The unlock key and the worker or manager join tokens are different secrets with different jobs.

Rotation is a cluster state change, but it does not restart Docker or any service by itself. It only changes what key will be needed if autolock later locks a manager out.

5. Rotate and record the new key

Run the rotation only after the preparation check above:

$ docker swarm unlock-key --rotate
Successfully rotated manager unlock key.

To unlock a swarm manager after it restarts, run the docker swarm unlock command and provide the following key:

SWMKEY-1-REDACTED

Docker generates the key randomly. Copy the new value into the approved secret store, replacing or versioning the previous record per your operational policy. Do not save the sample value above, or any key, in this article.

If the command fails, do not assume rotation happened anyway. Read the daemon error, confirm the active context and manager quorum, and only then run docker swarm unlock-key to inspect the current key, so a failed operation cannot leave you with an ambiguous result. If it reported success but the output was lost, retrieve the current value again with the no-option form and store it securely.

6. Verify the active key without exposing it

Run quiet mode again and compare it, inside your restricted secret-management process, with the value you recorded. Do not print the comparison result or either key to a shared log:

$ docker swarm unlock-key --quiet
SWMKEY-1-REDACTED

For a future restart test, use the separate docker swarm unlock command only inside an approved maintenance procedure; this guide does not ask you to restart Docker or deliberately lock a manager. A key lookup cannot prove a recovery workflow will succeed on every manager, because that also depends on each manager's local state and the swarm's availability.