diff --git a/docs/reference/api/docker_remote_api_v1.25.md b/docs/reference/api/docker_remote_api_v1.25.md index 0da2c7aee3..167110b959 100644 --- a/docs/reference/api/docker_remote_api_v1.25.md +++ b/docs/reference/api/docker_remote_api_v1.25.md @@ -4724,18 +4724,21 @@ Inspect swarm "ElectionTick" : 3 }, "TaskDefaults" : {}, + "EncryptionConfig" : { + "AutoLockManagers": false + }, "Name" : "default" }, - "JoinTokens" : { + "JoinTokens" : { "Worker" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-6qmn92w6bu3jdvnglku58u11a", "Manager" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-8llk83c4wm9lwioey2s316r9l" - }, - "ID" : "70ilmkj2f6sp2137c753w2nmt", - "UpdatedAt" : "2016-08-15T16:32:09.623207604Z", - "Version" : { - "Index" : 51 + }, + "ID" : "70ilmkj2f6sp2137c753w2nmt", + "UpdatedAt" : "2016-08-15T16:32:09.623207604Z", + "Version" : { + "Index" : 51 + } } - } **Status codes**: @@ -4761,7 +4764,10 @@ Initialize a new swarm. The body of the HTTP response includes the node ID. "Orchestration": {}, "Raft": {}, "Dispatcher": {}, - "CAConfig": {} + "CAConfig": {}, + "EncryptionConfig" : { + "AutoLockManagers": false + } } } @@ -4816,6 +4822,9 @@ JSON Parameters: - **URL** - URL where certificate signing requests should be sent. - **Options** - An object with key/value pairs that are interpreted as protocol-specific options for the external CA driver. + - **EncryptionConfig** – Parameters related to encryption-at-rest. + - **AutoLockManagers**: If set, generate a key and use it to lock data stored on the + managers. ### Join an existing swarm @@ -4885,6 +4894,44 @@ Leave a swarm - **200** – no error - **406** – node is not part of a swarm +### Retrieve the swarm's unlock key + +`GET /swarm/unlockkey` + +Get unlock key + +**Example response**: + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" + } + +**Status codes**: + +- **200** - no error + +### Unlock a locked manager + +`POST /swarm/unlock` + +Unlock a manager + +**Example request**: + + POST /v1.25/swarm/unlock HTTP/1.1 + Content-Type: application/json + + { + "UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8" + } + +**Status codes**: + +- **200** - no error + ### Update a swarm @@ -4916,6 +4963,9 @@ Update a swarm "JoinTokens": { "Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx", "Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" + }, + "EncryptionConfig": { + "AutoLockManagers": false } } @@ -4932,6 +4982,7 @@ Update a swarm required to avoid conflicting writes. - **rotateWorkerToken** - Set to `true` (or `1`) to rotate the worker join token. - **rotateManagerToken** - Set to `true` (or `1`) to rotate the manager join token. +- **rotateManagerUnlockKey** - Set to `true` (or `1`) to rotate the manager unlock key. **Status codes**: @@ -4965,6 +5016,9 @@ JSON Parameters: - **JoinTokens** - Tokens that can be used by other nodes to join the swarm. - **Worker** - Token to use for joining as a worker. - **Manager** - Token to use for joining as a manager. +- **EncryptionConfig** – Parameters related to encryption-at-rest. + - **AutoLockManagers**: If set, generate a key and use it to lock data stored on the + managers. ## 3.9 Services 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