How to restore a controller from a backup

Once you’ve created a backup file using juju create-backup, you can restore the controller to an earlier snapshot using the stand-alone juju-restore tool.

The restore tool is useful for rolling back to a previous backup, for example, if a juju upgrade-model failed for some reason. It must be run on the primary controller. At a high level, it performs the following actions:

  1. Run various pre-checks, for example, ensuring the backup version matches the controller version
  2. Confirm with the user they definitely want to proceed
  3. Stop the controller agent
  4. Reinstate the model data in MongoDB using mongorestore (already installed on the controller)
  5. Restart the controller agent

The tool works on high-availability (HA) controllers, as long as there’s SSH connectivity from the primary controller (where you run juju-restore) to the secondary controller machines. We check for connectivity before beginning the restore, just in case.

Restoring a backup used to be done using the juju restore-backup command. This command is now deprecated (and no longer works on controllers running Focal); use juju-restore instead.


juju-restore is written in Go and can be downloaded from the Releases tab of the GitHub project. To “install” juju-restore, download the executable and copy it to the controller machine.

# Download the latest release binary (Linux, AMD64)
chmod +x juju-restore

# Switch to the controller model
juju switch -m controller

# Copy juju-restore to the machine hosting the MongoDB primary  
juju scp juju-restore 0:


juju-restore should be run on the primary controller machine in the MongoDB replica set. This is typically machine 0 in the controller model. All replica set nodes need to be healthy and in PRIMARY or SECONDARY state.

juju-restore requires a backup file created with juju create-backup. If you saved a local copy, use juju scp to copy this to the controller machine.

To perform the restore:

# SSH into the controller machine
juju ssh 0

# Start the restore! (it will ask for confirmation)
juju-restore /path/to/backup


By default, you can only restore from a backup created with exactly the same Juju version as the controller. If you run juju-restore with the --allow-downgrade option, you can also restore from a backup created with an earlier Juju version. This means that if you take a backup before upgrading the controller, and then hit a bug in the new Juju version, you can restore the backup to get back to the original version.

High availability (HA) operation

juju-restore supports restoring backups to high availability controllers, and can automatically stop and restart Juju agents and Mongo daemons on the secondary controller machines. If --manual-agent-control is specified or the user responds “no” when prompted, juju-restore expects the user to do this manually.

Other options

Additional options include:

  • --yes: answer “yes” to confirmation prompts (for non-interactive mode)
  • --include-status-history: restore the status history collection for machines and units (which can be large, and usually isn’t needed)
  • --username, --password, and related options, to override the defaults for connecting to MongoDB

For the full list of options, type: juju-restore --help

Last updated a month ago.