Restoring with BOSH Backup and Restore

This topic describes how to use BOSH Backup and Restore (BBR) to restore a BOSH deployment or BOSH Director.

To back up a BOSH deployment or BOSH Director with BBR, see the Backing Up with BOSH Backup and Restore topic.

Perform the steps below to restore a BOSH Director, a BOSH deployment, or both.

Step 1: Recreate VMs

Before restoring a BOSH Deployment or director, you must create the VMs that constitute the deployment.

In a disaster recovery scenario, re-create the deployment with your BOSH deployment manifest. If you used the --with-manifest flag when running the BBR backup command, your backup artifact includes a copy of your manifest.

Step 2: Transfer Artifacts to Jumpbox

In the Backing Up with BOSH Backup and Restore topic, you moved the TAR and metadata files of the backup artifact off your jumpbox to your preferred storage space. Now you must transfer those files back to your jumpbox.

For instance, you could SCP the backup artifact to your jumpbox:

$ scp LOCAL_PATH_TO_BACKUP_ARTIFACT JUMPBOX_USER/JUMPBOX_ADDRESS

Step 3: Restore

Restore a BOSH Director

Perform the following steps to restore a BOSH Director:

  1. Ensure the BOSH Director backup artifact is in the folder you will run BBR from.
  2. Run the BBR restore command from your jumpbox to restore the BOSH Director:

    $ nohup bbr director \
      --private-key-path PATH_TO_PRIVATE_KEY \
      --username USER_NAME \
      --host HOST \
      restore \
        --artifact-path PATH_TO_DIRECTOR_BACKUP
    

    Use the optional --debug flag to enable debug logs. See the Exit Codes and Logging topic for more information.

    Replace the placeholder values as follows:

    • PATH_TO_PRIVATE_KEY: This is the path to the SSH private key used to connect to the BOSH Director.
    • USER_NAME: This is the SSH username of the BOSH Director.
    • HOST: This is the address of the BOSH Director, with an optional port that defaults to 22. If the BOSH Director is public, this is a URL, such as https://my-bosh.xxx.cf-app.com. Otherwise, this is the BOSH Director IP address.
    • PATH_TO_DIRECTOR_BACKUP: This is the path to the BOSH Director backup you want to restore.

Note: The BBR restore command can take a long time to complete. You can run it independently of the SSH session, so that the process can continue running even if your connection to the jumpbox fails. The command above uses nohup but you could also run the command in a screen or tmux session.

If the command fails, do the following:

  1. Ensure all the parameters in the command are set.
  2. Ensure the BOSH Director credentials are valid.
  3. Ensure the specified BOSH Director exists.
  4. Ensure that the jumpbox can reach the BOSH Director.
  5. Ensure the source BOSH Director is compatible with the target BOSH Director.
  6. Consult the Exit Codes and Logging topic.

Restore a BOSH Deployment

Perform the following steps to restore a BOSH deployment:

  1. Ensure the BOSH deployment backup artifact is in the folder you will run BBR from.
  2. Run the BBR pre-backup check:

    $ BOSH_CLIENT_SECRET=BOSH_CLIENT_SECRET \
      nohup bbr deployment \
      --target BOSH_TARGET \
      --username BOSH_CLIENT \
      --deployment DEPLOYMENT_NAME \
      --ca-cert PATH_TO_BOSH_SERVER_CERT \
      restore \
        --artifact-path PATH_TO_DEPLOYMENT_BACKUP
    

    Use the optional --debug flag to enable debug logs. See the Exit Codes and Logging topic for more information.

    Replace the placeholder values as follows:

    • BOSH_CLIENT, BOSH_CLIENT_SECRET: If you have a BOSH Director with User Account and Authentication (UAA) as the authentication provider, use a UAA client as the user name and a UAA client secret as the password. If you have a BOSH Director with basic auth configured, use your user name and password.
    • BOSH_TARGET: This is the FQDN or IP address of your BOSH Director.
    • DEPLOYMENT-NAME: This is the name of the deployment you want to restore.
    • PATH_TO_BOSH_SERVER_CERT: This is the path to the BOSH Director’s Certificate Authority (CA) certificate, if the certificate is not verifiable by the local machine’s certificate chain.
    • PATH_TO_DEPLOYMENT_BACKUP: This is the path to the BOSH deployment backup you want to restore.

      Note: The BBR restore command can take a long time to complete. You can run it independently of the SSH session, so that the process can continue running even if your connection to the jumpbox fails. The command above uses nohup but you could also run the command in a screen or tmux session.

If the command fails, do the following:

  1. Ensure all the parameters in the command are set.
  2. Ensure the BOSH Director credentials are valid.
  3. Ensure the specified BOSH deployment exists.
  4. Ensure that the jumpbox can reach the BOSH Director.
  5. Ensure the source BOSH deployment is compatible with the target BOSH deployment.
  6. Consult the Exit Codes and Logging topic.
Create a pull request or raise an issue on the source for this page in GitHub