Create a backup

Data managed by DTR

Docker Trusted Registry maintains data about:

This data is persisted on the host running DTR, using named volumes. Learn more about DTR named volumes.

To perform a backup of a DTR node, run the docker/dtr backup command. This command backs up the following data:

Back up DTR data

To create a backup of DTR, you need to:

1. Back up image content
2. Back up DTR metadata

You should always create backups from the same DTR replica, to ensure a smoother restore. If you have not previously performed a backup, the web interface displays a warning for you to do so:

Find your replica ID

Since you need your DTR replica ID during a backup, the following covers a few ways for you to determine your replica ID:

UCP web interface

You can find the list of replicas by navigating to Shared Resources > Stacks or Swarm > Volumes (when using swarm mode) on the UCP web interface.

UCP client bundle

From a terminal using a UCP client bundle, run:

docker ps --format "{{.Names}}" | grep dtr

# The list of DTR containers with <node>/<component>-<replicaID>, e.g.
# node-1/dtr-api-a1640e1c15b6

SSH access

Another way to determine the replica ID is to SSH into a DTR node and run the following:

REPLICA_ID=$(docker inspect -f '{{.Name}}' $(docker ps -q -f name=dtr-rethink) | cut -f 3 -d '-')
&& echo $REPLICA_ID

Back up image content

Since you can configure the storage backend that DTR uses to store images, the way you back up images depends on the storage backend you’re using.

If you’ve configured DTR to store images on the local file system or NFS mount, you can back up the images by using SSH to log into a DTR node, and creating a tar archive of the dtr-registry volume:

Example backup commands

Local images

sudo tar -cf dtr-image-backup-$(date +%Y%m%d-%H_%M_%S).tar \
  /var/lib/docker/volumes/dtr-registry-$(docker ps --filter name=dtr-rethinkdb \
  --format "{{ .Names }}" | sed 's/dtr-rethinkdb-//')

NFS-mounted images

sudo tar -cf dtr-image-backup-$(date +%Y%m%d-%H_%M_%S).tar \
  /var/lib/docker/volumes/dtr-registry-nfs-$(docker ps --filter name=dtr-rethinkdb \
  --format "{{ .Names }}" | sed 's/dtr-rethinkdb-//')

Expected output

tar: Removing leading `/' from member names

If you’re using a different storage backend, follow the best practices recommended for that system.

Back up DTR metadata

To create a DTR backup, load your UCP client bundle, and run the following concatenated commands:

DTR_VERSION=$(docker container inspect $(docker container ps -f name=dtr-registry -q) | \
  grep -m1 -Po '(?<=DTR_VERSION=)\d.\d.\d'); \
REPLICA_ID=$(docker ps --filter name=dtr-rethinkdb --format "" | head -1 | \
  sed 's|.*/||' | sed 's/dtr-rethinkdb-//'); \
read -p 'ucp-url (The UCP URL including domain and port): ' UCP_URL; \
read -p 'ucp-username (The UCP administrator username): ' UCP_ADMIN; \
read -sp 'ucp password: ' UCP_PASSWORD; \
docker run --log-driver none -i --rm \
  --env UCP_PASSWORD=$UCP_PASSWORD \
  docker/dtr:$DTR_VERSION backup \
  --ucp-username $UCP_ADMIN \
  --ucp-url $UCP_URL \
  --ucp-ca "$(curl https://${UCP_URL}/ca)" \
  --existing-replica-id $REPLICA_ID > dtr-metadata-${DTR_VERSION}-backup-$(date +%Y%m%d-%H_%M_%S).tar

UCP field prompts

• <ucp-url> is the URL you use to access UCP.
• <ucp-username> is the username of a UCP administrator.
• <replica-id> is the DTR replica ID to back up.

The above concatenated commands run through the following tasks:

1. Sets your DTR version and replica ID. To back up a specific replica, set the replica ID manually by modifying the --existing-replica-id flag in the backup command.
2. Prompts you for your UCP URL (domain and port), username, and password.
3. Prompts you for your UCP password without saving it to your disk or printing it on the terminal.
4. Retrieves the CA certificate for your specified UCP URL. To skip TLS verification, replace the --ucp-ca flag with --ucp-insecure-tls. Docker does not recommend this flag for production environments.
5. Includes DTR version and timestamp to your tar backup file.

You can learn more about the supported flags in the reference documentation.

By default, the backup command does not pause the DTR replica being backed up to prevent interruptions of user access to DTR. Since the replica is not stopped, changes that happen during the backup may not be saved. Use the --offline-backup flag to stop the DTR replica during the backup procedure. If you set this flag, remove the replica from the load balancing pool to avoid user interruption.

Also, the backup contains sensitive information like private keys, so you can encrypt the backup by running:

gpg --symmetric dtr-metadata-backup.tar

This prompts you for a password to encrypt the backup, copies the backup file and encrypts it.

Test your backups

To validate that the backup was correctly performed, you can print the contents of the tar file created. The backup of the images should look like:

tar -tf dtr-metadata-backup.tar

dtr-backup-v2.6.5/
dtr-backup-v2.6.5/rethink/
dtr-backup-v2.6.5/rethink/layers/

And the backup of the DTR metadata should look like:

tar -tf dtr-metadata-backup.tar

# The archive should look like this
dtr-backup-v2.6.5/
dtr-backup-v2.6.5/rethink/
dtr-backup-v2.6.5/rethink/properties/
dtr-backup-v2.6.5/rethink/properties/0

If you’ve encrypted the metadata backup, you can use:

gpg -d dtr-metadata-backup.tar | tar -t

You can also create a backup of a UCP cluster and restore it into a new cluster. Then restore DTR on that new cluster to confirm that everything is working as expected.

Where to go next

• Configure your storage backend
• Switch your storage backend
• Use NFS
• Use S3
• CLI reference pages
  • docker/dtr install
  • docker/dtr reconfigure
  • docker/dtr restore