Using the Stash Backup Client
This page describes using the Stash Backup Client, which is the backup strategy that Atlassian recommends for most people running Stash Server instances. This tool can be used to backup data from Stash Server instances from release 2.7.0 and later.
The Stash Backup Client is not compatible with Stash Data Center instances running two or more cluster nodes. To back up an instance of Stash Data Center, you must either:
- bring down all the cluster nodes except one, or
- switch to Stash DIY Backup instead of the Stash Backup Client.
For information about other backup strategies for Stash, see Data recovery and backups.
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.
How it works
The Backup Client implements a common and universal way to back up a Stash instance, and does the following:
- Locks access to the Stash application, the repositories managed by Stash and the Stash database for the entire duration of the back up. This state is called 'maintenance mode'.
- Checks that all Git and database operations have completed.
- Performs an application-specific backup of the Stash home directory and the Stash database. The backup is generic and does not depend on the server or database configuration.
- Stores the backup as a single tar file on the local filesystem in the specified location.
- Unlocks Stash from maintenance mode.
You will get an error message if you 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.
What is backed up
The Backup Client backs up all the following data:
- the database Stash is connected to (either the internal or external DB)
- managed Git repositories
- the Stash audit logs
- installed plugins and their 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
- the
plugins
directory (except for theinstalled-plugins
directory)
Backing up Stash using the client
Before you begin backing up Stash using the client, you should first ensure you are using a release of the Stash Backup Client that is compatible with your Stash instance.
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 commands:
cd <path/to/backup-config.properties file>
java -jar <path/to/stash-backup-client.jar>
Configuration options are kept in the backup-config.properties
file, an example of which is included with the client. This file is automatically read from the directory you were in when the stash-backup-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. 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. The location defined by |
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 -Dbackup.home=path/to/backup-home -jar stash-backup-client.jar
Cancelling the client backup
You can cancel the running client backup operation if necessary.
To cancel the backup:
- Copy the cancel token echoed by the client in the terminal (or the Command Prompt on Windows):
- Go to the Stash interface in your browser. Stash will display this screen:
- Click Cancel backup, and enter the cancel token:
- Click Cancel backup.
Restoring Stash to use the existing DB
This section applies if you are restoring Stash to fix a corrupted installation, but are able to use the existing DB that Stash was backed up from. This scenario assumes that Stash is to be restored to the same server from which Stash was originally backed up.
The Restore Client must be run on the machine that Stash should be restored to. To ensure restores do not accidentally delete existing data, the Restore Client will only restore into an empty home directory and an empty database.
The Restore Client will use the JDBC connection configuration contained in the backup you are restoring from.
Follow this process:
- Stop your Stash instance.
- Delete the content of the current home directory, so that it is empty.
- Drop the existing tables in your database so it is empty. The database still needs to exist with the same user/password, and it should have the configuration described in the 'Create the Stash database' section of the relevant page here:
Run the Restore Client using the following command (replacing '
path/to/stash/home
' and '/path/to/original/backup/file
' with your own values):java -Dstash.home="path/to/stash/home" -jar stash-restore-client.jar /path/to/original/backup/file
If you are restoring Stash to fix a corrupted installation, now follow Steps 4 to 6 of the Stash upgrade guide. Note that you should use the same version of Stash that was used to back up Stash.
Restoring Stash to use a newly created DB
This section applies if you intend to perform a restore into a newly created DB. This scenario assumes the restore is done to a server different from the one from which Stash was originally backed up.
The restore process is database agnostic, meaning the database you are restoring your backup to could be of a different configuration or type from the originally backed up database.
When restoring Stash, the Restore Client must be run on the machine that Stash should be restored to. To ensure restores do not accidentally delete existing data, the Restore Client will only restore into an empty home directory and an empty database.
Follow this process:
- Create a new empty home directory using the user account that will be used to run Stash.
- Create the database. It should have the configuration described in the ' Create the Stash database' section of the relevant page here:
- Run the Restore Client. See the following section.
- Follow Steps 4 to 6 of the Stash upgrade guide. Note that you should use the same version of Stash that was used to back it up.
Running the Restore Client from the command line
You can run the Restore Client from the command line. In this scenario, as you will have created a new database, you need to specify the JDBC connection parameters that should be used.
The Restore Client uses the JDBC connection configuration specified in the jdbc.driver
, jdbc.url
, jdbc.user
and jdbc.password
parameters used in the command to run the Restore Client (see below). Once the database backup is successfully restored, the client will write the specified parameters to the stash-config.properties
file in the newly restored Stash home directory, allowing the new instance to connect to the restored database once the steps outlined below are followed.
In this example, you can follow the restore into a newly created PostgreSQL database:
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
Alternatively, you can configure these parameters on the backup-config.properties
file – make sure the file exists in the current working directory. A sample file is shipped with the client. The properties are fully documented in the backup-config.properties
file and more details are described below:
| 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 log in 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 log in to the new database. |
jdbc.password | The username that Stash should use to log in to the new database. |
stash.home.restore.whitelist | Defines a comma-separated list of files and directories that may be present in the target home and shared directories when restoring a backup. Files other than those matching these entries will result in a failure. By default files .snapshot, lost+found, .DS_Store are white listed. |
Example use of JDBC properties
Example jdbc.driver
and jdbc.url
properties are shown below:
Database | jdbc.driver | jdbc.url |
---|---|---|
MySQL | com.mysql.jdbc.Driver | jdbc:mysql://HOSTNAME:PORT/DATABASE?autoReconnect=true&characterEncoding=utf8&useUnicode=true&sessionVariables=storage_engine%3DInnoDB |
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; |
Debug logging
Debug logging can be turned on by adding the following to the logback.xml
file in the working directory from where you're running the backup client. Create this file if it does not already exist.
<included><logger name="com.atlassian.stash" level="DEBUG"/></included>