Backing Up with BOSH Backup and Restore

This topic describes how to use BOSH Backup and Restore (BBR) to back up a BOSH deployment or BOSH Director. Perform the steps below to back up a BOSH Director, a BOSH deployment, or both.

To perform a restore, see Restoring with BOSH Backup and Restore.

Prerequisite

If you want to use the result of the backup to restore to a destination environment, verify that the current environment and the destination environment are compatible. For information, see Compatibility of Restore.

Back Up a BOSH Director

Follow these steps to verify that your BOSH Director is reachable and can be backed up with BBR and then perform the backup.

  1. SSH into your jumpbox.
    For general information about the jumpbox, see Installing BOSH Backup and Restore.

  2. Run the BBR pre-backup check:

    bbr director --private-key-path PATH-TO-PRIVATE-KEY --username USER-NAME --host HOST pre-backup-check

    Where:

    PATH-TO-PRIVATE-KEY: The path to the SSH private key used to connect to the BOSH Director.

    USER-NAME: The SSH username of the BOSH Director.

    HOST: 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.

    For example,

    $ bbr director \
        --private-key-path bosh.pem \
        --username vcap \
        --host bosh.example.com \
        pre-backup-check
    
  3. If the pre-check command fails, do the following:

    • Run the command again adding the --debug flag to enable debug logs. For more information, see Exit Codes and Logging.
    • Make the fix suggested in the output and run the pre-backup check again.
      For example, the command fails if the BOSH Director selected did not have the correct backup scripts or if the connection to the BOSH Director failed.
  4. Run the BBR backup command from your jumpbox to back up your BOSH Director:

    bbr director --private-key-path PATH-TO-PRIVATE-KEY --username USER-NAME --host HOST backup

    Where the variables are the same step 2 above.

    For example,

    $ bbr director \
      --private-key-path bosh.pem \
      --username vcap \
      --host bosh.example.com \
      backup
    
  5. If the backup command completes successfully, follow the steps in Good Practices for Managing Your Backup Artifact below.

  6. If the backup command fails, do the following:

Back Up a BOSH Deployment

Perform the following steps to check that your BOSH Director is reachable and has a deployment that can be backed up:

  1. SSH into your jumpbox.
    For general information about the jumpbox, see Installing BOSH Backup and Restore.

  2. Run the BBR pre-backup check:

    BOSH_CLIENT_SECRET=BOSH-CLIENT-SECRET bbr deployment --target BOSH-TARGET --username BOSH-CLIENT --deployment DEPLOYMENT-NAME --ca-cert PATH-TO-BOSH-SERVER-CERT pre-backup-check


    Where:

    BOSH-CLIENT-SECRET: If you have a BOSH Director with User Account and Authentication (UAA) as the authentication provider, this is a UAA client secret as the password.
    If you have a BOSH Director with basic auth configured, this is your password.

    BOSH-TARGET: The FQDN or IP address of your BOSH Director.

    BOSH-CLIENT: If you have a BOSH Director with User Account and Authentication (UAA) as the authentication provider, this is a UAA client as the username.
    If you have a BOSH Director with basic auth configured, this is your username.

    DEPLOYMENT-NAME: The name of the deployment you want to back up. For a list of deployments, run bosh deployments.

    PATH-TO-BOSH-CA-CERT: The path to the BOSH Director’s Certificate Authority (CA) certificate if the certificate is not verifiable by the local machine’s certificate chain:

    • If you used bbl spin up your director to retrieve the CA cert with bbl director-ca-cert.
    • If you manually deployed then it may be stored in a secrets.yml or similar.

    For example,

    $ BOSH_CLIENT_SECRET=p455w0rd \
      bbr deployment \
      --target bosh.example.com \
      --username admin \
      --deployment cf-acceptance-0 \
      --ca-cert bosh.ca.cert \
      pre-backup-check
    
  3. If the pre-backup check command fails, do the following:

    • Run the command again adding the --debug flag to enable debug logs.
      For more information, see Exit Codes and Logging.
    • Make the fix suggested in the output and run the pre-backup check again.
      For example, the deployment you selected might not have the correct backup scripts, or the connection to the BOSH Director failed.
  4. If the pre-backup check succeeds, run the BBR backup command from your jumpbox to back up your BOSH deployment:

    BOSH_CLIENT_SECRET=BOSH-CLIENT-SECRET nohup bbr deployment --target BOSH-DIRECTOR-IP --username BOSH-CLIENT --deployment DEPLOYMENT-NAME --ca-cert PATH-TO-BOSH-SERVER-CERT backup

    Replace the placeholder values with the same values as above.

    Note: If you want to include the manifest in the backup artifact, add the --with-manifest flag. However, be aware that the backup artifact then includes credentials that you need to keep secret.

    For example,

    $ BOSH_CLIENT_SECRET=p455w0rd \
        nohup bbr deployment \
        --target bosh.example.com \
        --username admin \
        --deployment cf-acceptance-0 \
        --ca-cert bosh.ca.cert \
        backup

    Note: The BBR backup 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.

  5. If the command completes successfully, follow the steps in What To Do with Your Backup Artifact below.

  6. If the backup command fails, do the following:

Recovering from a Failing Command

If the backup fails for the BOSH Director or deployment, follow these steps:

  1. Ensure all the parameters in the command are set.
  2. Ensure the BOSH Director credentials are valid.
  3. If you are backing up a deployment, ensure the deployment you specify in the BBR command exists.
  4. Ensure that the jumpbox can reach the BOSH Director.
  5. Consult Exit Codes and Logging.
  6. If you see the error message Directory /var/vcap/store/bbr-backup already exists on instance, run the appropriate cleanup command. See Clean Up after a Failed Backup below.
  7. If the backup artifact is corrupted discard the failing artifacts and rerun the backup.

Cancel a Backup

Backups can take a long time. If you need to cancel a backup, for example if you realize that the backup is going to fail or that your developers need to push an app in a hurry, follow these steps:

  1. Terminate the BBR process by pressing Ctrl-C and typing yes to confirm.
  2. Because stopping a backup can leave the system in an unusable state and prevent additional backups, follow the procedures in Clean Up after a Failed Backup below.

Clean Up after a Failed Backup

If your backup process fails, it might leave the BBR backup folder on the instance, causing any subsequent attempts to backup to fail. In addition, BBR might not have run the post-backup scripts, leaving the instance in a locked state.

Follow the steps below to use the BBR cleanup script to tidy up after a failed backup attempt.

  1. If the BOSH Director backup failed, run the following command:

    bbr director --private-key-path PATH-TO-PRIVATE-KEY --username USER-NAME --host HOST backup-cleanup

    $ bbr director \
        --private-key-path bosh.pem \
        --username vcap \
        --host bosh.example.com
        backup-cleanup
    
  2. If the BOSH deployment backup failed, run the following command:

    BOSH_CLIENT_SECRET=BOSH-CLIENT-SECRET bbr deployment --target BOSH-TARGET --username BOSH-CLIENT --deployment DEPLOYMENT-NAME --ca-cert PATH-TO-BOSH-CA-CERT backup-cleanup

    For example,

    $ BOSH_CLIENT_SECRET=p455w0rd \
    bbr deployment \
    --target bosh.example.com \
    --username admin \
    --deployment cf-acceptance-0 \
    --ca-cert bosh.ca.crt \
    backup-cleanup
    
  3. If the cleanup script fails, consult the following table to match the exit codes to an error message.

    Value Error
    0 Success
    1 General failure
    8 The post-backup unlock failed. Your BOSH deployment or BOSH Director might be in a bad state and require attention.
    16 The cleanup failed. This is a non-fatal error indicating that the utility has been unable to clean up open BOSH SSH connections to the deployment VMs. Manual cleanup might be required to clear any hanging BOSH users and connections.


    For more information about how to interpret the exit code, see Exit Codes.

Good Practices for Managing Your Backup Artifact

Keep your backup artifact safe by following these steps:

  1. Move the backup artifact off the jumpbox to your storage space.

    BBR stores each backup in a subdirectory named DEPLOYMENT-TIMESTAMP within the current working directory. The backup created by BBR consists of a folder with the backup artifacts and metadata files.

  2. Compress and encrypt the backup artifacts when storing them.

  3. Make redundant copies of your backup and store them in multiple locations.

    This minimizes the risk of losing your backups in the event of a disaster.

  4. Each time you reploy Cloud Foundry, test your backup artifact by following the procedures in Restoring with BOSH Backup and Restore.

Create a pull request or raise an issue on the source for this page in GitHub