docker/ucp restore

Estimated reading time: 3 minutes

This topic applies to Docker Enterprise.

The Docker Enterprise platform business, including products, customers, and employees, has been acquired by Mirantis, inc., effective 13-November-2019. For more information on the acquisition and how it may affect you and your business, refer to the Docker Enterprise Customer FAQ.

Restore a UCP cluster from a backup.


docker container run --rm -i \
        --name ucp \
        -v /var/run/docker.sock:/var/run/docker.sock \
        docker/ucp \
        restore [command options] < backup.tar


This command installs a new UCP cluster that is populated with the state of a previous UCP manager node using a tar file generated by the backup command. All UCP settings, users, teams and permissions will be restored from the backup file. The Restore operation does not alter or recover any containers, networks, volumes or services of an underlying cluster.

The restore command can be performed on any manager node of an existing cluster. If the current node does not belong in a cluster, one will be initialized using the value of the --host-address flag. When restoring on an existing swarm-mode cluster, no previous UCP components must be running on any node of the cluster. This cleanup can be performed with the uninstall-ucp command.

If restore is performed on a different cluster than the one where the backup file was taken on, the Cluster Root CA of the old UCP installation will not be restored. This will invalidate any previously issued Admin Client Bundles and all administrator will be required to download new client bundles after the operation is completed. Any existing Client Bundles for non-admin users will still be fully operational.

By default, the backup tar file is read from stdin. You can also bind-mount the backup file under /config/backup.tar, and run the restore command with the --interactive flag.


  • Run uninstall-ucp before attempting the restore operation on an existing UCP cluster.

  • If your swarm-mode cluster has lost quorum and the original set of managers are not recoverable, you can attempt to recover a single-manager cluster with docker swarm init --force-new-cluster.

  • You can restore from a backup that was taken on a different manager node or a different cluster altogether.


Option Description
--debug, D Enable debug mode
--jsonlog Produce json formatted output for easier parsing
--interactive, i Run in interactive mode and prompt for configuration values
--data-path-addr value Address or interface to use for data path traffic
--force-minimums Force the install/upgrade even if the system does not meet the minimum requirements
--host-address value The network address to advertise to other nodes. Format: IP address or network interface name
--passphrase value Decrypt the backup tar file with the provided passphrase
--san value Add subject alternative names to certificates (e.g. --san --san
--swarm-grpc-port value Port for communication between nodes (default: 2377)
--unlock-key value The unlock key for this swarm-mode cluster, if one exists.
ucp, cli, restore