From 6e51854c1b2b16cedc2a605297cd024ee47c9721 Mon Sep 17 00:00:00 2001
From: Joao Fernandes <joao.fernandes@docker.com>
Date: Wed, 5 Oct 2016 18:00:19 -0700
Subject: [PATCH] Updates CLI and API docs for 2.0

Closes 3085
---
 reference/backup.md      | 63 ++++++++++++++++++--------------
 reference/dumpcerts.md   | 36 ++++++++++---------
 reference/images.md      | 29 +++++++++++++++
 reference/index.md       | 44 +++++++++--------------
 reference/install.md     | 76 +++++++++++++++++++++++----------------
 reference/join.md        | 57 +++++++++++++++--------------
 reference/menu.md        |  2 +-
 reference/migrate.md     |  3 +-
 reference/reconfigure.md | 73 +++++++++++++++++++++----------------
 reference/remove.md      | 48 +++++++++++++------------
 reference/restore.md     | 78 ++++++++++++++++++++++------------------
 reference/upgrade.md     | 42 ++++++++++++++++++++++
 12 files changed, 334 insertions(+), 217 deletions(-)
 create mode 100644 reference/images.md
 create mode 100644 reference/upgrade.md

diff --git a/reference/backup.md b/reference/backup.md
index e1181c7015..8f5ca87a37 100644
--- a/reference/backup.md
+++ b/reference/backup.md
@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "backup"
-description = "Docker Trusted Registry backup command reference."
-keywords = ["docker, registry, reference, backup"]
+title ="backup"
+description="Create a backup of DTR"
+keywords= ["docker, dtr, cli, backup"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_backup"
@@ -11,40 +11,49 @@ identifier="dtr_reference_backup"
 
 # docker/dtr backup
 
-Backup a DTR cluster to a tar file and stream it to stdout
+Create a backup of DTR
 
 ## Usage
 
 ```bash
-$ docker run -i --rm docker/dtr \
- backup [command options] > backup.tar
+docker run -i --rm docker/dtr \
+    backup [command options] > backup.tar
 ```
 
 ## Description
 
-This command creates a backup of configurations and image metadata, in a tar
-file. It can be used to make periodic backups of a DTR installation.
 
-This command only creates backups of configurations, and image metadata.
-It does not backup the Docker images stored in your registry.
+This command creates a tar file with the contents of the volumes used by
+DTR, and prints it. You can then use the 'restore' command to restore the data
+from an existing backup.
 
-You should implement a separate backup policy for the Docker images stored
-in your registry, taking in consideration whether your DTR installation is
-configured to store images on the filesystem or using a cloud provider.
+Note:
 
-WARNING: This backup contains sensitive information and should be
-stored securely.
+  * This command only creates backups of configurations, and image metadata.
+    It doesn't backup users and organizations. Users and organizations can be
+    backed up when performing a UCP backup.
+
+    It also doesn't backup the Docker images stored in your registry.
+    You should implement a separate backup policy for the Docker images stored
+    in your registry, taking in consideration whether your DTR installation is
+    configured to store images on the filesystem or using a cloud provider.
+
+  * This backup contains sensitive information and should be
+    stored securely.
 
 
-| Option                  | Description                                                                           |
-|:------------------------|:--------------------------------------------------------------------------------------|
-| `--ucp-url`             | Specify the UCP controller URL [$UCP_URL]                                             |
-| `--ucp-username`        | Specify the UCP admin username [$UCP_USERNAME]                                        |
-| `--ucp-password`        | Specify the UCP admin password [$UCP_PASSWORD]                                        |
-| `--debug`               | Enable debug mode, provides additional logging [$DEBUG]                               |
-| `--hub-username`        | Specify the Docker Hub username for pulling images [$HUB_USERNAME]                    |
-| `--hub-password`        | Specify the Docker Hub password for pulling images [$HUB_PASSWORD]                    |
-| `--ucp-insecure-tls`    | Disable TLS verification for UCP [$UCP_INSECURE_TLS]                                  |
-| `--ucp-ca`              | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]                                |
-| `--existing-replica-id` | ID of an existing replica in a cluster [$DTR_EXISTING_REPLICA_ID]                     |
-| `--config-only`         | Backup/restore only the configurations of DTR and not the database [$DTR_CONFIG_ONLY] |
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--existing-replica-id`|The ID of an existing DTR replica|
+|`--config-only`|Backup/restore only the configurations of DTR and not the database|
+
diff --git a/reference/dumpcerts.md b/reference/dumpcerts.md
index c17c70219c..2c1da74923 100644
--- a/reference/dumpcerts.md
+++ b/reference/dumpcerts.md
@@ -1,9 +1,9 @@
 <!--[metadata]>
 +++
-title = "dumpcerts"
+title ="dumpcerts"
+description="Print the TLS certificates used by DTR"
+keywords= ["docker, dtr, cli, dumpcerts"]
 [menu.main]
-description = "Docker Trusted Registry dumpcerts command reference."
-keywords = ["docker, registry, reference, dumpcerts"]
 parent="dtr_menu_reference"
 identifier="dtr_reference_dumpcerts"
 +++
@@ -11,29 +11,33 @@ identifier="dtr_reference_dumpcerts"
 
 # docker/dtr dumpcerts
 
-Dump out the TLS certificates used by this DTR instance
+Print the TLS certificates used by DTR
 
 ## Usage
 
 ```bash
-$ docker run -it --rm docker/dtr \
+docker run -i --rm docker/dtr \
     dumpcerts [command options] > backup.tar
 ```
 
 ## Description
 
+
 This command creates a backup of the certificates used by DTR for
 communicating across replicas with TLS.
 
 
-| Option                  | Description                                                        |
-|:------------------------|:-------------------------------------------------------------------|
-| `--ucp-url `            | Specify the UCP controller URL [$UCP_URL]                          |
-| `--ucp-username `       | Specify the UCP admin username [$UCP_USERNAME]                     |
-| `--ucp-password`        | Specify the UCP admin password [$UCP_PASSWORD]                     |
-| `--debug`               | Enable debug mode, provides additional logging [$DEBUG]            |
-| `--hub-username`        | Specify the Docker Hub username for pulling images [$HUB_USERNAME] |
-| `--hub-password `       | Specify the Docker Hub password for pulling images [$HUB_PASSWORD] |
-| `--ucp-insecure-tls`    | Disable TLS verification for UCP [$UCP_INSECURE_TLS]               |
-| `--ucp-ca`              | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]             |
-| `--existing-replica-id` | ID of an existing replica in a cluster [$DTR_EXISTING_REPLICA_ID]  |
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--existing-replica-id`|The ID of an existing DTR replica|
+
diff --git a/reference/images.md b/reference/images.md
new file mode 100644
index 0000000000..907d67be24
--- /dev/null
+++ b/reference/images.md
@@ -0,0 +1,29 @@
+<!--[metadata]>
++++
+title ="images"
+description="List all the images necessary to install DTR"
+keywords= ["docker, dtr, cli, images"]
+[menu.main]
+parent="dtr_menu_reference"
+identifier="dtr_reference_images"
++++
+<![end-metadata]-->
+
+# docker/dtr images
+
+List all the images necessary to install DTR
+
+## Usage
+
+```bash
+docker run -it --rm docker/dtr \
+    images [command options]
+```
+
+## Description
+
+
+This command lists all the images necessary to install DTR.
+
+
+
diff --git a/reference/index.md b/reference/index.md
index 96f9939dba..2371f24bc7 100644
--- a/reference/index.md
+++ b/reference/index.md
@@ -1,54 +1,44 @@
 <!--[metadata]>
 +++
 title = "Overview"
-description = "Learn about the options available on the docker/dtr image."
+description = "Learn about the commands available in the docker/dtr image."
 keywords = ["docker, dtr, install, uninstall, configure"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_overview"
-weight=0
+weight=-10
 +++
 <![end-metadata]-->
 
-# docker/dtr image overview
+# docker/dtr overview
 
 This tool has commands to install, configure, and backup Docker
 Trusted Registry (DTR). It also allows uninstalling DTR.
 By default the tool runs in interactive mode. It prompts you for
 the values needed.
-For running this tool in non-interactive mode, there are three
-ways you can use to pass values:
-
-```bash
-$ docker run -it --rm docker/dtr command --option value
-$ docker run -e --rm docker/dtr command ENV_VARIABLE=value
-$ docker run -e --rm docker/dtr command ENV_VARIABLE
-```
 
 Additional help is available for each command with the '--help' option.
 
+
 ## Usage
 
 ```bash
-$ docker run -it --rm docker/dtr \
+docker run -it --rm docker/dtr \
     command [command options]
 ```
 
-## Options
-
-| Option      | Description |
-|:------------|:------------|
-| `--help, h` | Show help   |
 
 ## Commands
 
-| Option        | Description                                                                     |
-|:--------------|:--------------------------------------------------------------------------------|
-| `install`     | Install Docker Trusted Registry on this Docker Engine                           |
-| `join`        | Add a new replica to an existing DTR cluster                                    |
-| `reconfigure` | Change DTR configurations                                                       |
-| `remove`      | Remove a replica from a DTR cluster                                             |
-| `restore`     | Create a new DTR cluster from an existing backup                                |
-| `backup`      | Backup a DTR cluster to a tar file and stream it to stdout                      |
-| `migrate`     | Migrate configurations, accounts, and repository metadata from DTR 1.4.3 to 2.0 |
-| `dumpcerts`   | Dump out the TLS certificates used by this DTR instance                         |
+| Option                       | Description                |
+|:-----------------------------|:---------------------------|
+|`install`| Install Docker Trusted Registry|
+|`join`| Add a new replica to an existing DTR cluster|
+|`reconfigure`| Change DTR configurations|
+|`remove`| Remove a DTR replica|
+|`restore`| Install and restore DTR from an existing backup|
+|`backup`| Create a backup of DTR|
+|`upgrade`| Upgrade DTR 2.0.0 or later cluster to this version|
+|`dumpcerts`| Print the TLS certificates used by DTR|
+|`images`| List all the images necessary to install DTR|
+
diff --git a/reference/install.md b/reference/install.md
index c76ba6edb5..8445609103 100644
--- a/reference/install.md
+++ b/reference/install.md
@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "install"
-description = "Docker Trusted Registry install command reference."
-keywords = ["docker, registry, reference, install"]
+title ="install"
+description="Install Docker Trusted Registry"
+keywords= ["docker, dtr, cli, install"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_install"
@@ -11,42 +11,58 @@ identifier="dtr_reference_install"
 
 # docker/dtr install
 
-Install Docker Trusted Registry on this Docker Engine
+Install Docker Trusted Registry
 
 ## Usage
 
 ```bash
-$ docker run -it --rm docker/dtr \
+docker run -it --rm docker/dtr \
     install [command options]
 ```
 
 ## Description
 
-This command installs DTR on the Docker Engine that runs the command.
-After installing DTR, you can add more nodes to a DTR cluster with
-the 'join' command.
+
+This command installs Docker Trusted Registry (DTR) on a node managed by
+Docker Universal Control Plane (UCP).
+
+After installing DTR, you can join additional DTR replicas using the 'join'
+command.
+
 
 ## Options
 
-| Option                     | Description                                                                                      |
-|:---------------------------|:-------------------------------------------------------------------------------------------------|
-| `--ucp-url`                | Specify the UCP controller URL [$UCP_URL]                                                        |
-| `--ucp-username`           | Specify the UCP admin username [$UCP_USERNAME]                                                   |
-| `--ucp-password`           | Specify the UCP admin password [$UCP_PASSWORD]                                                   |
-| `--debug`                  | Enable debug mode, provides additional logging [$DEBUG]                                          |
-| `--hub-username`           | Specify the Docker Hub username for pulling images [$HUB_USERNAME]                               |
-| `--hub-password`           | Specify the Docker Hub password for pulling images [$HUB_PASSWORD]                               |
-| `--http-proxy`             | Set the HTTP proxy for outgoing requests [$DTR_HTTP_PROXY]                                       |
-| `--https-proxy`            | Set the HTTPS proxy for outgoing requests [$DTR_HTTPS_PROXY]                                     |
-| `--no-proxy`               | Set the list of domains to not proxy to [$DTR_NO_PROXY]                                          |
-| `--replica-http-port "0"`  | Specify the public HTTP port for the DTR replica [$REPLICA_HTTP_PORT]                            |
-| `--replica-https-port "0"` | Specify the public HTTPS port for the DTR replica [$REPLICA_HTTPS_PORT]                          |
-| `--log-protocol`           | The protocol for sending container logs: tcp, udp or internal. Default: internal [$LOG_PROTOCOL] |
-| `--log-host`               | Endpoint to send logs to, required if --log-protocol is tcp or udp [$LOG_HOST]                   |
-| `--log-level`              | Log level for container logs. Default: INFO [$LOG_LEVEL]                                         |
-| `--dtr-external-url`       | Specify the domain name and port for the DTR load balancer [$DTR_LOAD_BALANCER]                  |
-| `--ucp-insecure-tls`       | Disable TLS verification for UCP [$UCP_INSECURE_TLS]                                             |
-| `--ucp-ca`                 | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]                                           |
-| `--ucp-node`               | Specify the host to install Docker Trusted Registry [$UCP_NODE]                                  |
-| `--replica-id`             | Specify the replica Id. Must be unique per replica, leave blank for random [$DTR_REPLICA_ID]     |
-| `--unsafe`                 | Enable this flag to skip safety checks when installing or joining [$DTR_UNSAFE]                  |
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--http-proxy`|The HTTP proxy used for outgoing requests|
+|`--https-proxy`|The HTTPS proxy used for outgoing requests|
+|`--no-proxy`|Don't use a proxy for these domains. Format acme.org[, acme.com]|
+|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80|
+|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443|
+|`--log-protocol`|The protocol for sending container logs: tcp, tcp+tls, udp or internal. Default: internal|
+|`--log-host`|Endpoint to send logs to, required if --log-protocol is tcp or udp|
+|`--log-level`|Log level for container logs. Default: INFO|
+|`--log-tls-ca-cert`|PEM-encoded TLS CA cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls|
+|`--log-tls-cert`|PEM-encoded TLS cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls|
+|`--log-tls-key`|PEM-encoded TLS key for DTR logging driver. Ignored if the address protocol is not tcp+tls|
+|`--log-tls-skip-verify`|Disable TLS verification for the logging service. Ignored if the logging address is not tcp+tls|
+|`--dtr-external-url`|URL of the host or load balancer clients use to reach DTR. Format https://host[:port]|
+|`--dtr-storage-volume`|Full path or volume name to store Docker images in the local filesystem|
+|`--nfs-storage-url`|NFS to store Docker images. Requires NFS client libraries. Format nfs://<ip|hostname>/<mountpoint>|
+|`--enable-pprof`|Enables pprof profiling of the server|
+|`--etcd-heartbeat-interval`|Frequency in milliseconds that the key-value store leader notifies followers|
+|`--etcd-election-timeout`|Timeout in milliseconds for key-value store membership|
+|`--etcd-snapshot-count`|Number of changes between key-value store snapshots|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--ucp-node`|The hostname of the node to install DTR|
+|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random|
+|`--unsafe`|Allow DTR to be installed on a UCP manager node|
+|`--extra-envs`|Environment variables or swarm constraints for DTR containers. Format var=val[&var=val]|
+
diff --git a/reference/join.md b/reference/join.md
index af3a775863..117560164d 100644
--- a/reference/join.md
+++ b/reference/join.md
@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "join"
-description = "Docker Trusted Registry join command reference."
-keywords = ["docker, registry, reference, join"]
+title ="join"
+description="Add a new replica to an existing DTR cluster"
+keywords= ["docker, dtr, cli, join"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_join"
@@ -13,36 +13,35 @@ identifier="dtr_reference_join"
 
 Add a new replica to an existing DTR cluster
 
-## Usage
 
-```bash
-$ docker run -it --rm docker/dtr \
-   join [command options]
-```
 
 ## Description
 
-This command installs DTR on the Docker Engine that runs the command,
-and joins the new installation to an existing cluster.
 
-To set up a cluster with high-availability, add 3, 5, or 7 nodes to
-the cluster.
+This command creates a replica of an existing DTR on a node managed by
+Docker Universal Control Plane (UCP).
+
+For setting DTR for high-availability, create 3, 5, or 7 replicas of DTR.
 
 
-| Option                     | Description                                                                                  |
-|:---------------------------|:---------------------------------------------------------------------------------------------|
-| `--ucp-url`                | Specify the UCP controller URL [$UCP_URL]                                                    |
-| `--ucp-username`           | Specify the UCP admin username [$UCP_USERNAME]                                               |
-| `--ucp-password`           | Specify the UCP admin password [$UCP_PASSWORD]                                               |
-| `--debug`                  | Enable debug mode, provides additional logging [$DEBUG]                                      |
-| `--hub-username`           | Specify the Docker Hub username for pulling images [$HUB_USERNAME]                           |
-| `--hub-password`           | Specify the Docker Hub password for pulling images [$HUB_PASSWORD]                           |
-| `--ucp-insecure-tls`       | Disable TLS verification for UCP [$UCP_INSECURE_TLS]                                         |
-| `--ucp-ca`                 | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]                                       |
-| `--ucp-node`               | Specify the host to install Docker Trusted Registry [$UCP_NODE]                              |
-| `--replica-id`             | Specify the replica Id. Must be unique per replica, leave blank for random [$DTR_REPLICA_ID] |
-| `--unsafe`                 | Enable this flag to skip safety checks when installing or joining [$DTR_UNSAFE]              |
-| `--existing-replica-id`    | ID of an existing replica in a cluster [$DTR_EXISTING_REPLICA_ID]                            |
-| `--replica-http-port "0"`  | Specify the public HTTP port for the DTR replica [$REPLICA_HTTP_PORT]                        |
-| `--replica-https-port "0"` | Specify the public HTTPS port for the DTR replica [$REPLICA_HTTPS_PORT]                      |
-| `--skip-network-test`      | Whether to skip the overlay networking test or not [$DTR_SKIP_NETWORK_TEST]                  |
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--ucp-node`|The hostname of the node to install DTR|
+|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random|
+|`--unsafe`|Allow DTR to be installed on a UCP manager node|
+|`--existing-replica-id`|The ID of an existing DTR replica|
+|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80|
+|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443|
+|`--skip-network-test`|Don't test if overlay networks are working correctly between UCP nodes|
+|`--extra-envs`|Environment variables or swarm constraints for DTR containers. Format var=val[&var=val]|
+
diff --git a/reference/menu.md b/reference/menu.md
index b14ccfcb3e..ca6363f184 100644
--- a/reference/menu.md
+++ b/reference/menu.md
@@ -1,7 +1,7 @@
 <!--[metadata]>
 +++
 title = "docker/dtr image reference"
-description = "Learn about the options available on the docker/trusted-registry image."
+description = "Learn about the commands available in the docker/dtr image."
 keywords = ["docker, dtr, install, uninstall, configure"]
 type = "menu"
 [menu.main]
diff --git a/reference/migrate.md b/reference/migrate.md
index 6f5423b6ff..9c77d0db3d 100644
--- a/reference/migrate.md
+++ b/reference/migrate.md
@@ -11,7 +11,8 @@ identifier="dtr_reference_migrate"
 
 # docker/dtr migrate
 
-Migrate configurations, accounts, and repository metadata from DTR 1.4.3 to 2.0
+Migrate configurations, accounts, and repository metadata from DTR 1.4.3 to 2.0.
+Only available in `docker/dtr` version 2.0.x.
 
 ## Usage
 
diff --git a/reference/reconfigure.md b/reference/reconfigure.md
index 6b08db5b5b..b92110cacb 100644
--- a/reference/reconfigure.md
+++ b/reference/reconfigure.md
@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "reconfigure"
-description = "Docker Trusted Registry reconfigure command reference."
-keywords = ["docker, registry, reference, reconfigure"]
+title ="reconfigure"
+description="Change DTR configurations"
+keywords= ["docker, dtr, cli, reconfigure"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_reconfigure"
@@ -13,39 +13,52 @@ identifier="dtr_reference_reconfigure"
 
 Change DTR configurations
 
-# Usage
+## Usage
 
 ```bash
-$ docker run -it --rm docker/dtr \
-  reconfigure [command options]
+docker run -it --rm docker/dtr \
+    reconfigure [command options]
 ```
 
 ## Description
 
-This command changes specified configurations for DTR and leaves
-existing configurations in its original state.
 
-WARNING: DTR is restarted for the new configurations to take
-effect. To have no down time, configure your DTR for high-availability.
+This command changes DTR configuration settings.
+
+DTR is restarted for the new configurations to take effect. To have no down
+time, configure your DTR for high-availability.
 
 
-| Option                     | Description                                                                                      |
-|:---------------------------|:-------------------------------------------------------------------------------------------------|
-| `--ucp-url`                | Specify the UCP controller URL [$UCP_URL]                                                        |
-| `--ucp-username`           | Specify the UCP admin username [$UCP_USERNAME]                                                   |
-| `--ucp-password`           | Specify the UCP admin password [$UCP_PASSWORD]                                                   |
-| `--debug`                  | Enable debug mode, provides additional logging [$DEBUG]                                          |
-| `--hub-username`           | Specify the Docker Hub username for pulling images [$HUB_USERNAME]                               |
-| `--hub-password`           | Specify the Docker Hub password for pulling images [$HUB_PASSWORD]                               |
-| `--http-proxy`             | Set the HTTP proxy for outgoing requests [$DTR_HTTP_PROXY]                                       |
-| `--https-proxy`            | Set the HTTPS proxy for outgoing requests [$DTR_HTTPS_PROXY]                                     |
-| `--no-proxy`               | Set the list of domains to not proxy to [$DTR_NO_PROXY]                                          |
-| `--replica-http-port "0"`  | Specify the public HTTP port for the DTR replica [$REPLICA_HTTP_PORT]                            |
-| `--replica-https-port "0"` | Specify the public HTTPS port for the DTR replica [$REPLICA_HTTPS_PORT]                          |
-| `--log-protocol`           | The protocol for sending container logs: tcp, udp or internal. Default: internal [$LOG_PROTOCOL] |
-| `--log-host`               | Endpoint to send logs to, required if --log-protocol is tcp or udp [$LOG_HOST]                   |
-| `--log-level`              | Log level for container logs. Default: INFO [$LOG_LEVEL]                                         |
-| `--dtr-load-balancer`      | Specify the domain name and port for the DTR load balancer [$DTR_LOAD_BALANCER]                  |
-| `--ucp-insecure-tls`       | Disable TLS verification for UCP [$UCP_INSECURE_TLS]                                             |
-| `--ucp-ca`                 | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]                                           |
-| `--existing-replica-id`    | ID of an existing replica in a cluster [$DTR_EXISTING_REPLICA_ID]                                |
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--http-proxy`|The HTTP proxy used for outgoing requests|
+|`--https-proxy`|The HTTPS proxy used for outgoing requests|
+|`--no-proxy`|Don't use a proxy for these domains. Format acme.org[, acme.com]|
+|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80|
+|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443|
+|`--log-protocol`|The protocol for sending container logs: tcp, tcp+tls, udp or internal. Default: internal|
+|`--log-host`|Endpoint to send logs to, required if --log-protocol is tcp or udp|
+|`--log-level`|Log level for container logs. Default: INFO|
+|`--log-tls-ca-cert`|PEM-encoded TLS CA cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls|
+|`--log-tls-cert`|PEM-encoded TLS cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls|
+|`--log-tls-key`|PEM-encoded TLS key for DTR logging driver. Ignored if the address protocol is not tcp+tls|
+|`--log-tls-skip-verify`|Disable TLS verification for the logging service. Ignored if the logging address is not tcp+tls|
+|`--dtr-external-url`|URL of the host or load balancer clients use to reach DTR. Format https://host[:port]|
+|`--dtr-storage-volume`|Full path or volume name to store Docker images in the local filesystem|
+|`--nfs-storage-url`|NFS to store Docker images. Requires NFS client libraries. Format nfs://<ip|hostname>/<mountpoint>|
+|`--enable-pprof`|Enables pprof profiling of the server|
+|`--etcd-heartbeat-interval`|Frequency in milliseconds that the key-value store leader notifies followers|
+|`--etcd-election-timeout`|Timeout in milliseconds for key-value store membership|
+|`--etcd-snapshot-count`|Number of changes between key-value store snapshots|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--existing-replica-id`|The ID of an existing DTR replica|
+
diff --git a/reference/remove.md b/reference/remove.md
index 0b601a8f78..393af38cb5 100644
--- a/reference/remove.md
+++ b/reference/remove.md
@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "remove"
-description = "Docker Trusted Registry remove command reference."
-keywords = ["docker, registry, reference, remove"]
+title ="remove"
+description="Remove a DTR replica"
+keywords= ["docker, dtr, cli, remove"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_remove"
@@ -11,31 +11,35 @@ identifier="dtr_reference_remove"
 
 # docker/dtr remove
 
-Remove a replica from a DTR cluster
+Remove a DTR replica
 
 ## Usage
 
 ```bash
-$ docker run -it --rm docker/dtr \
-  remove [command options]
+docker run -it --rm docker/dtr \
+    remove [command options]
 ```
 
 ## Description
 
-This command removes a replica from the cluster, stops and removes all
-DTR containers, and deletes all DTR volumes.
 
-| Option                  | Description                                                                                  |
-|:------------------------|:---------------------------------------------------------------------------------------------|
-| `--ucp-url`             | Specify the UCP controller URL [$UCP_URL]                                                    |
-| `--ucp-username`        | Specify the UCP admin username [$UCP_USERNAME]                                               |
-| `--ucp-password`        | Specify the UCP admin password [$UCP_PASSWORD]                                               |
-| `--debug`               | Enable debug mode, provides additional logging [$DEBUG]                                      |
-| `--hub-username`        | Specify the Docker Hub username for pulling images [$HUB_USERNAME]                           |
-| `--hub-password`        | Specify the Docker Hub password for pulling images [$HUB_PASSWORD]                           |
-| `--ucp-insecure-tls`    | Disable TLS verification for UCP [$UCP_INSECURE_TLS]                                         |
-| `--ucp-ca`              | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]                                       |
-| `--ucp-node`            | Specify the host to install Docker Trusted Registry [$UCP_NODE]                              |
-| `--force-remove`        | Force removal of replica even if it will break your cluster's state [$DTR_CONFIG_ONLY]       |
-| `--replica-id`          | Specify the replica Id. Must be unique per replica, leave blank for random [$DTR_REPLICA_ID] |
-| `--existing-replica-id` | ID of an existing replica in a cluster [$DTR_EXISTING_REPLICA_ID]                            |
+This command removes a replica from a DTR deployment. All DTR containers and
+volumes are removed from the node.
+
+
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--force-remove`|Force a DTR replica to be removed|
+|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random|
+|`--existing-replica-id`|The ID of an existing DTR replica|
+
diff --git a/reference/restore.md b/reference/restore.md
index de29b66d83..f32e670aeb 100644
--- a/reference/restore.md
+++ b/reference/restore.md
@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
-title = "restore"
-description = "Docker Trusted Registry restore command reference."
-keywords = ["docker, registry, restore, backup"]
+title ="restore"
+description="Install and restore DTR from an existing backup"
+keywords= ["docker, dtr, cli, restore"]
 [menu.main]
 parent="dtr_menu_reference"
 identifier="dtr_reference_restore"
@@ -11,51 +11,61 @@ identifier="dtr_reference_restore"
 
 # docker/dtr restore
 
-Create a new DTR cluster from an existing backup
+Install and restore DTR from an existing backup
 
 ## Usage
 
 ```bash
-$ docker run -i --rm docker/dtr \
-  restore [command options] < backup.tar
+docker run -i --rm docker/dtr \
+    restore [command options] < backup.tar
 ```
 
 ## Description
 
+
 This command performs a fresh installation of DTR, and reconfigures it
 with configuration data from a tar file generated by the 'backup' command.
-The command starts by installing DTR, restores the configurations
-stored on etcd, and then restores the repository metadata stored
-on RethinkDB.
 
 This command does not restore Docker images. You should implement a separate
 restore procedure for the Docker images stored in your registry, taking in
 consideration whether your DTR installation is configured to store images on
-the filesystem or using a cloud provider.
+the local filesystem or using a cloud provider.
 
-After restoring DTR, you can add more nodes to the DTR cluster with
-the 'join' command.
+After restoring, you can add more DTR replicas by using the the 'join' command.
 
 
-| Option                     | Description                                                                                      |
-|:---------------------------|:-------------------------------------------------------------------------------------------------|
-| `--ucp-url`                | Specify the UCP controller URL [$UCP_URL]                                                        |
-| `--ucp-username`           | Specify the UCP admin username [$UCP_USERNAME]                                                   |
-| `--ucp-password`           | Specify the UCP admin password [$UCP_PASSWORD]                                                   |
-| `--debug`                  | Enable debug mode, provides additional logging [$DEBUG]                                          |
-| `--hub-username`           | Specify the Docker Hub username for pulling images [$HUB_USERNAME]                               |
-| `--hub-password`           | Specify the Docker Hub password for pulling images [$HUB_PASSWORD]                               |
-| `--http-proxy`             | Set the HTTP proxy for outgoing requests [$DTR_HTTP_PROXY]                                       |
-| `--https-proxy`            | Set the HTTPS proxy for outgoing requests [$DTR_HTTPS_PROXY]                                     |
-| `--no-proxy`               | Set the list of domains to not proxy to [$DTR_NO_PROXY]                                          |
-| `--replica-http-port "0"`  | Specify the public HTTP port for the DTR replica [$REPLICA_HTTP_PORT]                            |
-| `--replica-https-port "0"` | Specify the public HTTPS port for the DTR replica [$REPLICA_HTTPS_PORT]                          |
-| `--log-protocol`           | The protocol for sending container logs: tcp, udp or internal. Default: internal [$LOG_PROTOCOL] |
-| `--log-host`               | Endpoint to send logs to, required if --log-protocol is tcp or udp [$LOG_HOST]                   |
-| `--log-level`              | Log level for container logs. Default: INFO [$LOG_LEVEL]                                         |
-| `--dtr-load-balancer`      | Specify the domain name and port for the DTR load balancer [$DTR_LOAD_BALANCER]                  |
-| `--ucp-insecure-tls`       | Disable TLS verification for UCP [$UCP_INSECURE_TLS]                                             |
-| `--ucp-ca`                 | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA]                                           |
-| `--ucp-node`               | Specify the host to install Docker Trusted Registry [$UCP_NODE]                                  |
-| `--replica-id`             | Specify the replica Id. Must be unique per replica, leave blank for random [$DTR_REPLICA_ID]     |
-| `--config-only`            | Backup/restore only the configurations of DTR and not the database [$DTR_CONFIG_ONLY]            |
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--http-proxy`|The HTTP proxy used for outgoing requests|
+|`--https-proxy`|The HTTPS proxy used for outgoing requests|
+|`--no-proxy`|Don't use a proxy for these domains. Format acme.org[, acme.com]|
+|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80|
+|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443|
+|`--log-protocol`|The protocol for sending container logs: tcp, tcp+tls, udp or internal. Default: internal|
+|`--log-host`|Endpoint to send logs to, required if --log-protocol is tcp or udp|
+|`--log-level`|Log level for container logs. Default: INFO|
+|`--log-tls-ca-cert`|PEM-encoded TLS CA cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls|
+|`--log-tls-cert`|PEM-encoded TLS cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls|
+|`--log-tls-key`|PEM-encoded TLS key for DTR logging driver. Ignored if the address protocol is not tcp+tls|
+|`--log-tls-skip-verify`|Disable TLS verification for the logging service. Ignored if the logging address is not tcp+tls|
+|`--dtr-external-url`|URL of the host or load balancer clients use to reach DTR. Format https://host[:port]|
+|`--dtr-storage-volume`|Full path or volume name to store Docker images in the local filesystem|
+|`--nfs-storage-url`|NFS to store Docker images. Requires NFS client libraries. Format nfs://<ip|hostname>/<mountpoint>|
+|`--enable-pprof`|Enables pprof profiling of the server|
+|`--etcd-heartbeat-interval`|Frequency in milliseconds that the key-value store leader notifies followers|
+|`--etcd-election-timeout`|Timeout in milliseconds for key-value store membership|
+|`--etcd-snapshot-count`|Number of changes between key-value store snapshots|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--ucp-node`|The hostname of the node to install DTR|
+|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random|
+|`--config-only`|Backup/restore only the configurations of DTR and not the database|
+
diff --git a/reference/upgrade.md b/reference/upgrade.md
new file mode 100644
index 0000000000..bae2f3e29c
--- /dev/null
+++ b/reference/upgrade.md
@@ -0,0 +1,42 @@
+<!--[metadata]>
++++
+title ="upgrade"
+description="Upgrade DTR 2.0.0 or later cluster to this version"
+keywords= ["docker, dtr, cli, upgrade"]
+[menu.main]
+parent="dtr_menu_reference"
+identifier="dtr_reference_upgrade"
++++
+<![end-metadata]-->
+
+# docker/dtr upgrade
+
+Upgrade DTR 2.0.0 or later cluster to this version
+
+## Usage
+
+```bash
+docker run -it --rm docker/dtr \
+    upgrade [command options]
+```
+
+## Description
+
+
+This command upgrades DTR 2.0.0 or later to the current version of this image.
+
+
+## Options
+
+| Option                    | Description                |
+|:--------------------------|:---------------------------|
+|`--ucp-url`|The UCP URL including domain and port|
+|`--ucp-username`|The UCP administrator username|
+|`--ucp-password`|The UCP administrator password|
+|`--debug`|Enable debug mode for additional logging|
+|`--hub-username`|Username to use when pulling images|
+|`--hub-password`|Password to use when pulling images|
+|`--ucp-insecure-tls`|Disable TLS verification for UCP|
+|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP|
+|`--existing-replica-id`|The ID of an existing DTR replica|
+