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 clustered Stash Data Center instances (even if you switch back to a single node). To back up a Stash Data Center instance, you must 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.

On this page:

関連ページ

動作の仕組み

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'.
すべての Git およびデータベース操作が完了したことを確認します。
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.
バックアップファイルをローカルファイルシステムの指定された場所に、1 つの tar ファイルして保管します。
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.

バックアップ対象

Backup Client は次のすべてのデータをバックアップします。

the database Stash is connected to (either the internal or external DB)
管理された Git リポジトリ
the Stash audit logs
インストール済みのプラグインとそれらのデータ

バックアップには次のファイルおよびディレクトリは含まれません。

export/*
log/* (監査ログを除く)
data/db* (DB 内の HSQL データはバックアップされますが、ディスクのファイルはバックアップされません)
tmp
plugins ディレクトリ (installed-plugins ディレクトリを除く)

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:

stash.home

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 STASH_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.

stash.user

Defines the username of the Stash user with administrative privileges you wish to perform the backup. REQUIRED

ここで省略した場合、同じ名前の Java システムプロパティから取得されます (コマンドラインで Backup Client に指定していた場合)。これは必須の値であるため、これらのメカニズムのいずれかで指定されていない場合は、バックアップが失敗します。

stash.password

Defines the password of the Stash user with administrative privileges you wish to perform the backup. REQUIRED

ここで省略した場合、同じ名前の Java システムプロパティから取得されます (コマンドラインで Backup Client に指定していた場合)。これは必須の値であるため、これらのメカニズムのいずれかで指定されていない場合は、バックアップが失敗します。

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.

backup.home

Backup Client がバックアップアーカイブなどの自身のファイルを保存する場所を定義します。

指定しない場合、これらのファイルは Backup Client の作業ディレクトリの配下に保存されます。バックアップファイルは backup サブディレクトリに、ログは logs サブディレクトリに保存されます。

Windows の場合、パスの間に 2 つのバックスラッシュを使用する必要がある点にご注意ください。例: C:\\path\\to\\folder または代わりにフォワードスラッシュを使用してください。例: C:/path/to/folder

The location defined by backup.home must not be located in the directory defined by stash.home. If that is the case, the Backup Client will fail.

あるいは、次のプロパティをコマンドラインで指定できます。これらは "-D" プレフィックスを持ち、"-jar" パラメーターの前に配置する必要があります。次に例を示します。

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

必要に応じて、実行中のクライアントバックアップ操作をキャンセルできます。

バックアップのキャンセル方法

ターミナル (または Windows のコマンドプロンプト) でクライアントによって返されるキャンセルトークンをコピーします。
Go to the Stash interface in your browser. Stash will display this screen:
Click Cancel backup, and enter the cancel token:
[バックアップを取消] をクリックします。

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.

Restore Client は復元元のバックアップに含まれる JDBC 接続構成を使用します。

次のプロセスに従います。

Stop your Stash instance.
現在のホームディレクトリのコンテンツを削除し、空にします。
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:
次のコマンドを使用して Restore Client を実行します (「path/to/stash/home」と「/path/to/original/backup/file」の値を自身のものに置き換えてください)。
```
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.

復元プロセスはデータベースを問いません。つまり、バックアップの復元先のデータベースは、元のバックアップされたデータベースと異なる構成やタイプでもかまいません。

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.

次のプロセスに従います。

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.

コマンドラインから Restore Client を実行する

Restore Client をコマンドラインから実行することもできます。このシナリオでは、新しいデータベースを作成済みであるため、使用すべき JDBC 接続を指定する必要があります。

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.

この例では、新しく作成された PostgreSQL への復元を行っています。

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

あるいは、backup-config.properties ファイルでこれらのパラメータを構成することもできます。ファイルが現在のワーキングディレクトリに存在することを確認してください。サンプルファイルはクライアントに同梱されます。プロパティは、backup-config.properties ファイルに完全に文書化されており、詳細は以下で説明されています。

`stash.home`	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.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 Stash should use to log in to the new database. See examples below.
`jdbc.url`	新しいデータベースの接続の詳細です。JDBC URL の形式を持ちます。以降の例をご確認ください。
`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`	バックアップの復元時にターゲットのホームと共有ディレクトリに存在する可能性があるファイルとディレクトリの、コンマ区切りの一覧を定義します。これらのエントリに一致しないファイルがあった場合、処理に失敗します。 By default files .snapshot, lost+found, .DS_Store are white listed.

JDBC プロパティの使用例

jdbc.driver および jdbc.url プロパティの例を以下に示します。

データベース	`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;

デバッグロギング

バックアップクライアントを実行しているワーキングディレクトリで logback.xml ファイルに次の情報を追加することで、デバッグロギングを有効化できます。このファイルが存在しない場合は作成します。

logback.xml

<included><logger name="com.atlassian.stash" level="DEBUG"/></included>

ページツリー