BorgBackup簡易解説(ver1.1.7)

# はじめに
圧縮率が高く、高速にバックアップが行えるツール「borg」について、公式のドキュメントを翻訳しながら抜粋してまとめます。
Borg: <https://borgbackup.readthedocs.io/en/1.1.7/>
※この翻訳はversion1.1.7(2018/08/11)のものになります。
（[前回（1.1.5）](https://qiita.com/sax_/items/64df7024114641551331)の投稿が個人的に見にくかったので書き直しました。）

間違いなどありましたら編集リクエスト、コメントをお願いします。
（アドベントカレンダーに参加しようと思ったけど、マッチしそうなカレンダーがなかったので通常投稿します。。。）

# Borgって？

* リポジトリ管理方式の重複除外バックアップツール。(差分をブロック単位で検知して、変更ブロックのみ保存する方法)
* 圧縮形式を選択できる。（lz4,zstd,zkib,lzma）
* パスワードなどをかけてセキュリティ対策も行える。（SHA-256）
* SSHでリモートにデータを設置できる。
* データはバイナリ形式で保存される。
* 利用可能なOS
  * パッケージマネージャー版
     * Arch Linux ( `pacman -S borg` )
     * Debian ( `apt install borgbackup` )
     * Gentoo ( `emerge borgbackup` )
     * GNU Guix ( `guix package --install borg` )
     * Fedora / RHEL ( `dnf install borgbackup` )
     * FreeBSD ( `cd /usr/ports/archivers/py-borgbackup && make install clean` )
     * Mac OS ( `brew cask install borgbackup` )
     * Mageia ( `urpmi borgbackup` )
     * NetBSD ( `pkg_add py-borgbackup` )
     * OpenBSD ( `pkg_add borgbackup` )
     * OpenIndiana ( `pkg install borg` )
     * openSUSE ( `zypper in borgbackup` )
     * Raspbian ( `apt install borgbackup` )
     * Ubuntu ( `apt install borgbackup` )
  * バイナリ版
     * Linux (glibc >= 2.13)
     * Mac OS X (10.10以上)
     * FreeBSD (10.2以上)
  * ソースからインストール
     * [ドキュメント](https://borgbackup.readthedocs.io/en/1.1.7/installation.html#source-install)を参照
     * BSD (3-Clause) ライセンス

参考：<https://borgbackup.readthedocs.io/en/1.1.7/index.html#what-is-borgbackup>

<details><summary>インストール方法</summary><div>

<https://borgbackup.readthedocs.io/en/1.1.7/installation.html>
OSごとにインストール方法が異なります。

一番簡単なのは、「Standalone Binary」の項目にあるバイナリ版です。

必須条件
Linux： glibc >= 2.13
Mac OS X： 10.10
FreeBSD： 10.2

```console
cd /usr/local/bin
wget https://github.com/borgbackup/borg/releases/download/1.1.7/borg-linux64
cp borg-linux64 /usr/local/bin/borg
chown root:root /usr/local/bin/borg
chmod 755 /usr/local/bin/borg
```

可能であれば、[jq](https://stedolan.github.io/jq/)（JSONを扱えるようになるアプリケーション）をインストールすることをオススメします。（ログの表示を好きなように設定できるため）

</div></details>

<details><summary>用語</summary><div>

基本的な用語などは、下記の通りです。

| 名称 | 意味 |
|:--|:--|
| 共通オプション | ほぼすべてのコマンドで使用できるオプションです。 |
| 環境変数 | BORGから始まる環境変数群です。対話に対する自動回答や、コマンド実行時の設定を省く機能などがあります。 |
| レポジトリ | バックアップ対象となるディレクトリです。初期化を実行したユーザのホームディレクトリに、.cacheや.configディレクトリが生成されます。 |
| アーカイブ | バックアップを取る時に指定する保存名です。復元する場合などに使用します。 |

</div></details>

<details><summary>ディレクトリについて</summary><div>

borgでは、バックアップ対象や保存先に下記を指定できます。

* ローカル
  * 絶対パス  
    /path/to/repo
  * 相対パス（実行ユーザのホームディレクトリからの相対）  
    ~/path/to/repo
  * ユーザのホームディレクトリ  
    ~user/path/to/repo

* リモート
  * ssh://user@host:port/./path/to/repo （相対パス）

</div></details>

<details><summary>ステータスコード</summary><div>

| コード | 意味 |
|:--|:--|
| 0       | 成功 |
| 1       | 警告 |
| 2       | エラー |
| 128 + N | KILLされたシグナル番号（例えば137 = 128 + kill(9)） |

</div></details>

<details><summary>共通オプション（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| --critical            | ログレベルCRITICALで実行する。 |
| --error               | ログレベルERRORで実行する。 |
| --warning             | ログレベルWARNINGで実行する。（デフォルト） |
| --info, -v, --verbose | ログレベルINFOで実行する。 |
| --debug               | ログレベルDEBUGで実行する。 |
| -p, --progress        | 進捗状況を表示する。 |
| --log-json            | ログをJSON形式で表示する。 |

</div></details>

<details><summary>環境変数一覧（抜粋）</summary><div>

すべてを試しているわけではないので、間違っていたら編集リクエストやコメントをお願いします。

| 設定値 | 概要 |
|:--|:--|
| BORG_REPO                                       | デフォルトのレポジトリを指定します。指定されている場合はレポジトリ指定を省略できます。 |
| BORG_PASSPHRASE                                 | 設定すると、パスフレーズを自動回答します。 |
| BORG_PASSCOMMAND                                | 設定すると、パスフレーズを聞かれた時にコマンドを実行します。BORG_PASSPHRASEを設定している場合はそちらが優先されます。 |
| TMPDIR                                          | 一時ディレクトリの場所を変更できます。 |
| BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes  | 暗号化をnoneにしている場合のエラーをスキップできます。 |

</div></details>

# コマンド一覧
リンクがあるものは、最低限必要になるコマンドです。
これらの中から、抜粋して解説していきます。

| コマンド | 用途 |
|:--|:--|
| [borg init](#borg-init)       | 初期化 |
| [borg create](#borg-create)   | アーカイブ作成 |
| [borg extract](#borg-extract) | 内容抽出 |
| [borg list](#borg-list)       | 内容の一覧表示 |
| [borg diff](#borg-diff)       | アーカイブ間の比較 |
| [borg delete](#borg-delete)   | アーカイブの削除（単一） |
| [borg prune](#borg-prune)     | アーカイブの削除（複数） |
| [borg info](#borg-info)       | アーカイブ情報表示 |
| borg check                    | 整合性の検証 |
| borg rename                   | アーカイブ名変更 |
| borg mount                    | ファイルシステムのマウント |
| borg umount                   | ファイルシステムのマウント解除 |
| borg key                      | アーカイブの鍵設定 |
| borg upgrade                  | アーカイブ情報の更新 |
| borg recreate                 | アーカイブの再構築（実験中） |
| borg export-tar               | アーカイブからtarを作成 |
| borg serve                    | ?? |
| borg config                   | アーカイブの設定変更 |
| borg with-lock                | アーカイブロック |
| borg break-lock               | アーカイブロック解除 |
| borg benchmark                | ベンチマーク（作成/読取/更新/削除） |

## borg init
指定したディレクトリをBorgのレポジトリに初期化します。
下記のように実行します。

```console
borg [common options] init [options] [REPOSITORY]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| -e MODE. --encryption MODE | 暗号化モードの選択 |

</div></details>

暗号化を無効にすると、有効に切り替えることができません。
暗号化には、パスフレーズを設定する方法、キーファイルを設定する方法、またはその両方の3種類があります。

## borg create
バックアップを行います。レポジトリを指定する為、initを行っているディレクトリを指定する必要があります。
下記のように実行します。

```console
borg [common options] create [options] ARCHIVE [PATH...]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| -n, --dry-run        | テスト実行する。（保存しない） |
| -s, --stats          | 作成後に情報を表示する。 |
| --list               | 対象ディレクトリ/ファイルをすべて表示する。 |
| --filter STATUSCHARS | 指定したステータスの対象のみ表示する。使用する際は--listオプションを追加すること。（下記参照） |
| --json               | 作成後に情報をJSON形式で表示する。 |

| 除外オプション | 概要 |
|:--|:--|
| -e PATTERN, --exclude PATTERN | PATTERNに一致するパスを除外する。 |

| アーカイブオプション | 概要 |
|:--|:--|
| --comment COMMENT                         | COMMENTを追加する。 |
| --timestamp TIMESTAMP                     | アーカイブの作成日時を手動で指定する。 |
| -c SECONDS, --checkpoint-interval SECONDS | チェックポイントをSECONDS秒ごとに書き込みます。（デフォルトは1800） |
| -c COMPRESSION, --compression COMPRESSION | 圧縮アルゴリズムを選択します。（borg help compressionを見て選んでください。） |

</div></details>

<details><summary>filterオプションについて（抜粋）</summary><div>

| CHAR | 概要 |
|:--|:--|
| A | 追加されたファイル |
| M | 変更されたファイル |
| U | 変更なし |
| E | アクセスエラー |

</div></details>

## borg extract
バックアップから復元を行います。復元の際、ディレクトリ/ファイルを指定、除外設定することもできます。
実行時のディレクトリに復元されるため、`mktemp -d`などで一時ディレクトリを作成し、移動してから実行したほうがいい。
下記のように実行します。

```console
borg [common options] extract [options] ARCHIVE [PATH...]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| --list        | 対象ディレクトリ/ファイルをすべて表示する。 |
| -n, --dry-run | テスト実行する。（復元しない） |

| 除外オプション | 概要 |
|:--|:--|
| -e PATTERN, --exclude PATTERN | PATTERNに一致するパスを除外する。 |

</div></details>

復元は少し癖があります。
例えば、`/backup/root`レポジトリの`test01`というアーカイブに含まれる`/root/test/`ディレクトリを復元したい場合、下記のように実行します。

```console
mktemp -p
# /tmp/tmp.xxxxxxxxxxと出力される
cd /tmp/tmp.xxxxxxxxxx
mkdir -p root
borg extract /backup/root::test01 root/test/
# /tmp/tmp.xxxxxxxxxx/root/test/に復元される
```

## borg list
内容を表示します。レポジトリを指定した場合と、アーカイブ名まで指定した場合とで表示が変わります。

* レポジトリを指定  
  保存されているアーカイブの一覧を表示
* アーカイブ名を指定  
  アーカイブに格納されているディレクトリ/ファイルの一覧を表示

下記のように実行します。

```console
borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| --short                               | ディレクトリ/ファイル名のみ出力する。 |
| --format FORMAT, --list-format FORMAT | ファイルの出力形式を指定する。（デフォルト： "{mode} {user：6} {group：6} {size：8d} {mtime} {path} {extra} {NL}"） |
| --json                                | JSON形式で出力する。（レポジトリ内容の一覧表示時） |
| --json-lines                          | JSON形式で出力する。（アーカイブ内容の一覧表示時） |

| 除外オプション | 概要 |
|:--|:--|
| -e PATTERN, --exclude PATTERN | PATTERNに一致するパスを除外する。 |

※formatオプションについては、内容が多すぎるため省略します。

</div></details>

## borg diff
アーカイブ間の差分を表示します。
下記のように実行します。

```console
borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
# PATHはアーカイブ内の比較するパスを指定
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| --sort | 出力をファイルパスでソートする。 |

| 除外オプション | 概要 |
|:--|:--|
| -e PATTERN, --exclude PATTERN | PATTERNに一致するパスを除外する。 |

</div></details>

## borg delete
アーカイブ名を指定して、アーカイブを削除します。
複数選択された場合は、回答を求められます。
下記のように実行します。

```console
# アーカイブ削除
borg [common options] delete [options] REPO::ARCHIVE
# レポジトリ削除
borg [common options] delete [options] [REPOSITORY]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| -n, --dry-run | テスト実行する。（削除しない） |
| -s, --stats   | 削除後に削除されたアーカイブの情報を表示する。 |
| --cache-only  | 指定したレポジトリのローカルキャッシュのみ削除します。 |
| --save-space  | 時間がかかりますが、スペースをより多く確保できます。 |

</div></details>

## borg prune
日時を指定して、アーカイブを削除します。
下記のように実行します。

```console
borg [common options] prune [options] [REPOSITORY]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| -n, --dry-run                | テスト実行する。（削除しない） |
| -s, --stats                  | 削除後に削除されたアーカイブの情報を表示する。 |
| --list                       | 対象ディレクトリ/ファイルをすべて表示する。 |
| --keep-within INTERVAL       | INTERVALで保持期間を指定します。（H,d,w,m,yを付ける） |
| --keep-last, --keep-secondly | 最後、2番目までのアーカイブのみ保持します。 |
| --keep-minutely              | 分単位で保持するアーカイブを指定します。 |
| -H, --keep-hourly            | 時単位で保持するアーカイブを指定します。 |
| -d, --keep-daily             | 日単位で保持するアーカイブを指定します。 |
| -w, --keep-weekly            | 週単位で保持するアーカイブを指定します。 |
| -m, --keep-monthly           | 月単位で保持するアーカイブを指定します。 |
| -y, --keep-yearly            | 年単位で保持するアーカイブを指定します。 |
| --save-space                 | 時間がかかりますが、スペースをより多く確保できます。 |

</div></details>

## borg info
レポジトリの情報を表示します。レポジトリを指定した場合と、アーカイブ名まで指定した場合とで表示が変わります。

* レポジトリを指定

| 名称 | 意味 |
|:--|:--|
| Repository ID | レポジトリのID |
| Location      | レポジトリの設置場所（移動しないこと） |
| Encrypted     | 暗号化種類 |
| Cache         | キャッシュが置かれている場所 |
| Security dir  | セキュリティ設定が置かれている場所 |

* アーカイブ名を指定

| 名称 | 意味 |
|:--|:--|
| Archive name        | アーカイブ名 |
| Archive fingerprint | アーカイブのID（フィンガープリント） |
| Comment             | コメント |
| Hostname            | 保存ホスト名 |
| Username            | 保存ユーザ名 |
| Time (start)        | 処理開始時間 |
| Time (end)          | 処理終了時間 |
| Duration            | 所要時間 |
| Number of files     | 対象ファイル数 |
| Command line        | 実行コマンド |
| Utilization of maximum supported archive size | アーカイブ全体で占める割合 |

下記のように実行します。

```console
borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
```

<details><summary>options（抜粋）</summary><div>

| オプション | 概要 |
|:--|:--|
| --json | JSON形式で出力する。 |

</div></details>

# 最後に
この記事を書いている時点でGitHubでは743コミットもありました。
もしかしたら今年中に1.2.0が来るかもしれません。
設定項目などに大幅なアップデートがない場合は、早いうちに更新するかも。

BorgBackup、便利なのに日本語の解説が少なくて悲しいです。。。
もっとBorgBackupが盛り上がってくれたら嬉しいな。

# 著作表示
>Copyright (C) 2015-2018 The Borg Collective (see AUTHORS file)
Copyright (C) 2010-2014 Jonas Borgström \<jonas&#64;borgstrom.se>
All rights reserved.