diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md index 36c07f72f9..d2a8846f2b 100644 --- a/docs/reference/commandline/swarm_init.md +++ b/docs/reference/commandline/swarm_init.md @@ -22,6 +22,7 @@ Initialize a swarm Options: --advertise-addr value Advertised address (format: [:port]) + --autolock Enable or disable manager autolocking (requiring an unlock key to start a stopped manager) --cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s) --dispatcher-heartbeat duration Dispatcher heartbeat period (ns|us|ms|s|m|h) (default 5s) --external-ca value Specifications of one or more certificate signing endpoints @@ -57,6 +58,18 @@ to [swarm join](swarm_join.md). After you create the swarm, you can display or rotate the token using [swarm join-token](swarm_join_token.md). +### `--autolock` + +This flag enables automatic locking of managers with an encryption key. The +private keys and data stored by all managers will be protected by the +encryption key printed in the output, and will not be accessible without it. +Thus, it is very important to store this key in order to activate a manager +after it restarts. The key can be passed to `docker swarm unlock` to reactivate +the manager. Autolock can be disabled by running +`docker swarm update --autolock=false`. After disabling it, the encryption key +is no longer required to start the manager, and it will start up on its own +without user intervention. + ### `--cert-expiry` This flag sets the validity period for node certificates. diff --git a/docs/reference/commandline/swarm_unlock.md b/docs/reference/commandline/swarm_unlock.md new file mode 100644 index 0000000000..164b7d35a4 --- /dev/null +++ b/docs/reference/commandline/swarm_unlock.md @@ -0,0 +1,41 @@ +--- +title: "swarm unlock" +description: "The swarm unlock command description and usage" +keywords: "swarm, unlock" +--- + + + +# swarm unlock + +```markdown +Usage: docker swarm unlock + +Unlock swarm + +Options: + --help Print usage +``` + +Unlocks a locked manager using a user-supplied unlock key. This command must be +used to reactivate a manager after its Docker daemon restarts if the autolock +setting is turned on. The unlock key is printed at the time when autolock is +enabled, and is also available from the `docker swarm unlock-key` command. + + +```bash +$ docker swarm unlock +Please enter unlock key: +``` + +## Related information + +* [swarm init](swarm_init.md) +* [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_unlock_key.md b/docs/reference/commandline/swarm_unlock_key.md new file mode 100644 index 0000000000..a2597fe9ab --- /dev/null +++ b/docs/reference/commandline/swarm_unlock_key.md @@ -0,0 +1,84 @@ +--- +title: "swarm unlock-key" +description: "The swarm unlock-keycommand description and usage" +keywords: "swarm, unlock-key" +--- + + + +# swarm unlock-key + +```markdown +Usage: docker swarm unlock-key [OPTIONS] + +Manage the unlock key + +Options: + --help Print usage + -q, --quiet Only display token + --rotate Rotate unlock key +``` + +An unlock key is a secret key needed to unlock a manager after its Docker daemon +restarts. These keys are only used when the autolock feature is enabled for the +swarm. + +You can view or rotate the unlock key using `swarm unlock-key`. To view the key, +run the `docker swarm unlock-key` command without any arguments: + + +```bash +$ 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-fySn8TY4w5lKcWcJPIpKufejh9hxx5KYwx6XZigx3Q4 + +Please remember to store this key in a password manager, since without it you +will not be able to restart the manager. +``` + +Use the `--rotate` flag to rotate the unlock key to a new, randomly-generated +key: + +```bash +$ 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-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 + +Please remember to store this key in a password manager, since without it you +will not be able to restart the manager. +``` + +The `-q` (or `--quiet`) flag only prints the key: + +```bash +$ docker swarm unlock-key -q +SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 +``` + +### `--rotate` + +This flag rotates the unlock key, replacing it with a new randomly-generated +key. The old unlock key will no longer be accepted. + +### `--quiet` + +Only print the unlock key, without instructions. + +## Related information + +* [swarm unlock](swarm_unlock.md) +* [swarm init](swarm_init.md) +* [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_update.md b/docs/reference/commandline/swarm_update.md index e9c30b6d44..78d4ba8969 100644 --- a/docs/reference/commandline/swarm_update.md +++ b/docs/reference/commandline/swarm_update.md @@ -21,6 +21,7 @@ Usage: docker swarm update [OPTIONS] Update the swarm Options: + --autolock Enable or disable manager autolocking (requiring an unlock key to start a stopped manager) --cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s) --dispatcher-heartbeat duration Dispatcher heartbeat period (ns|us|ms|s|m|h) (default 5s) --external-ca value Specifications of one or more certificate signing endpoints