Best practices for backup and restore

On this page

Jenkins, and deployments based on Jenkins, utilizes copy-on-write, sometimes referred to as COW. For backups, this is significant because it means that configuration changes are written to a temporary file and then moved to the proper file in $JENKINS_HOME. You will never have a partial write to $JENKINS_HOME, also known as an atomic move.

Even though Jenkins takes advantage of COW, it is recommended that you stop Jenkins if possible before performing a backup because the pipeline workflow XML files may get captured in an inconsistent state (for example if the backup does not take an 'instant snapshot' of every file at that exact moment).
Plugins are included in the backup of $JENKINS_HOME unless you exclude the plugins directory, but Jenkins itself is not.

Things to consider

When developing your backup and restore processes, consider the following:

  • Make sure you test your backups on a regular basis.

  • Keep rolling history of backups in case of data corruption.

  • Store the backup tar off the Jenkins host in case you lose the entire Jenkins host.

  • Keep multiple backups in multiple locales in case of natural disaster.

  • Consider storing credentials.xml and the secrets/ directory in different locations.

  • In case of local storage corruption, send the backup to a network drive, such as NFS-mounted directory.

    Users can configure a retention policy to delete the old backups that works for all the types of storage. However, when the backups use a local folder, the local folder stores other backups. This is a not a recommended practice. The directory needs to be configured to store only the backups of the instance. Do not use a shared folder with other instances or processes. The deletion process launched by the retention policy can cause that errors and loss of information because the deletion process may remove wrong backup files.