Documentation for JIRA 6.3. Not using this? See below:
(JIRA 6.2.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

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 backup tools, or JIRA's XML backup utility.

Icon

For production use, it is strongly recommended that for regular backups, you use native database backup tools instead of JIRA's XML backup service.

When JIRA is in use, XML backups are not guaranteed to be consistent as the database may be updated during the backup process. JIRA does not report any warnings or error messages when an XML backup is generated with inconsistencies and such XML backups will fail during the restore process. Native database backup tools offer a much more consistent and reliable means of storing (and restoring) data while JIRA is active.

Caveat: if you are migrating your instance, we recommend that you create an XML backup (per the directions in this guide) where possible. In certain cases, such as very large instance sizes, this may not be possible due to the system requirements for an XML backup.

Using native database backup tools

All serious databases come with tools to back up and restore databases (the 'MS' in RDBMS). 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.

See the documentation for your database on how to set up periodic backups. This typically involves a cron job or Windows scheduled task invoking a command-line tool like mysqldump or pg_dump .

Using JIRA's XML backup utility

To perform a once-off backup, e.g. before an upgrade, follow the steps below.

(info) You can also configure scheduled XML backups, as described in Automating JIRA Backups.

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Choose > System. Select Import & Export > Backup System to open the Backup JIRA data page.
    (tick) Keyboard shortcut: 'g' + 'g' + type 'backup'
    Screenshot: The Backup JIRA Data Page

    (info) As shown in the screenshot above, the backup will be stored within the export subdirectory of the JIRA Home Directory.
  3. In 'File name' field, type the name of the backup file.
    (info) Ensure that JIRA has the necessary file system permissions to write to this location. See the relevant procedures in the JIRA Installation and Upgrade Guide for details on creating a dedicated operating system account to run JIRA.
  4. Click the 'Backup' button and wait while your JIRA data is backed up.
    (info) JIRA will save your XML backup as a zipped archive file.
  5. When the backup is complete, a message will be displayed, confirming that JIRA has written its data to the file you specified.

2. Backing up the data directory

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).
  • 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.daily to ensure local conventions (file locations, lockfiles, permissions) are adhered to.

Your "attachments" directory may be located elsewhere

Icon

If you have put your attachments directory in a custom location (see Configuring File Attachments) rather than inside the data directory, you will also need to back up your attachments directory using the snapshot method described above.

18 Comments

  1. This is good but I had to do a bit of extra work to get production automated backups working. I guess most people will be administering a database system already and know how to do automated backups for that database. But for those that don't there is a bit of extra work here.

    I went with Postgres on Windows for the six starter license products, not having administered Postgres before.

    The link to pg_dump command is fine but it will not give you an automated solution. The following page will help Postgres users on Windows with automating the process http://wiki.postgresql.org/wiki/Automated_Backup_on_Windows

    If you use a .pgpass file as described on that page (which incidentally you could use with pg_dump or pg_dumpall), just make sure your scripts can access the .pgpass file, by setting the permissions correctly or having them in the same directory (eg your home directory) for instance.

    Additionally that page on the Postgres wiki doesn't tell you how to restore your backups. In the case of pg_dumpall you will want to use psql to restore, by giving the path to the backup file you created with pg_dumpall as the value for the -f or --file option. For all the options you need to supply read the psql 8.4 doc at http://www.postgresql.org/docs/8.4/static/app-psql.html

    To restore from a pg_dump you can use pg_restore http://www.postgresql.org/docs/8.4/interactive/app-pgrestore.html

    Backing up the data directory is no problem as it is like backing up any other ordinary directory.

    1. Anonymous

      If you are just looking for a quick solution to backup everything on your Postgresql instance, check out pg_dumpall.

      This command dumps everything to a .sql file which can then be restored in one hit as well.

      Some great info at http://www.commandprompt.com/ppbook/x17860 and also the basics at http://www.postgresql.org/docs/9.2/static/backup-dump.html#BACKUP-DUMP-ALL

  2. Anonymous

    The link to picozip takes you to a domain landing page.

  3. Anonymous

    Hi all,

    Can anyone help in in the issue that i am facing?

    I have backed up a file in Jira in XML format, and i need  to get the backed up data.

    the data has got stored onto the server file system, i need to locate the file and send it to my id.

    the message i got after back up was

    Backup JIRA data
     
    Data exported to: /apps/atlassian/data_4.2/export/dce_backup_2011_04_05

    Can anyone help me with this?

    1. Anonymous

      Same problem! Appending that to my own onjira.com account does NOT work.

      How on earth does one download the .ZIP file? 

      Henk

  4. Anonymous

    What is the difference between a "snapshot" (.. you need to create a snapshot of the ...) and a "copy" (.. a batch script copying ...) of the directory?

    I am aware that some filesystems (ZFS) allow to take snapshots of a directory, so that modifications to the content that are made while the backup is being created are not effecting the snapshot/backup.

    The propsed procedure for Windows does not handle concurrent modifications to the directories while the copy is being created.

    Also I don't see any easy out-of-the-box solution for Linux to implement this (see http://superuser.com/superuser.com/questions/252964/ )

    What is the *supported* procedure for creating backups of the data/attchment/... directories?

  5. Anonymous

    Target of referenced link http://www.picozip.com does not exists anymore (sad)

  6. Anonymous

    CentOS and prob other distro's - yum install zip unzip

    Windows - http://www.7-zip.org/download.html

    • Make sure to download correct version for Windows - as in 32 bit vs.64 bit. Can't remember why but its important
    • For correct file association to zip files etc - Once installed - Shift + Right click 7zip icon and click "Run as Administrator" then click select all or pick your extensions. Click Ok. Go and check that zip files now can be opened with 7zip
    • Only 7zip downside - spanned archives from WinZip users are not extractable. I think! As in zip files that have been split up on creation.
  7. The documentation for the PostgreSQL pg_dump backup utility (at http://www.postgresql.org/docs/8.4/static/app-pgdump.html) mentions a parameter for Object Identifiers:

    -o, --oids  Dump object identifiers (OIDs) as part of the data for every table. Use this option if your application references the OID columns in some way (e.g., in a foreign key constraint). Otherwise, this option should not be used.

    So, is it best to include object identifiers when backing up my PostgreSQL 8.4 JIRA database, or does JIRA not reference them?  I am running JIRA 4.4 at present, but plan to upgrade to 5.0 soon.

  8. FYI: Backing up a MSSQL Server database from SSMS is as easy as right-clicking on the JIRA database, select Tasks->Backup..., (I accept all the defaults) and hit OK. For me it's near-instantaneous.

     

  9. Anonymous

    what is creating a snapshot? Can I just cp -r the entire data directory to a backup location? Would that be considered creating a snapshot and would it work for the purpose of restoring my data?

    1. You got it. "cp -r" of data directory + db backup = good to go.

      Only thing you should backup too is the caches diretory or at least the caches\indexes dir or you have to rebuild the index from inside JIRA after restoring from backup.

       

  10. Just some quick remarks for JIRA on Windows Server, which took me some time to fix:

    I made a simple .cmd script for the backup, which stops the JIRA instance before backup and uses sub-scripts for the different tasks:

    call stop_service.bat
    TIMEOUT /T 30
    call BackupJiraData.cmd > DataBackup.log
    call BackupJiraDb.cmd > DbBackup.log
    call start_service.bat

     

    Remarks:

    1. use the "call"-statement for starting other scripts, because otherwise the script stops in case of error (e.g. JIRA-process is already stopped) . By using "call", the rest of the script runs through.
    2. call "TIMEOUT /T 30" to make the script sleep for 30 seconds, because otherwise some files in the data-directory are still locked and 7-Zip complains, that it cannot access the file.
    3. redirect output of backup-scripts to log-files to be able to check the next morning, if everything went OK

     

    BackupJiraData.cmd

    set DATE_FORMAT=%DATE:~6,4%-%DATE:~3,2%-%DATE:~0,2%
    7z.exe a -r -tzip %DATE_FORMAT%_JiraData.zip D:\JIRA-HOME\data\*

    BackupJiraDb.cmd (for MySQL-Server)

    set DATE_FORMAT=%DATE:~6,4%-%DATE:~3,2%-%DATE:~0,2%
    mysqldump.exe -v -h localhost --user=JiraUser --password=xxxxxxx --port=3306 --databases jira_db --result-file=%DATE_FORMAT%_JiraMySqlDump.sql
    7z.exe a -tzip %DATE_FORMAT%_JiraMySqlDump.zip %DATE_FORMAT%_JiraMySqlDump.sql
    If not errorlevel 0 goto script_end
    del JiraMySqlDump_%DATE_FORMAT%.sql
    :script_end
  11. Can I please get a bit of clarification on the warning?

    In the first line, it says, "For production use, it is strongly recommended that for regular backups, you use native database backup tools instead of JIRA's XML backup service."

    In the last line, the caveat says, "Native tools run a much higher risk of failure and/or corruption if used for migration or disaster-recovery purposes"

    Am I reading this correctly?  Aren't these two lines contradicting?  What should I use to backup on a nightly basis in order to recover in case of disaster?

    1. They were contradicting, thanks for pointing this out. We've updated them. (smile) It's recommended to use the native DB tools on a nightly basis.

  12. Anonymous

    I agree. It's very confusing ...

  13. Is there a way to back up just the JIRA configuration data, as opposed to all the issue data?  I have to implement a project in a Prod server after getting it set up in Dev with dummy issues.

    1. Hi Ray,

      There is a way to create back up of the configuration data. Simply create a System or Project level snapshot from the Dev instance and then deploy it to Production using this add-on:  https://marketplace.atlassian.com/plugins/com.botronsoft.jira.configurationmanager