Using the Bitbucket Server Backup Client
The backup client is not compatible with Bitbucket Data Center
The Bitbucket Server Backup Client is not compatible with clustered Bitbucket Data Center instances (even if you switch to a single node).
To back up a clustered Bitbucket Data Center instance, you need to use the Bitbucket Server DIY Backup instead.
This page describes using the Bitbucket Server Backup Client. We highly recommend that you establish a data recovery plan that is aligned with your company's policies.
To start using the Backup Client:
- Download the Bitbucket Server Backup Client.
- Unzip the client into a directory on the server where your Bitbucket Server instance resides.
Questions? Check out FAQ - Data recovery and backup.
On this page:
How it works
The Backup Client implements a common and universal way to backup a Bitbucket Server instance, and does the following:
- Locks access to the Bitbucket Server application, the repositories managed by Bitbucket Server and the Bitbucket Server 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 Bitbucket Server home directory and the Bitbucket Server 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 Bitbucket Server from maintenance mode.
You will get an error message if you try to access the Bitbucket Server web interface, or use the Bitbucket Server hosting services, when Bitbucket Server is in maintenance mode.
The client supports Windows and Linux platforms, and Bitbucket Server versions 4.0 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 Bitbucket Server Backup Client, in our testing and internal use we have seen downtimes for Bitbucket Server of 7–8 minutes with repositories totalling 6 GB in size. For comparison, using Bitbucket Server 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 Bitbucket Server is connected to (either the internal or external DB)
- managed Git repositories
- the Bitbucket Server audit logs
- installed plugins and their data
The backup does NOT include the following files and directories:
export/*log/*(except for the audit logs)shared/data/db*(HSQL data in the DB is backed up, but the files on disk are not)tmp- the
pluginsdirectory (except for theinstalled-pluginsdirectory)
Backing up Bitbucket Server using the client
Before you begin backing up Bitbucket Server using the client, you should first ensure you are using a release of the Bitbucket Server Backup Client that is compatible with your Bitbucket Server instance .
The Backup Client is a command line tool and not a plugin (no application UI) so it must be run externally from somewhere with access to the Bitbucket Server home directory. Usually, you will run the Backup Client directly on the Bitbucket Server server. Run the client with the following commands:
cd <path/to/backup-config.properties file>
java -jar <path/to/bitbucket-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 bitbucket-backup-client is run. The properties are fully documented in the backup-config.properties file, but include:
bitbucket.home
Defines the location of the home directory of the Bitbucket Server instance you wish to back up or restore to. REQUIRED
If omitted here it will be taken from the BITBUCKET_HOME environment variable or the Java system property of the same name if supplied to the Backup and Restore Client on the command line. As a required value, backup and restore will fail if it is not supplied through one of these mechanisms.
bitbucket.user
Defines the username of the Bitbucket Server 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.
bitbucket.password
Defines the password of the Bitbucket Server 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.
bitbucket.baseUrl
Defines base URL of the Bitbucket Server instance you wish to back up. REQUIRED
E.g.
http://localhost:7990/bitbucket
or http://bitbucketserver/.
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.
backup.home
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 backup subdirectory and logs will be stored in a logs subdirectory.
Note that on Windows, you must use two backslashes between paths. E.g. C:\\path\\to\\folder or instead use the forward slash e.g. C:/path/to/folder.
The location defined by backup.home must not be located in the directory defined by bitbucket.home. If that is the case, the Backup Client will fail.
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 -Dbitbucket.password="admin" -Dbitbucket.user="admin" -Dbitbucket.baseUrl="http://localhost:7990" -Dbitbucket.home=path/to/bitbucket/home -Dbackup.home=path/to/backup-home -jar bitbucket-backup-client.jarCanceling 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):
$ ./bitbucket.diy-backup.sh [http://localhost:7990/bitbucket] INFO: Prepared backup of DB bitbucket in /bitbucket-backup/bitbucket-db/ building file list ... done. sent 4.17M bytes received 484 bytes 2.78M bytes/sec total size is 121.12M speedup is 29.06 [http://localhost:7990/bitbucket] INFO: Prepared backup of /bitbucket-home to /bitbucket-backup/bitbucket-home/ [http://localhost:7990/bitbucket] INFO: locked with '7187ae1824ce1ede38a8e7de4bccf58d9a8e1a7a' [http://localhost:7990/bitbucket] INFO: backup started with '82c73f89e790b27fef3032e81c7071388ae4e371' [http://localhost:7990/bitbucket] INFO: Waiting for DRAINED state....... done [http://localhost:7990/bitbucket] INFO: db state 'DRAINED' [http://localhost:7990/bitbucket] INFO: scm state 'DRAINED'- Go to the Bitbucket Server interface in your browser. Bitbucket Server will display this screen:
- Click Cancel backup, and enter the cancel token:
- Click Cancel backup.
Restoring Bitbucket Server to use the existing DB
This section applies if you are restoring Bitbucket Server to fix a corrupted installation, but are able to use the existing DB that Bitbucket Server was backed up from. This scenario assumes that Bitbucket Server is to be restored to the same server from which Bitbucket Server was originally backed up.
The Restore Client must be run on the machine that Bitbucket Server 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 Bitbucket Server 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 Bitbucket Server database' section of the relevant page here:
Run the Restore Client using the following command (replacing '
path/to/bitbucket/home' and '/path/to/original/backup/file' with your own values):java -Dbitbucket.home="path/to/bitbucket/home" -jar bitbucket-restore-client.jar /path/to/original/backup/fileIf you are restoring Bitbucket Server to fix a corrupted installation, now follow Steps 4 to 6 of the Bitbucket Server upgrade guide. Note that you should use the same version of Bitbucket Server that was used to back up Bitbucket Server.
Restoring Bitbucket Server 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 Bitbucket Server 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 Bitbucket Server, the Restore Client must be run on the machine that Bitbucket Server 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 Bitbucket Server.
- Create the database. It should have the configuration described in the ' Create the Bitbucket Server database' section of the relevant page here:
- Run the Restore Client. See the following section for details.
- Install Bitbucket server on the new server by following the instructions on Running the Bitbucket Server installer. Point the installation to an empty directory and install it as a service in case you used to have that in your previous server.
- Make sure your new installation is up and running - refer to Starting and stopping Bitbucket Server. At this stage you should see Bitbucket server guiding you for a configuration from scratch (i.e. it will ask you for license details, admin user etc.) and that's expected.
- Stop the newly installed instance.
- Delete the contents from the newly installed
BITBUCKET_HOME. - Copy the contents of the restored
BITBUCKET_HOMEinto the newly installedBITBUCKET_HOME. - Start the newly installed Bitbucket server.
- At this stage, the following will happen:
- If you installed a binary at the same release as it was on your previous server, everything will be like before and you will need to perform an upgrade in a separate step. This is the recommended approach.
- If you installed a binary at a release above the one it was installed on your previous server, an upgrade will be performed at this stage.
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 bitbucket-config.properties file in the newly restored Bitbucket Server home directory, allowing the new instance to connect to the restored database once the steps outlined below are followed.
Before performing a restore to a MySQL database, note that the JDBC driver for MySQL is not bundled with it (due to licensing restrictions). You need to download and install the driver yourself.
Download the MySQL Connector/J JDBC driver from the download site.
Expand the downloaded zip/tar.gz file.
Copy the mysql-connector-java-5.1.XX-bin.jar file from the extracted directory to your
<path/to/backup/client>/jdbcdirectory.
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=bitbucketuser -Djdbc.password=password -Dbitbucket.home="path/to/bitbucket/home" -jar /path/to/bitbucket-restore-client.jar /path/to/original/backup/fileAlternatively, 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:
bitbucket.home
The full path to a directory that the Restore Client will populate with the Bitbucket Server 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.override is set to true , the Restore Client will restore into the database specified by the jdbc properties in the table below. The database must be empty.
jdbc.driver
The driver class that Bitbucket Server 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 Bitbucket Server should use to log in to the new database.
jdbc.password
The username that Bitbucket Server should use to log in to the new database.
bitbucket.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.bitbucket" level="DEBUG"/></included>