Restore backups created with the CloudBees Backup plugin

The CloudBees Backup Plugin is only available for CloudBees CI. This chapter explains how to restore from a backup created with the CloudBees Backup Plugin. Refer to Restoring $JENKINS_HOME manually to restore other Jenkins-based deployments.

Restoring from backup (using a restore job)

Controller with CloudBees Backup Plugin 3.38 or later installed have support for the Restore job type. The operations center does not have a restore option, so to restore an operations center when using CloudBees CI on traditional platforms you can follow the steps for Restoring manually. If you are using CloudBees CI on modern cloud platforms, follow to steps to Backup and restore on Kubernetes - Using a rescue-pod.

To restore a backup:

Select New Item from the left pane.
Select Backup and Restore and enter an item name.
Select OK.

After you select OK, you are directed to the restore job configuration. Configuration of a restore job is very similar to that of a Freestyle job.
Under the Build heading, select Add build step and Restore from backup.
Then, just like a backup job, you must configure where the backup is retrieved from. The latest backup available in the given source will be used to restore. If the backups were created with an operations center cluster operation, all backups will be in the same location. It is recommended that you create a new directory and add the specific backup that you would like to restore from in that new directory, and point the restore job at that directory instead.
When running the restore job, the backup file is downloaded from the configured backend to the Jenkins filesystem, checked for integrity, then unpacked. After these steps are completed, you will be prompted to restart the Jenkins instance.
Upon restart, $JENKINS_HOME is replaced with the content of the backup file, and the restore process is complete.

Restore is supported only from full backup files

The restore process will replace the current $JENKINS_HOME with the data from backup archive. Therefore it is important to restore from a full backup. If there is data in $JENKINS_HOME that is not in the backup and needs to be kept, select the Advanced button under Restore options and select the Preserve Jenkins home contents checkbox. This will copy the current $JENKINS_HOME into a directory named archive-<timestamp>.

Excluding files from a restore job

When a restore job is performed, everything in the $JENKINS_HOME directory is moved to a file named archive_<timestamp>. If you have files that are introduced by the file system in your $JENKINS_HOME directory, for example .snapshot files, you must exclude them from the restore process or you will receive an error when you try to restore.

To exclude system files from the restore process on a CloudBees CI on traditional platforms client controller:

In the backup job, add a comma-separated list of Ant-style patterns in the system configuration excludes list.

See Setting backup options for more information.
In the restore job, select the Advanced button.
Select the Preserve Jenkins home contents checkbox under Restore options.

Restart the client controller, using the following system property:

-Dcb.backup.restore.keepFilesPattern='<Ant-style patterns>▼

Example with Ant-style patterns to exclude .snapshots files:

-Dcb.backup.restore.keepFilesPattern='.snapshots,**/.snapshots'▼

To exclude system files from the restore process on a CloudBees CI on modern cloud platforms managed controller:

In the backup job, add a comma-separated list of Ant-style patterns in the system configuration excludes list.

See Setting backup options for more information.
In the restore job, select the Advanced button.
Select the Preserve Jenkins home contents checkbox under Restore options.
From the operations center, select Manage Jenkins Configure Controller Provisioning.
Under the Additional options heading, add the following system property to Global System Properties:
```
cb.backup.restore.keepFilesPattern=<Ant-style patterns>▼
```
Example with Ant-style patterns to exclude .snapshots files:
```
cb.backup.restore.keepFilesPattern=.snapshots,**/.snapshots▼
```
Select Save. If you are restoring a backup from the controller, a message will appear in the restore log about creating a [.confxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] hidden file in the $JENKINS_HOME folder and then restarting Jenkins.

Example: In order to initiate the restore after shutting this Jenkins instance down, you will need to touch the file [.confxxxxxxxxxxxxxxxxxxxxxxxxxxxx] in the $JENKINS_HOME folder.
Select the gear icon for the controller.
Select Restart under Manage in the left navigation pane.

After you have re-provisioned the controller, you should see the new system property listed the controller’s menu:Manage Jenkins [System Information].