document dtr backup/restore better (#1787)

* document dtr backup/restore better

fix #1722

* little things

* improvements

* tweaks

datacenter/dtr/2.2/guides/admin/backups-and-disaster-recovery.md

@@ -4,10 +4,10 @@ keywords: docker, registry, high-availability, backup, recovery
 title: DTR backups and recovery
 ---
 
-When you use Docker Trusted Registry on a production setting, you should first
+DTR replicas rely on having a majority available at any given time for writes to
-configure it for high availability.
+succeed. Therefore if a majority of replicas are permanently lost, the only way
-
+to restore DTR to a working state is to recover from backups. This is why it's
-The next step is creating a backup policy and disaster recovery plan.
+very important to perform periodic backups.
 
 ## DTR data persistence
 
@@ -17,6 +17,9 @@ Docker Trusted Registry persists:
 that is replicated through all DTR replicas.
 * **Repository metadata**: the information about the repositories and
 images deployed. This information is replicated through all DTR replicas.
+* **Access control**: permissions for teams and repos.
+* **Notary data**: notary tags and signatures.
+* **Scan results**: security scanning results for images.
 * **Certificates and keys**: the certificates, public keys, and private keys
 that are used for mutual TLS communication.
 
@@ -33,21 +36,38 @@ command creates a backup of DTR:
 
 * Configurations,
 * Repository metadata,
+* Access control,
+* Notary data,
+* Scan results,
 * Certificates and keys used by DTR.
 
-These files are added to a tar archive, and the result is streamed to stdout.
+This data is added to a tar archive, and the result is streamed to stdout. This
+is done while DTR is running without shutting down any containers.
+
+Things DTR's backup command doesn't back up:
+
+* The vulnerability database (if using image scanning)
+* Image contents
+* Users, orgs, teams
+
+There is no way to back up the vulnerability database. You can re-download it
+after restoring or re-apply your offline tar update if offline.
 
 The backup command does not create a backup of Docker images. You should
 implement a separate backup policy for the Docker images, taking in
 consideration whether your DTR installation is configured to store images on the
-filesystem or using a cloud provider.
+filesystem or using a cloud provider. During restore, you need to separately
+restore the image contents.
 
 The backup command also doesn't create a backup of the users and organizations.
 That data is managed by UCP, so when you create a UCP backup you're creating
-a backup of the users and organizations metadata.
+a backup of the users and organizations. For this reason, when restoring DTR,
+you must do it on the same UCP cluster (or one created by restoring from
+backups) or else all DTR resources such as repos will be owned by non-existent
+users and will not be usable despite technically existing in the database.
 
 When creating a backup, the resulting .tar file contains sensitive information
-like private keys. You should ensure the backups are stored securely.
+such as private keys. You should ensure the backups are stored securely.
 
 You can check the
 [reference documentation](../../reference/cli/backup.md), for the
@@ -71,6 +91,23 @@ Where:
 * `--existing-replica-id` is the id of the replica to backup,
 * `--ucp-username`, and `--ucp-password` are the credentials of a UCP administrator.
 
+To avoid having to pass the password as a command line parameter, you may
+instead use the following approach in bash:
+
+```none
+$ read -sp 'ucp password: ' PASS; UCP_PASSWORD=$PASS docker run -i --rm -e UCP_PASSWORD docker/dtr backup \
+  --ucp-url <ucp-url> \
+  --ucp-insecure-tls \
+  --existing-replica-id <replica-id> \
+  --ucp-username <ucp-admin> > /tmp/backup.tar
+```
+
+This puts the password into a shell variable which is then passed into the
+docker client command with the -e flag which in turn relays the password to the
+DTR bootstrapper.
+
+## Testing backups
+
 To validate that the backup was correctly performed, you can print the contents
 of the tar file created:
 
@@ -78,27 +115,59 @@ of the tar file created:
 $ tar -tf /tmp/backup.tar
 ```
 
+The structure of the archive should look something like this:
+
+```none
+dtr-backup-v2.2.1/
+dtr-backup-v2.2.1/rethink/
+dtr-backup-v2.2.1/rethink/properties/
+dtr-backup-v2.2.1/rethink/properties/0
+...
+```
+
+To really test that the backup works, you must make a copy of your UCP cluster
+by backing it up and restoring it onto separate machines. Then you can restore
+DTR there from your backup and verify that it has all the data you expect to
+see.
+
 ## Restore DTR data
 
-You can restore a DTR node from a backup using the `restore`
+You can restore a DTR node from a backup using the `restore` command.
-command.
-This command performs a fresh installation of DTR, and reconfigures it with
-the configuration created during a backup.
 
-The command starts by installing DTR, restores the configurations stored on
+Note that backups are tied to specific DTR versions and are guaranteed to work
-etcd, and then restores the repository metadata stored on RethinkDB. You
+only with those DTR versions. You can backup/restore across patch versions
-can use the `--config-only` option, to only restore the configurations stored
+at your own risk, but not across minor versions as those require more complex
-on etcd.
+migrations.
 
-This command does not restore Docker images. You should implement a separate
+Before restoring DTR, make sure that you are restoring it on the same UCP
-restore procedure for the Docker images stored in your registry, taking in
+cluster or you've also restored UCP using its restore command. DTR does not
-consideration whether your DTR installation is configured to store images on
+manage users, orgs or teams so if you try to
-the filesystem or using a cloud provider.
+restore DTR on a cluster other than the one it was backed up on, DTR
+repositories will be associated with users that don't exist and it will appear
+as if the restore operation didn't work.
+
+Note that to restore DTR, you must first remove any left over containers from
+the previous installation. To do this, see the [uninstall
+documentation](../install/uninstall.md).
+
+The restore command performs a fresh installation of DTR, and reconfigures it with
+the configuration created during a backup. The command starts by installing DTR.
+Then it restores the configurations from the backup and then restores the
+repository metadata. Finally, it applies all of the configs specified as flags to
+the restore command.
+
+After restoring DTR, you must make sure that it's configured to use the same
+storage backend where it can find the image data. If the image data was backed
+up separately, you must restore it now.
+
+Finally, if you are using security scanning, you must re-fetch the security
+scanning database through the online update or by uploading the offline tar. See
+the [security scanning configuration](../admin/configure/set-up-vulnerability-scans.md)
+for more detail.
 
 You can check the
-[reference documentation](../../reference/cli/backup.md), for the
+[reference documentation](../../reference/cli/restore.md), for the
-backup command to learn about all the available flags.
+restore command to learn about all the available flags.
-
 
 As an example, to install DTR on the host and restore its
 state from an existing backup:
@@ -121,6 +190,12 @@ Where:
 * `--ucp-username`, and `--ucp-password` are the credentials of a UCP administrator,
 * `--dtr-load-balancer` is the domain name or ip where DTR can be reached.
 
+Note that if you want to avoid typing your password into the terminal you must pass
+it in as an environment variable using the same approach as for the backup command:
+
+```none
+$ read -sp 'ucp password: ' PASS; UCP_PASSWORD=$PASS docker run -i --rm -e UCP_PASSWORD docker/dtr restore ...
+```
 
 ## Where to go next
 

datacenter/dtr/2.2/guides/admin/install/uninstall.md

@@ -4,18 +4,8 @@ keywords: docker, dtr, install, uninstall
 title: Uninstall Docker Trusted Registry
 ---
 
-Uninstalling DTR is a two-step process. You first scale your DTR deployment down
+Uninstalling DTR can be done by simply removing all data associated with each
-to a single replica. Then you uninstall the last DTR replica, which permanently
+replica. To do that, you just run the destroy command once per replica:
-removes DTR and deletes all its data.
-
-Start by [scaling down your DTR deployment](../configure/set-up-high-availability.md) to a
-single replica.
-
-When your DTR deployment is down to a single replica, you can use the
-`docker/dtr destroy` command to permanently remove DTR and all its data:
-
-1. Use ssh to log into any node that is part of UCP.
-2. Uninstall DTR:
 
 ```none
 docker run -it --rm \
@@ -23,6 +13,9 @@ docker run -it --rm \
   --ucp-insecure-tls
 ```
 
+You will be prompted for the UCP URL, UCP credentials and which replica to
+destroy.
+
 To see what options are available in the destroy command, check the
 [destroy command reference documentation](../../../reference/cli/destroy.md).