Document autolock/unlock/unlock-key

Signed-off-by: Aaron Lehmann <aaron.lehmann@docker.com>

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
 

docs/reference/commandline/swarm_init.md

@@ -22,6 +22,7 @@ Initialize a swarm
 
 Options:
       --advertise-addr value            Advertised address (format: <ip|interface>[: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.

docs/reference/commandline/swarm_unlock.md

@@ -0,0 +1,41 @@
+---
+title: "swarm unlock"
+description: "The swarm unlock command description and usage"
+keywords: "swarm, unlock"
+---
+
+<!-- This file is maintained within the docker/docker Github
+     repository at https://github.com/docker/docker/. Make all
+     pull requests against that repo. If you see this file in
+     another repository, consider it read-only there, as it will
+     periodically be overwritten by the definitive file. Pull
+     requests which include edits to this file in other repositories
+     will be rejected.
+-->
+
+# 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)

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"
+---
+
+<!-- This file is maintained within the docker/docker Github
+     repository at https://github.com/docker/docker/. Make all
+     pull requests against that repo. If you see this file in
+     another repository, consider it read-only there, as it will
+     periodically be overwritten by the definitive file. Pull
+     requests which include edits to this file in other repositories
+     will be rejected.
+-->
+
+# 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)

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