[Other doc versions]
[Doc downloads (PDF, HTML, XML)]
This page describes using the Stash Backup Client, which has been supported from Stash 2.8 and is the backup strategy that Atlassian recommends for most people.
For information about other backup strategies for Stash, see Data recovery and backups. That page also discusses the tight coupling between the Stash file system on disk and the database that Stash uses.
With any strategy, you should consider scheduling the backup window so as to minimise the impact on Stash availability. You might consider checking the access logs to determine patterns of lowest usage to help with this.
We highly recommend that you establish a data recovery plan that is aligned with your company's policies.
Questions? Check out FAQ - Data recovery and backup.
Download the Stash Backup Client from the Atlassian Marketplace, or from here:
Unzip the client into a directory on the Stash server.
The Backup Client implements a common and universal way to back up a Stash instance, and does the following:
A user will get an error message if they try to access the Stash web interface, or use the Stash hosting services, when Stash is in maintenance mode.
The client supports Windows and Linux platforms, and Stash versions 2.7 and higher, but does not provide ways to integrate with your organizations IT policies or processes.
As an indication of the unavailability time that can be expected when using the Stash Backup Client, in our testing and internal use we have seen downtimes for Stash of 7–8 minutes with repositories totalling 6 GB in size. For comparison, using Stash DIY Backup for the same repositories typically results in a downtime of less than a minute.
The Backup Client backs up all the following data:
The backup does NOT include the following files and directories:
export/*
log/*
(except for the audit logs)data/db*
(HSQL data in the DB is backed up, but the files on disk are not)tmp
plugins
directory (except for the installed-plugins
directory)
Note that the caches
directory is included in the backup because it contains previously indexed heads.
The Backup Client must be run from somewhere with access to the Stash home directory. Usually, you will run the Backup Client directly on the Stash server. Run the client with the following command:
java -jar <path/to/stash-backup-client.jar>
Configuration options are kept in the backup-config.properties
file that is included with the client – this file is automatically read when the client is run. The properties are fully documented in the backup-config.properties
file, but include:
| Defines the location of the home directory of the Stash instance you wish to back up or restore to. REQUIRED If omitted here it will be taken from the |
| Defines the username of the Stash user with administrative privileges you wish to perform the backup. REQUIRED If omitted here it will be taken from the Java system property of the same name if supplied to the Backup Client on the command line. As a required value, backup will fail if it is not supplied through one of these mechanisms. |
| Defines the password of the Stash user with administrative privileges you wish to perform the backup. REQUIRED If omitted here it will be taken from the Java system property of the same name if supplied to the Backup Client on the command line. As a required value, backup will fail if it is not supplied through one of these mechanisms. |
stash.baseUrl | Defines base URL of the Stash instance you wish to back up. REQUIRED E.g. http://localhost:7990/stash or http://stashserver/. If omitted here it will be taken from the Java system property of the same name if supplied on the command line to the Backup Client. As a required value, backup will fail if it is not supplied through one of these mechanisms. |
| Defines where the Backup Client will store its own files, such as backup archives. If not specified, these files are stored beneath the working directory for the Backup Client. Backup files will be stored in a Note that on Windows, you must use two backslashes between paths. E.g. |
Alternatively, these properties can be given on the command-line, when they need to be prefixed with "-D
", and be placed before the "-jar" parameter. For example:
java -Dstash.password="admin" -Dstash.user="admin" -Dstash.baseUrl="http://localhost:7990" -Dstash.home=path/to/stash/home -jar stash-backup-client.jar
You can cancel the running client backup operation if necessary.
To cancel the backup:
In order to ensure accidental restores do not delete existing data, the restore client will only restore into an empty home directory and an empty database. Therefore, if you intend to perform the restore into the current environment, make sure that these prerequisites are met.
Run the client with the following command:
java -Dstash.home="path/to/stash/home" -jar stash-restore-client.jar
When restoring Stash, the restore client must be run on the machine that Stash should be restored to. In order to ensure accidental restores do not delete existing data, the restore client will only restore into an empty home directory and an empty database.
The new database should be configured following the instructions in Connecting Stash to an external database and its sub-page that corresponds to your database type.
If you are using MySQL
The JDBC drivers for MySQL are not bundled with the Backup Client (due to licensing restrictions). You need to download and install the driver yourself.
<path/to/backup/client>
/jdbc
directory.The restore client also uses the backup-config.properties
file. The properties are fully documented in the backup-config.properties
file, but include:
| The full path to a directory that the restore client will populate with the Stash home data. This directory must be empty. On Windows, you must use two backslashes ( \\ ) or a single forward slash ( / ) to separate paths. |
jdbc.override | By default, the restore client will restore into the same database that was backed up. If |
jdbc.driver | The driver class that Stash should use to login to the new database. See examples below. |
jdbc.url | The connection details for the new database, formatted as a JDBC URL. See examples below. |
jdbc.user | The username that Stash should use to login to the new database. |
jdbc.password | The username that Stash should use to login to the new database. |
Example jdbc.driver
and jdbc.url
properties are shown below:
Database | jdbc.driver | jdbc.url |
---|---|---|
MySQL | com.mysql.jdbc.Driver | |
Oracle | oracle.jdbc.driver.OracleDriver | jdbc:oracle:thin:@//HOSTNAME:PORT/SERVICE |
PostgreSQL | org.postgresql.Driver | jdbc:postgresql://HOSTNAME:PORT/DATABASE |
SQL Server | com.microsoft.sqlserver.jdbc.SQLServerDriver | jdbc:sqlserver://HOSTNAME:PORT;databaseName=DATABASE; |
You can also set JDBC properties on the command line with the following command:
java -Djdbc.override=true -Djdbc.driver=org.postgresql.Driver -Djdbc.url=jdbc:postgresql://HOSTNAME:PORT/DATABASE -Djdbc.user=stashuser -Djdbc.password=password -Dstash.home="path/to/stash/home" -jar /path/to/stash-restore-client.jar /path/to/original/backup/file