beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Document autolock/unlock/unlock-key

Browse source 
Signed-off-by: Aaron Lehmann <aaron.lehmann@docker.com>
This commit is contained in:
Aaron Lehmann 2016-11-09 14:35:58 -08:00
parent c3c70c4bcd
commit 824db2c454
5 changed files with 201 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
docs/reference/api/docker_remote_api_v1.25.md
View file

@ -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

13
docs/reference/commandline/swarm_init.md
View file

@ -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.

41
docs/reference/commandline/swarm_unlock.md Normal file
View file

@ -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)

84
docs/reference/commandline/swarm_unlock_key.md Normal file
View file

@ -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)

1
docs/reference/commandline/swarm_update.md
View file

@ -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