This page describes how to back up your JIRA data, and establish processes for maintaining continual backups. Backing up your JIRA data is the first step in upgrading your server to a new JIRA revision, or splitting your JIRA instance across multiple servers. See also Restoring JIRA data and Restoring a Project from Backup.
Creating a complete backup of JIRA consists of two stages:
1. Backing up database contents
There are two possibilities: native database-specific tools, or JIRA's XML backup utility.
For production use, it is strongly recommended to use native database-specific tools instead of the XML backup service. XML backups are not guaranteed to be consistent, as the database may be updated during the backup process. Inconsistent backups are created successfully without any warnings or error messages, but fail during the restore process. Database-native tools offer a much more consistent and reliable means of storing data.
Using native database tools
All serious databases come with tools to back up and restore databases (the 'MS' inRDBMS). We strongly recommend these tools in preference to the XML backup option described below, as they:
- ensure integrity of the database by taking the backup at a single point in time
- are much faster and less resource-intensive than JIRA's XML backup.
- integrate with existing backup strategies (e.g. allowing one backup run for all database-using apps).
- may allow for incremental (as opposed to 'full') backups, saving disk space.
- avoid character encoding and format issues relating to JIRA's use of XML as a backup format.
Using JIRA's XML backup utility
To perform a once-off backup, e.g. before an upgrade, follow the steps below. (Note that you can also configure scheduled XML backups, as described in Automating JIRA Backups. )
- Log in as a user with the 'JIRA System Administrators' global permission.
- Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
- Under the 'Import & Export' sub-menu in the left-hand navigation column, click the 'Backup Data to XML' link. This will display the 'Backup JIRA data' page:
Screenshot: The Backup JIRA Data Page
If you see the following message at the top of this page, you will need to set a safe backup path first (by following the procedure below) and then restart this particular procedure from step 1 (above).
- In 'File name' field, type the full path, including filename, of the location to which you want JIRA to write the backup file. Note: Ensure that JIRA has rights to write to this location.
- (Optional but recommended) Select the 'Backup as Zip' checkbox.
- Click the 'Backup' button, and wait while your JIRA data is backed up.
- When the backup is complete, a message will be displayed, confirming that JIRA has written the data to the file you specified.
Setting a safe backup path
Due to security vulnerabilities in JIRA that have been fixed in JIRA 4.1.1 and later (and in earlier versions of JIRA that have been fixed via patches available from JIRA Security Advisory 2010-04-16), it is now a mandatory requirement to explicitly set a safe backup path in JIRA before JIRA data XML backups can be performed.
To set a safe backup path, where JIRA data XML backups will be stored:
- Shutdown JIRA.
- Open the
jira-application.propertiesfile in a text editor. Refer to Advanced JIRA configuration with jira-application.properties for details.
- Locate the
jira.paths.safe.backup.pathvaribale in this file.
- Set this variable's value to a valid and safe directory path for the operating system on which JIRA runs. A safe path is one which excludes the JIRA web application directory and other sensitive areas of the operating system.
Examples of valid directory paths used with this variable:
- UNIX-based systems (e.g. Linux or Mac OS X)
- Windows systems
- Restart JIRA.
2. Backing up the
data directory is a sub-directory of your JIRA Home Directory. It contains application data for JIRA, e.g. if you have attachments enabled, all files attached to JIRA issues are stored in the
data\attachments directory (not in the database).
To back up the
data directory , you need to create a snapshot of the
data directory (including all files and subdirectories), then back up the snapshot. Note that the directory structure under the
data directory must be preserved in the snapshot.
Creating this snapshot is an operating system-specific task, e.g.:
- On MS Windows, a batch script copying the directory can be written and scheduled periodically (Programs > Accessories > System Tools > Scheduled Tasks). There are also various utilities available to simplify this (eg. http://www.picozip.com).
- On Linux/Solaris, it is best to write a small shell script, placed in
/etc/cron.daily, backing up files to a directory like
/var/backup/jira. It is best to copy an existing script in
/etc/cron.dailyto ensure local conventions (file locations, lockfiles, permissions) are adhered to.
Your "attachments" directory may be located elsewhere
If you have put your
attachments directory in a custom location (see Enabling File Attachments) rather than inside the
data directory, you will also need to backup your
attachments directory using the snapshot method described above.