FishEye data can be backed up from the admin interface or command line. This page contains the command syntax, options and the required procedure to backup and restore your FishEye instance.
On this page:
If you are migrating to a different machine, please follow the instructions form our Migrating FishEye Between Servers page.
Backing Up FishEye Data
The FishEye Admin Interface Backup Process
1. Navigate to the FishEye 'Admin' screen (click the 'Administration' link in the footer of any FishEye page).
2. On the Admin screen, click 'Backup' under the 'System' heading in the left navigation bar. The Backup screen opens.
3. On the Backup screen, the 'File Path' field indicates where the backup file (in .zip format) will be stored. You can manually edit this path to change it. Under the heading 'Include', a list of checkboxes is shown, with the following items:
- Plugins and their configuration data
- SQL database
- Web templates
- Uploaded files and local copies of files under review.
- Repository and application caches.
Repository and application caches contain temporary data stored from repository scans and library caches that improve startup time. Both will be recreated automatically by re-scanning the source repositories, so the backup files can be reduced by a significant amount by excluding these (if the cost of re-scanning is acceptable).
4. Once you have chosen your options, click 'Create Backup Now'.
Screenshot: The FishEye Backup Screen
The FishEye Command Line Backup Process
Your FishEye instance must be running during the backup.
- Open a command line interface on the FishEye server computer.
- Navigate to the
FISHEYE_HOME/bin/directory. - Run the backup command on the command line with the desired options.
- The backup is created as a new Zip archive file and placed in the
FISHEYE_INST/backup/directory.
Note that if your FishEye instance uses a custom FISHEYE_INSTdirectory, make sure the environment variable is properly set when running the backup command.
Components of a FishEye Backup
The FishEye backup is highly configurable and allows for many different configurations. This table shows the various components of the backup, what they are for and how they can be used.
Component | Purpose | Defaults |
|---|---|---|
SQL Database | Refers to the SQL content database (used by both FishEye and Crucible and containing all user profile data, reviews and their comments). | Backed up by default. |
Cache | The cache contains data that reflects the state of FishEye's repositories. Without it, FishEye must re-scan its repositories after a backup is restored. The cache also contains OSGI library data that increases startup time. These too can be excluded and will be generated automatically when the application is started. | The cache is not backed up by default as it tends to be large (running a risk of pushing the maximum file size for Java backups), whilst also representing replaceable data. |
Plugins | Plugins are 3rd-party extensions that you may have installed, and configuration for all plugins (this includes configuration for Crucible's set of standard plugins). | Configuration data for all plugins are backed up by default, as well as all plugins installed in |
Templates | In this context, these are custom freemarker templates that you or your users have created. They live in | Templates are backed up by default. You can choose to exclude them from the backup if your templates directory is covered by some other backup mechanism. |
Uploads | In this context, uploads refers to files which are added to Crucible via the web interface (such as patch file reviews). It also includes each repository-backed file that went under review, when Crucible is configured to make a local copy of every reviewed file. | Uploads are backed up by default. You can choose not to back them up for example when the |
| ActiveObjects | Data that is stored by plugins | Backed up by default. |
Note that the backup will always include the configuration data (config.xml), your license file and the FishEye user data.
Backup Command Line Options
These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the FISHEYE_HOME/bin/ directory.
The basic syntax of the backup command is as follows:
To see inline help for all backup options, run the following command in the FISHEYE_HOME/bin/ directory:
Option | Switch | Description | Default setting |
|---|---|---|---|
Quiet mode | -q OR --quiet | Suppresses output | No |
Output filename | -f OR --file | Specify a different path and filename to the |
|
Compression level | --compression OR -c | Sets the Zip compression level, from 1-9. Runs at level 6 if no argument is passed. | Yes (6) |
Anonymise | -a OR --anonymise | Anonymises the SQL database by replacing all text with 'x'. This is only useful when sending a backup to Atlassian as part of a support case. Please do not anonymise data unless the Support Engineer handling your support case has specifically requested the data anonymised (as often anonymised data will not help reproduce the issue). | No |
Cache Backup | --cache | Include the repository caching files in the backup. These hold information gained from scanning the repositories and can be quite large (many gigabytes). However, it can shorten the time needed to re-scan the repositories after data is restored. | No. By default, the cache data is excluded from backups. |
Command Line Examples
These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the FISHEYE_HOME/bin/ directory.
Backing up with compression of 9, quiet mode and setting an output location
Backup including cache data (also includes all default components)
Restoring a backup with cache data (also restores all default components)
Advanced Backup Command Line Settings
In some cases it might be preferable to only backup a limited set of items. This could be useful when your instance uses an external database such as MySQL Enterprise Server or PostgreSQL and your DBA has already configured automatic backups in the database. The commands below allow this.
Option | Switch | Description | Default |
|---|---|---|---|
Exclude Plugins | --no-plugins | Excludes plugins from the backup. | No. By default, plugins are included in every backup. |
Exclude Templates | --no-templates | Excludes templates from the backup. | No. By default, templates are included in every backup. |
Exclude Uploads | --no-uploads | Excludes uploaded files (such as patch reviews, stored in Crucible's internal database) from the backup. | No. By default, uploads are included in every backup. |
Exclude SQL Database | --no-sql | Excludes the SQL content database used by both FishEye and Crucible. | No. By default, this data is included in every backup. |
Show help | --help OR -h | Shows inline help on the command line. | No |
Known Limitations
Please note that the below limitations are common for any Java based backup tool.
Archives Containing Over 65535 Files
Versions of Java earlier than v1.6 (b25) are incapable of handling zip files that contain more than 65,535 files. The solution for this problem is to either upgrade to a version of Java later than v1.6 (b25), or ensure that the archive does not exceed the threshold (contains less than 65,535 files). The FishEye cache (not included in backups by default) can be a contributor of many small files. Hence, exclude the cache from backups if this is likely to be a concern.
Archives Larger Than 4GB
Java has trouble reading and writing zip files that are larger than 4GB. As of release 1.5 Java appears capable of reliably creating archives that are over 4GB, but remains unable to extract them. For details see Sun's bug report. Also be aware of the fact that some file systems (including FAT32) have trouble with files larger than 4GB.
As a workaround, make sure you do not create archives that are larger than 4GB. The FishEye cache (not included in backups by default) can be a contributor of a lot of small files (although these tend to compress very well). If you still want to archive everything and end up with an achive that is too large, consider creating separate backups for the FishEye cache and uploaded files respectively.
Scheduling FishEye Backups
To set a schedule for automatic backups, open the administration screen and click 'Backup' under 'System' on the left navigation bar. The 'Backup' page opens. Now, click the link 'Manage Scheduled Backups' at the bottom of the page. The 'Scheduled Backups' page opens.
On the 'Scheduled Backups' page, click 'Edit' to adjust the backup schedule. Set the desired options and click 'Save'.
The options for scheduled backups are detailed in the table below.
Option name | Description | Allowed Values |
|---|---|---|
Disable Scheduled Backups | Stops regular backups from taking place. | On (disabled) or Off (enabled) |
Backup path | The path where the backup .zip file will be stored. | Any system or network path that FishEye or Crucible can access. |
Backup file prefix | Characters that will be added to the beginning of the backup file name. | Any string of characters that can be used as part of a filename on the local operating system. |
Backup file date pattern | Sets a date for the next (or initial) backup to take place. | Any valid date in the format |
Backup frequency | Sets how often the backup will take place. | Can be set to 'every day', 'every Sunday', 'Monday to Friday' and 'first day of the month'. |
Backup time (HH:mm) | The time when the backup will take place. | Any valid 24-hour time in the format |
Include | Specifies which items must be included in the backups (these components are explained at the top of this page). | As per the options for regular on-demand backup (These components are explained at the top of this page). |
Screenshot: Scheduling Backups in FishEye
Be aware that scheduled backups can fill up disks unless you regularly move or delete old archives.
Restoring FishEye Data
The FishEye Data Command Line Restoration Process
There is currently no way to restore a backup from the web interface because FishEye must be shut down during a data restore.
Restoring a backup will irreversibly overwrite the data of your installation with the data from the backup archive.
- Install FishEye into a new, empty directory (this must be the same version that the backup was created from, or later).
Note that you cannot restore data into versions of FishEye which are older than the version that created the backup. - Make sure the FishEye instance is not running.
- Open a command line interface on the FishEye server computer.
- Run the restore command on the command line with the desired options.
- The specified elements will be restored.
- Start the FishEye instance.
- When using FishEye integrated with Crucible, you will need to re-index your repositories after restoring data, unless the backup archive was created with the
--cacheoption.
Restore Command Line Options
These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the FISHEYE_HOME/bin/ directory.
The basic syntax of the restore command is as follows:
To see inline help for all backup options, run the following command in the FISHEYE_HOME/bin/ directory:
Restores a FishEye/Crucible backup instance.
If you are using an external database (as opposed to the default built-in database), make sure the JDBC driver file is present in the FISHEYE_INST/lib directory when running restore.
Option | Switch | Description | Default |
|---|---|---|---|
Suppress output | --quiet OR -q | Suppress the output messages from the restore program on the command line. | No |
Choose file to restore from | --file PATH/FILENAME OR -f PATH/FILENAME | Restore the backup from PATH/FILENAME. | Yes (required) |
Show inline help | --help OR -h | Displays help for options on the command line. | No |
Advanced Command Line Restore Settings
By default, the restore program will restore all items found in the backup archive (so if you included the caches using the --cache option, these will automatically be restored). However, it is possible to only restore a subset of items from the backup, by explicitly specifying the item names on the command line and only those will be restored.
Option | Switch | Description |
|---|---|---|
Restore FishEye cache | --cache | Restore the repository cache backup. |
Restore plugins | --plugins | Restore 3rd-party plugins and their configuration data. |
Restore templates | --templates | Restore freemarker templates from the backup (the restored instance will use the built-in templates). |
Restore uploads | --uploads | Restore uploads (e.g. patch files uploaded into Crucible and contents of files under review). |
Restore Crucible reviews | --sql | Restore the SQL database containing user profiles, reviews and review comments. |
Set database type | --dbtype OR -t | SQL database type ('mysql', 'postgresql', 'oracle', 'sqlserver2005', 'sqlserver2008', or 'built-in'). Only required when restoring to a database location different to that used at used at backup time. |
Set JDBC URL | --jdbcurl OR -j | JDBC URL of the SQL database. Only required when restoring to a database location different to that used at used at backup time (not applicable for 'built-in'). |
Set JDBC username | --username OR -u | JDBC username of the SQL database. Only required when restoring to a database location different to that used at used at backup time (not applicable for 'built-in'). |
JDBC password | --password OR -p | JDBC password of the SQL database. Only required when restoring to a database location different to that used at used at backup time (not applicable for 'built-in'). |
JDBC class | --driver OR -d | Specifies the JDBC driver class name needed to access the SQL database. Only required when restoring to a database location different to that used at used at backup time and when using a different JDBC driver than the standard driver associated with the database specified though |
Notes on Migrating Backup Data
When the process restores a SQL database, it looks at the configuration data (config.xml) included in the backup archive to learn which database product was used and how to connect to it. When FishEye uses the built-in HSQLDB database (which is the default), the restored instance will also use that.
However, when the restored instance will use a different database than the backed up instance (for instance, HSQLDB was used at the time the backup was created, but it needs to be restored on MySQL Enterprise Server), use the command line options to point the process to the new database.
Command Line Example: Migrating Backup Data to MySQL Enterprise Server
These examples are for use in a Linux-like operating system. When using these commands on Windows, use the filename fisheyectl.bat and use the correct slashes. Run the command from the FISHEYE_HOME/bin/ directory.
Restoring to a FishEye instance that uses a different database (ensure the MySQL Enterprise Server driver jar file is present in the FISHEYE_INST/lib directory)
6 Comments
Hide/Show CommentsJun 30, 2010
Anonymous
This page is out-of-date for version 2.3. The backup screen doesn't allow for the file path to be changed. It does say that the path may be changed by editing config.xml, but I can't seem to find any documentation on exactly what to change in config.xml to write the backups to a different path.
Jul 30, 2010
Bob Swift
Could you please add information about what coordination is required when backing up and restoring cache data separately from the rest of the data? For instance, is it possible to save cache data and later run the rest of the backup. Maybe only save the cache data once a week but backup the other data nightly. Does this work on restore or will it cause problems because they are out of sync?
Aug 08, 2010
Andy Brook
As of 2.3.5 This page does not reflect the automated backup. The UI refers to:
Yet there is no indicator as to what field, and the existing config.xml backup 'chunk' contains nothing specific:
Can the aspect of backup location be brought up to date?
– edited:
So, there is an .xsd in the root folder, which identifies path as the magic attribute, for anyone else needing that nugget
Jan 11, 2011
Anonymous
This page should really mention the "not a bug" http://jira.atlassian.com/browse/CRUC-4280 which requires you to copy the database drivers before the restore works.
Mar 02, 2011
Matt Doar (CustomWare)
I see a working backup as the ability to save and restore the state of an application. Saving seems to work fine for fecru, but when the restore steps start with directions for a complete reinstallation that seems, er, unsatisfying!
Apr 30, 2011
Anonymous
Interesting thing to note, if you're doing a RESTORE and you're restoring from one system to another system, and you want to use a new DB, even if the db is the same type you have to specify the dbtype otherwise it will ignore ALL the parameters you pass. In otherwords:
./fisheyectl.sh restore --jdbcurl jdbc:postgresql://localhost:5432/fisheyedb --username username --password thepassword --force --file /mnt/jira/fisheyeMove.zip
won't work but
./fisheyectl.sh restore --dbtype postgresql --jdbcurl jdbc:postgresql://localhost:5432/fisheyedb --username username --password thepassword --force --file /mnt/jira/fisheyeMove.zip
Does. Even if it's the same db type you're moving to, you need to specify the dbtype or you can't override defaults.
Add Comment