docker/docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-05 00:14:17 +03:00
Code Activity

Update CLI reference docs

Browse Source
This commit is contained in:
Joao Fernandes
2016-08-16 13:44:21 -07:00
parent 1b885e7f1a
commit 79f2bdb5e4
7 changed files with 101 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
reference/backup.md
View File

@@ -9,7 +9,7 @@ parent = "ucp_ref"
# docker/ucp id
Stream a tar file to stdout containing all UCP data volumes.
Stream a tar file to stdout containing all UCP data volumes
## Usage
@@ -42,11 +42,11 @@ built-in PGP compatible encryption.
## Options
| Option | Description |
|:-----------------|:------------------------------------------------------------------------|
| `--debug, -D` | Enable debug mode |
| `--jsonlog` | Produce json formatted output for easier parsing |
| `--id` | The ID of the UCP instance to backup |
| `--root-ca-only` | Backup only the root CA certificates and keys from this controller node |
| `--passphrase` | Encrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] |
| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. |
| Option | Description |
|:--------------------|:---------------------------------------------------------------------------------|
| `--debug, -D` | Enable debug mode |
| `--jsonlog` | Produce json formatted output for easier parsing |
| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. |
| `--id` | The ID of the UCP instance to backup |
| `--root-ca-only` | Backup only the root CA certificates and keys from this controller node |
| `--passphrase` | Encrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] |

35
reference/engine-discovery.md
View File

@@ -9,7 +9,7 @@ identifier="ucp_ref_engine_discovery"
# docker/ucp engine-discovery
Manage the Engine discovery configuration.
The engine-discovery command is no longer used.
## Usage
@@ -23,33 +23,12 @@ docker run --rm -it \
## Description
This command will display and update the local Docker engine discovery
configuration. This is used by the engine for cluster membership and multi-host
networking.
By default, this command will check if the configuration is up to date. Use
'--update' to update the configuration. Use '--debug' to show more information
including current and proposed configuration.
UCP controllers in this cluster are auto-detected if possible. Alternately you
may use one or more '--controller' arguments to manually specify ALL of the UCP
controllers.
The '--host-address' argument specifies the public advertise address for THIS
node (how other nodes in the system talk to this node.) You may specify an IP
address, and the port number will be automatically filled in. If omitted, the
tool will attempt to discover the address of this node.
This command uses the exit status of 0 for success. An exit status of 1 is used
when run without the '--update' flag and when the configuration needs updating,
and 2 is used for any failures.
The engine-discovery command is no longer used. Overlay networking is enabled
automatically via swarm-mode.
## Options
| Option | Description |
|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------------|
| `--debug, -D` | Enable debug |
| `--jsonlog` | Produce json formatted output for easier parsing |
| `--update` | Apply engine discovery configuration changes |
| `--controller` `[--controller option --controller option]` | Update discovery with the external IP address or hostname of the controller(s) |
| `--host-address` | Update the external IP address or hostname this node advertises itself as [$UCP_HOST_ADDRESS] |
| Option | Description |
|:--------------|:-------------------------------------------------|
| `--debug, -D` | Enable debug |
| `--jsonlog` | Produce json formatted output for easier parsing |

38
reference/index.md
View File

@@ -26,10 +26,7 @@ $ docker run --rm -it \
## Description
Docker Universal Control Plane Tool
This tool has commands to 'install' the UCP initial controller and
'join' nodes to that controller. The tool can also 'uninstall' the product.
This tool has commands to 'install' and 'uninstall' UCP.
This tool must run as a container with a well-known name and with the
docker.sock volume mounted, which you can cut-and-paste from the usage
example below.
@@ -39,8 +36,8 @@ your hostname and primary IP addresses. This may be overridden with the
'--host-address' option. The tool may not be able to discover your
externally visible fully qualified hostname. For proper certificate
verification, you should pass one or more Subject Alternative Names with
'--san' during 'install' and 'join' that matches the fully qualified
hostname you intend to use to access the given system.
'--san' during 'install' that matches the fully qualified hostname you
intend to use to access the given system.
Many settings can be passed as flags or environment variables. When passing as
an environment variable, use the 'docker run -e VARIABLE_NAME ...' syntax to
@@ -58,19 +55,16 @@ Additional help is available for each command with the '--help' option.
## Commands
| Command | Description |
|:-------------------|:---------------------------------------------------------------------------|
| `install` | Install UCP on this engine |
| `join` | Join this engine to an existing UCP |
| `upgrade` | Upgrade the UCP components on this engine |
| `images` | Verify the UCP images on this engine |
| `uninstall` | Uninstall UCP components from this engine |
| `dump-certs` | Dump out the public certs for this UCP controller |
| `support` | Generate a support dump for this engine |
| `fingerprint` | Dump out the TLS fingerprint for the UCP controller running on this engine |
| `id` | Dump out the ID of the UCP components running on this engine |
| `engine-discovery` | Manage the engine discovery configuration |
| `backup` | Stream a tar file to stdout containing all UCP data volumes |
| `restore` | Stream a tar file on stdin containing all local UCP data volumes |
| `regen-certs` | Regenerate keys and certificates for a UCP controller |
| `help` | Shows a list of commands or help for one command |
| Command | Description |
|:--------------|:---------------------------------------------------------------------------|
| `install` | Install UCP on this engine |
| `upgrade` | Upgrade the UCP components on this engine |
| `images` | Verify the UCP images on this engine |
| `dump-certs` | Dump out the public certs for this UCP controller |
| `support` | Generate a support dump for this engine |
| `fingerprint` | Dump out the TLS fingerprint for the UCP controller running on this engine |
| `id` | Dump out the ID of the UCP components running on this engine |
| `backup` | Stream a tar file to stdout containing all UCP data volumes |
| `restore` | Stream a tar file on stdin containing all local UCP data volumes |
| `regen-certs` | Regenerate keys and certificates for a UCP controller |
| `help` | Shows a list of commands or help for one command |

61
reference/install.md
View File

@@ -28,7 +28,10 @@ local engine. If you intend to install a multi-node cluster,
you must open firewall ports between the engines for the
following ports:
Ports: 443, 12376, 12379, 12380, 12381, 12382 and 2376 or the '--swarm-port'
* 443 or the '--controller-port'
* 2376 or the '--swarm-port'
* 12376, 4789, 12379, 12380, 12381, 12382, 12383, 12384, 12385, 12386
* 4789(udp) and 7946(tcp/udp) for overlay networking
You can optionally use an externally generated and signed certificate
for the UCP controller by specifying '--external-server-cert'. Create a storage
@@ -41,31 +44,31 @@ mounting the file at '/docker_subscription.lic' in the tool. E.g.
## Options
| Option | Description |
|:-----------------------------------------------------------|:--------------------------------------------------------------------------------------------------------|
| `--debug`, `-D` | Enable debug. |
| `--jsonlog` | Produce json formatted output for easier parsing. |
| `--interactive`, `-i` | Enable interactive mode.,You will be prompted to enter all required information. |
| `--admin-username` | Specify the UCP admin username [$UCP_ADMIN_USER] |
| `--admin-password` | Specify the UCP admin password [$UCP_ADMIN_PASSWORD] |
| `--fresh-install` | Destroy any existing state and start fresh. |
| `--san` `[--san option --san option]` | Additional Subject Alternative Names for certs (e.g. `--san foo1.bar.com --san foo2.bar.com`). |
| `--host-address` | Specify the visible IP/hostname for this node. |
| `--swarm-port "2376"` | Select what port to run the local Swarm manager on (default: 2376) |
| `--controller-port "443"` | Select what port to run the local Controller on (default: 443) |
| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. |
| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. |
| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. |
| `--kv-timeout` | Timeout in milliseconds for the KV store (set higher for a multi-datacenter cluster) |
| `--kv-snapshot-count` | Number of changes between KV store snapshots (all controllers must use the same value) (default: 10000) |
| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] |
| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] |
| `--swarm-experimental` | Enable experimental Swarm features. Note: Use only for install, not join). |
| `--disable-tracking` | Disable anonymous tracking and analytics. |
| `--disable-usage` | Disable anonymous usage reporting. |
| `--external-server-cert` | Set up UCP with an external CA. |
| `--preserve-certs` | Don't (re)generate certs on the host if existing ones are found. |
| `--binpack` | Set Swarm scheduler to binpack mode (default spread). |
| `--random` | Set Swarm scheduler to random mode (default spread). |
| `--pull "missing"` | Specify image pull behavior (`always`, when `missing`, or `never`) (default: "missing") |
| `--skip-engine-discovery` | Do not configure engine for clustering |
| Option | Description |
|:-----------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--debug`, `-D` | Enable debug. |
| `--jsonlog` | Produce json formatted output for easier parsing. |
| `--interactive`, `-i` | Enable interactive mode.,You will be prompted to enter all required information. |
| `--admin-username` | Specify the UCP admin username [$UCP_ADMIN_USER] |
| `--admin-password` | Specify the UCP admin password [$UCP_ADMIN_PASSWORD] |
| `--fresh-install` | Destroy any existing state and start fresh. |
| `--san` `[--san option --san option]` | Additional Subject Alternative Names for certs (e.g. `--san foo1.bar.com --san foo2.bar.com`). |
| `--host-address` | Specify the visible IP/hostname for this node. |
| `--swarm-port "2376"` | Select what port to run the local Swarm manager on (default: 2376) |
| `--controller-port "443"` | Select what port to run the local Controller on (default: 443) |
| `--swarm-grpc-port` | Select what port to run Swarm GRPC on (default: 2377) |
| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. [$DNS] |
| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. [$DNS_OPT] |
| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. [$DNS_SEARCH] |
| `--pull "missing"` | Specify image pull behavior (`always`, when `missing`, or `never`) (default: "missing") |
| `--kv-timeout` | Timeout in milliseconds for the KV store (set higher for a multi-datacenter cluster, all controllers must use the same value) (default: 5000) [$KV_TIMEOUT] |
| `--kv-snapshot-count` | Number of changes between KV store snapshots (all controllers must use the same value) (default: 20000) [$KV_SNAPSHOT_COUNT] |
| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] |
| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] |
| `--swarm-experimental` | Enable experimental Swarm features. Note: Use only for install, not join). |
| `--disable-tracking` | Disable anonymous tracking and analytics. |
| `--disable-usage` | Disable anonymous usage reporting. |
| `--external-server-cert` | Set up UCP with an external CA. |
| `--preserve-certs` | Don't (re)generate certs on the host if existing ones are found. |
| `--binpack` | Set Swarm scheduler to binpack mode (default spread). |
| `--random` | Set Swarm scheduler to random mode (default spread). | |

32
reference/join.md
View File

@@ -9,7 +9,7 @@ identifier = "ucp_ref_join"
# docker/ucp join
Join this engine to an existing UCP.
The join command is no longer used.
## Usage
@@ -23,21 +23,7 @@ docker run --rm -it \
## Description
When running the 'join' command, you must run this tool
on the engine you wish to join to an existing UCP. The UCP controller
must be running on a different engine. Both engines must have network
visibility to eachother and have the required ports open on their firewall
settings. If your system has multiple IP addresses, you may need to
specify the '--host-address' option to ensure the correct address is used.
Ports: 443, 12376, 12379, 12380, 12381, 12382 and 2376 or the '--swarm-port' from 'install'
To enable high-availability, you must join at least one node with the
'replica' flag. When joining a replica, you may optionally provide
a backup tar file containing the Root CA material from the initial
controller saved via the 'backup' command. Only the Root CA material
will be retrieved from that backup. Add the following volume mount:
`-v /path/to/my/backup.tar:/backup.tar`
To join a node to UCP, simply run `docker swarm join`
## Options
@@ -53,15 +39,9 @@ will be retrieved from that backup. Add the following volume mount:
| `--host-address` | Specify the visible IP/hostname for this node. (override automatic detection) [$UCP_HOST_ADDRESS] |
| `--swarm-port "2376"` | Select what port to run the local Swarm manager on (default: 2376) |
| `--controller-port "443"` | Select what port to run the local Controller on (default: 443) |
| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. |
| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. |
| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. |
| `--swarm-grpc-port value` | Select what port to run Swarm GRPC on (default: 2377) |
| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. [$DNS] |
| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. [$DNS_OPT] |
| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. [$DNS_SEARCH] |
| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] |
| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] |
| `--url` | The connection URL for the remote UCP controller [$UCP_URL] |
| `--fingerprint` | The fingerprint of the UCP controller you trust [$UCP_FINGERPRINT] |
| `--replica` | Configure this node to be a UCP controller replica. |
| `--external-server-cert` | (Replica only) Use externally signed certificates for the controller. |
| `--pull "missing"` | Specify image pull behavior ('always', when 'missing', or 'never') (default: "missing") |
| `--passphrase` | Decrypt the Root CA tar file with the provided passphrase [$UCP_PASSPHRASE] |
| `--skip-engine-discovery` | Do not configure engine for clustering |

47
reference/restore.md
View File

@@ -10,7 +10,7 @@ identifier = "ucp_ref_restore"
# docker/ucp id
Stream a tar file on stdin containing all local UCP data volumes.
Restore a UCP cluster from a backup tar file.
## Usage
@@ -24,27 +24,34 @@ docker run --rm -i \
## Description
This utility will restore all the contents in all the volumes on this
controller based on a tar file generated by the 'backup' command. Any UCP
containers that are running will be stopped prior to restoring the data.
After the data is replaced, the containers will be restarted.
This utility will restore the state of this controller based on a tar file
generated by the 'backup' command. Any UCP containers that are running on this
host will be stopped prior to restoring the data. After the data is replaced,
the containers will be restarted.
When restoring multiple controllers in an HA cluster, you must manually
stop all controller nodes you plan to restore first, then begin the
restore with the most recent controller backup first. The cluster will
resume operation once 1/2+1 of the controllers have been restored.
The full restore operation can be only performed on the same node where a backup
was taken. Other controllers of the cluster need to be stopped before attempting
a restore operation.
WARNING: Any existing state on this node will be lost and replaced by
the contents of the backup. To prevent accidental use, the "-id" flag
must be provided.
The restore operation can be also used to replicate Root CA material across
controllers in the same cluster, by using the --root-ca-only flag. In this case,
no controllers need to be stopped and the same backup file can be used to
replicate Root CA material across multiple controllers of the same cluster.
WARNING: Existing state on this node will be lost and replaced by the
contents of the backup.
When the restore operation is run using --interactive mode, the backup file
needs to be mounted under /backup.tar within this container. If the
--interactive flag is not set, the backup file will be read from stdin.
## Options
| Option | Description |
|:-----------------|:-------------------------------------------------------------------------------------------------------|
| `--debug, -D` | Enable debug mode |
| `--jsonlog` | Produce json formatted output for easier parsing |
| `--id` | The ID of the UCP instance to backup |
| `--root-ca-only` | Restore only the root CA certificates and keys on this controller node (leaving all other data intact) |
| `--passphrase` | Decrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] |
| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. |
| Option | Description |
|:--------------------|:-------------------------------------------------------------------------------------------------------|
| `--debug, -D` | Enable debug mode |
| `--jsonlog` | Produce json formatted output for easier parsing |
| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. |
| `--id` | The ID of the UCP instance to backup |
| `--root-ca-only` | Restore only the root CA certificates and keys on this controller node (leaving all other data intact) |
| `--passphrase` | Decrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] |

10
reference/uninstall.md
View File

@@ -9,7 +9,7 @@ identifier = "ucp_ref_uninstall"
# docker/ucp uninstall
Uninstall UCP components from this Docker Engine.
The uninstall command is no longer used.
## Usage
@@ -23,8 +23,9 @@ docker run --rm -it \
## Description
When uninstalling UCP, you must run the 'uninstall' command against every
engine in your cluster.
The uninstall command is no longer used. To remove a node from the UCP cluster,
run the 'docker swarm leave' and 'docker node rm' commands. To remove the UCP
components but preserve the swarm cluster, use the 'uninstall-cluster' command.
## Options
@@ -36,6 +37,3 @@ engine in your cluster.
| `--pull` | Specify image pull behavior ('always', when 'missing', or 'never') (default: "missing") |
| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] |
| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] |
| `--id` | The ID of the UCP instance to uninstall |
| `--preserve-certs` | Don't delete the certs on the host |
| `--preserve-images` | Don't delete images on the host |