Safely view and rotate a Docker Swarm unlock key

You will use docker swarm unlock-key on a Swarm manager to view the current autolock key, print it without explanatory text, or replace it with a newly generated key. Allow about ten minutes for a careful read-only check, or fifteen minutes for a rotation with records and verification. The unlock key is a secret: anyone who obtains it may be able to unlock a manager after a Docker restart.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the command without contacting the Swarm
2. View the current key
3. Print only the key when a tool needs it
4. Prepare before rotating
5. Rotate and record the new key
6. Verify the active key without exposing it

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 contacting the Swarm

The help command is safe and does not change the cluster. Run it as the same 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

The command is a Swarm management operation, so the final commands must run against a Docker Engine that is a manager. If the Docker socket requires elevated access, prefix the individual command with sudo; do not make the Docker socket or the key world-readable merely to avoid that permission check.

Checkpoint

You have confirmed the CLI version and that you are on the intended manager host. Do not continue against a test context when you mean to inspect production.

2. View the current key

Run the command with no options to display the current unlock key together with 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 and is secret. The command does not create a new key. It reads the current key from the manager, provided the swarm has a working manager quorum and the Docker context points to that swarm.

Do not paste the output into a ticket, shell transcript, chat room or source repository. Store it in the approved password manager or other restricted secret store. Treat terminal recordings and CI logs as potentially exposed if this command has been run there.

If the output says that the daemon is not a manager, check the host and context before trying another command:

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

The exact diagnostic varies with the daemon and context. The useful check is that the selected Engine is part of the expected swarm and has manager control. A worker cannot administer the unlock key. A missing quorum can also prevent management operations, so do not treat a worker error as evidence that the key has disappeared.

3. Print only the key when a tool needs it

The --quiet option removes the explanatory text and prints only the key:

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

-q is the equivalent short form. This is useful for a deliberately controlled hand-off to a secret-management workflow, but it is not automatically safe. Standard output may 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 patterns can leave the secret in shell history, process inspection output or debugging logs. If you need automation, use the secret store's documented input mechanism and confirm that it suppresses command output.

Checkpoint

You can retrieve the key without rotating it, and you know where the approved copy is stored. If that is all you needed, stop here. There is no reason to rotate a working key as part of a routine lookup.

4. Prepare before rotating

Warning

Rotation changes the cluster's unlock secret. The old key will no longer be accepted as the current key. A manager that goes down while nodes are learning the new key can require careful recovery, so perform this during a maintenance window and keep the old key available for a short period as a contingency.

Before rotation, check these points:

You are connected to the intended manager and have a healthy manager quorum.
The current key is already stored in the approved restricted location.
Operators who may need to unlock a restarted manager know the maintenance window and recovery contact.
You have not confused the unlock key with a worker or manager join token. They are different secrets with different purposes.

Rotation is a cluster state change, but it does not restart Docker or services by itself. It does alter what key will be required if autolock causes a manager to need unlocking later.

5. Rotate and record the new key

Run the rotation only after the preparation check:

$ 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

The key is randomly generated by Docker. Copy the new value into the approved secret store, replacing or versioning the previous record according to your operational policy. Do not save the sample value above or any key in this article.

If the command fails, do not assume that rotation happened. Read the daemon error, confirm the active context and manager quorum, then run docker swarm unlock-key to inspect the current key only after checking that a failed operation did not leave an ambiguous result. If the command 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 in an approved maintenance procedure. This guide does not ask you to restart Docker or deliberately lock a manager. A key lookup cannot prove that an unlock workflow will succeed on every manager, because the result also depends on the manager's local state and the swarm's availability.

There is no undo command that restores the previous key after rotation. Rotating again creates another new key; it does not bring the old one back. If a manager is unavailable during propagation, keep the previous key for the short contingency period described by Docker's operational guidance. If the old key is lost and the manager cannot be unlocked, recovery may require removing and rejoining that manager, which is a separate, disruptive procedure.

Done means

You confirmed Docker CLI 29.8.1 and the intended Docker context.
You ran the command on a Swarm manager rather than a worker.
You distinguished a read-only lookup from the state-changing --rotate operation.
The current or newly rotated key is stored in an approved restricted secret store.
You kept secret output out of tickets, repositories, command history and shared logs.
If you rotated the key, you verified the current value and retained a short-lived recovery record for the transition.