はじめに

圧縮に特化していて使いやすい差分バックアップツール「borg」について、公式ドキュメントを翻訳してみました。
実験的なもの、あまり使用しないと思われる項目については省いてあります。
リンク:Borg - https://borgbackup.readthedocs.io/
※この翻訳はversion1.1.5(2018/04/01)のものになります。

Borgって?

  • リポジトリ管理方式の差分バックアップツール。
  • 圧縮形式を選択でき、パスワードなどをかけてセキュリティ対策も行える。
  • リモートに対応している(SSH)
  • データはバイナリ形式で保存される。

参考:ArchLinux wiki - バックアッププログラム

インストール

先に下記のリンクから最新バージョンを確認してください。
Releases - https://github.com/borgbackup/borg/releases

例:Linux(CentOS) + Borg version1.1.5の場合

cd /usr/local/bin
wget https://github.com/borgbackup/borg/releases/download/1.1.5/borg-linux64
mv borg-linux64 borg
chmod 755 borg

コマンド一覧

最低限必要になるコマンドは、
init(初期化)
create(バックアップ)
extract(復元)
list(履歴表示)
diff(差分比較)
delete(手動削除)
prune(期間指定削除)
の7点です。

共通オプション

引数 内容
-h, --help ヘルプメッセージを表示する
--critical ログレベルCRITICALで実行する
--error ログレベルERRORで実行する
--warning ログレベルWARNINGで実行する(デフォルト)
--info, -v, --verbose ログレベルINFOで実行する
--debug デバッグ出力を有効にする、ログレベルDEBUGで実行する
-p, --progress 進捗情報を表示する
--log-json 書式付きテキストの代わりにJSONオブジェクトを出力します。
--lock-wait SECONDS リポジトリ/キャッシュロックの最大待機時間を、SECONDSで指定します(デフォルト:1)。
--show-version borgのバージョンを表示する
--show-rc リターンコードを表示する(rc)
--umask M umaskをMに設定する(ローカルとリモート、デフォルト:0077)
--remote-path PATH リモートでborgを実行する際のPATH(デフォルト: "borg")
--remote-ratelimit RATE リモートネットワークのアップロード速度制限をk/s単位で設定します(デフォルト:0=無制限)
--consider-part-files 通常のファイルのようにパートファイルを扱う(例:リストアップ/抽出)
--debug-profile FILE Borg形式の実行プロファイルをFILEに書き込みます。ローカルで使用する場合は、FILEの後に ".pyprof"を付けてPython互換のファイルを生成することができます。

borg init(ディレクトリの初期化)

borg [共通オプション] init [オプション] [リポジトリ]
例:
borg init -e repokey /path/to/backupdir
解説:
borgバックアップを行うためのディレクトリを作成します。
オプション「-eまたは--enctyption」は必須です。SHA-256(repokey)、BLAKE2b(repokey-blake2)、無し(none)から選択できます。
設定したキーファイルは{HOME}/.config/borg/keysに保存されます。

引数 内容
-e MODE, --encryption MODE 暗号化キーモードを選択する(必須)
--append-only 追加専用のリポジトリを作成する

borg create(バックアップの実行)

borg [共通オプション] create [オプション] [REPO_ARCHIVE] [パス...]
例:
borg create /path/to/backupdir::bk01 /dir
解説:
指定されたパスを再帰的に検索し、検出された全てのファイルをバックアップしアーカイブを作成します。

パスとして-を指定すると標準入力からデータを読み込み、そのデータから作成したアーカイブにはstdinというファイル名が付きます。

アーカイブ名は一意である必要があり、.checkpointや.checkpoint.N(Nは数字)で終わる名前は使用できません。
アーカイブ名には{now}、{utcnow}、{fqdn}、{hostname}、{user}などのプレースホルダを使用できます。

通常、ファイル変更の検出にはファイル変更の検出の信頼性を向上させるためにinode情報を参照します。
しかしこれは安定したinode番号を提供しないsshfsや同様のネットワークファイルシステム上にあるファイルには問題があります。そのようなファイルは常に変更されたとみなされます。この場合、--ignore-inodeによってinodeを無視したモードにしてパフォーマンスを向上させることができますが、変更検出の信頼せは低下する可能性があります。(他のモードについては下記モードの比較を参照)

マウント、除外設定、アイテムフラグについては公式ドキュメントを参照ください。

モードの比較:
デフォルトはinode情報で検証を行いますが、それができない場合、ctimeやmtimeで変更検出が行えます。
ctimeの場合、ファイルへの変更(メタデータ、コンテンツ)はユーザ空間から設定できないため、安全といえます。しかし、メタデータのみの変更はctimeを変更するため、コンテンツの変更が無くても不必要なチャンク/ハッシュが存在する可能性があります。また、いくつかのファイルシステムではctimeをサポートしていません。
mtimeの場合、ファイルの内容が変更された場合にのみ更新されます。しかし、mtimeはユーザ空間から任意に設定できます。例えばmtimeをコンテンツの変更が起こる前と同じ値に戻すことができてしまいます。

引数 内容
-n, --dry-run (テストモード)バックアップアーカイブを作成しない
-s, --stats 作成されたアーカイブの統計を表示する
--list 作成されたアーカイブの詳細を表示する
--filter STATUSCHARS 指定されたステータス文字を持つ項目のみを表示する
--json JSONで表示する
--no-cache-sync [試験運用]キャッシュファイルを同期しない(キャッシュファイルを使用しない)
--no-files-cache 変更されていないファイルを検出するために使用するファイルメタデータをロード/更新しない
--stdin-name NAME stdinデータのアーカイブ名を指定する(デフォルト:stdin)

除外オプション

引数 内容
-e PATTERN, --exclude PATTERN PATTERNで一致するパスを除外
--exclude-from EXCLUDEFILE EXCLUDEFILEにに一致するパスを除外
--pattern PATTERN [試験運用]パターンに一致するパスを含める/除外する
--patterns-from PATTERNFILE [試験運用]PATTERNFILEに一致するパスを含める/除外する

ファイルシステムオプション

引数 内容
-x, --one-file-system 同じファイルシステムに留まり、他のファイルシステムのマウントポイントを保存しない
--numeric-owner ユーザ、グループのみを格納する
--noatime アーカイブにアクセス日時を保存しない
--noctime アーカイブに更新日時を保存しない
--nobirthtime アーカイブに作成日時を保存しない
--nobsdflags bsdflags(例:NODUMP、IMMUTABLE)を読み込んでアーカイブに保存しない
--ignore-inode 変更されていないファイルを検出するために使用されるファイルメタデータキャッシュ内のinode値を無視する
--files-cache MODE MODEでファイルキャッシュを操作する(デフォルト:ctime, size, inode)
--read-special blockとcharのデバイスファイルとFIFOを通常のファイルであるかのように読み込みます。また、これらの種類のファイルが指すシンボリックリンクも読み込みます。

アーカイブオプション

引数 内容
--comment COMMENT アーカイブにコメントを追加する
--timestamp TIMESTAMP アーカイブ作成日時を手動で設定します
-c SECONDS, --checkpoint-interval SECONDS SECONDS毎にチェックポイントを書き込みます(デフォルト:1800)
--chunker-params PARAMS チャンクパラメータ(CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE)を指定します。(デフォルト:19,23,21,4095)
-C COMPRESSION, --compression COMPRESSION 圧縮アルゴリズムを選択します。(詳細はborg help compression)

borg extract(復元)

borg [共通オプション] extract [オプション] [REPO_ARCHIVE] [パス...]
例:
borg extract /path/to/backupdir::bk01 dir/example.txt
解説:
ファイル/ディレクトリの復元を実行します。パスには復元したいディレクトリやファイル名などを記入してください。
注意:
パスは環境変数BORG_BASE_DIRで指定されたディレクトリからのパスを記入してください。
復元データは現在のディレクトリから、指定したディレクトリに対してそのまま書き込みが行われるため、復元処理実行前にホームディレクトリなどに移動して行ってください。
例:ホームディレクトリが/home/hogeのhogeユーザが/home/hoge/workディレクトリを保存し、復元したい場合

# 保存
borg create /path/to/backupdir::bk01 /home/hoge/work
# 復元
cd /home/hoge
borg extract /path/to/backupdir::bk01 work
引数 内容
--list ファイル/ディレクトリの詳細を表示する
-n, --dry-run (テストモード)実際にファイル/ディレクトリを変更しない
--numeric-owner ユーザ、グループを考慮する
--nobsdflags bsdflagsを抽出/設定しない(例:NODUMP, IMMUTABLE)
--stdout 抽出された全データをstdoutに書き込む
--sparse

除外オプション

引数 内容
-e PATTERN, --exclude PATTERN PATTERNで一致するパスを除外
--exclude-from EXCLUDEFILE EXCLUDEFILEにに一致するパスを除外
--pattern PATTERN [試験運用]パターンに一致するパスを含める/除外する
--patterns-from PATTERNFILE [試験運用]PATTERNFILEに一致するパスを含める/除外する

borg check(データの検証)

borg [共通のオプション] check [オプション] [REPOSITORY_OR_ARCHIVE]
例:
borg check /path/to/backupdir
解説:
リポジトリと対応するアーカイブのデータを検証します。--repairを追加することで修復を実行します。
検出処理の流れや、修復処理の手順などはここでは解説しません。

引数 内容
--repository-only リポジトリのチェックのみ実行
--archives-only アーカイブのチェックのみ実行
--verify-data 暗号化アーカイブのデータの完全性を検証する
--repair 検出した矛盾を修復
--save-space 低速だが、スペースを節約して動作する

アーカイブフィルタ

引数 内容
-P PREFIX, --prefix PREFIX PREFIXで始まるアーカイブ名を指定
-a GLOB, --glob-archives GLOB GLOBと一致するアーカイブ名を指定。sh規則が適用できます。borg help patternを参照。
--sort-by KEYS KEYSでソートします。timestamp,name,idを指定可。デフォルト:timestamp
--first N 抽出した最初のN個のアーカイブを指定
--last N 抽出した最後のN個のアーカイブを指定

borg rename(アーカイブ名の変更)

borg [共通のオプション] rename [オプション] [REPO_ARCHIVE] [NEWNAME]
例:
borg rename /path/to/backupdir::bk01 backup01
解説:
作成したアーカイブ名を変更します。変更後はアーカイブIDが変わります。

borg list(リポジトリ/アーカイブの内容表示)

borg [共通オプション] リスト[オプション] [リポジトリまたはアーカイブ名] [パス...]
例:
borg list /path/to/bachupdir
解説:
リポジトリの表示やアーカイブ内容の表示ができます。データの復元(extract)を実行する際はアーカイブ内容の表示で出力されるファイル/ディレクトリパスで指定する必要があります。
※復元の際は保存先に注意!詳細はextractの解説をご覧ください。

引数 内容
--short ファイル/ディレクトリ名のみ表示
--format FORMAT、 --list-format FORMAT ファイル形式を指定 デフォルト:{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}
--json JSON形式で表示(リポジトリの一覧表示の場合)
--json-lines JSON形式で表示(アーカイブの内容表示の場合)

アーカイブフィルタ

引数 内容
-P PREFIX, --prefix PREFIX PREFIXで始まるアーカイブ名を指定
-a GLOB, --glob-archives GLOB GLOBと一致するアーカイブ名を指定。sh規則が適用できます。borg help patternを参照。
--sort-by KEYS KEYSでソートします。timestamp,name,idを指定可。デフォルト:timestamp
--first N 抽出した最初のN個のアーカイブを指定
--last N 抽出した最後のN個のアーカイブを指定

除外オプション

引数 内容
-e PATTERN, --exclude PATTERN PATTERNで一致するパスを除外
--exclude-from EXCLUDEFILE EXCLUDEFILEにに一致するパスを除外
--pattern PATTERN [試験運用]パターンに一致するパスを含める/除外する
--patterns-from PATTERNFILE [試験運用]PATTERNFILEに一致するパスを含める/除外する

borg diff(アーカイブの差分比較)

borg [共通オプション] diff [オプション] [REPO_ARCHIVE1] [ARCHIVE2] [パス...]
例:
borg diff /path/to/backupdir::bk01 bk02
解説:
2つのアーカイブのファイル内容、権限情報を比較(diff)します。
1.1以降のバージョンでは、同じチャンクパラメータで作成されているかどうかを自動的に検出します。

引数 内容
--numeric-owner ユーザ、グループを考慮する
--same-chunker-params チャンクパラメータのオーバーライドをチェックする
--sort 出力をファイルパスでソートする

除外オプション

引数 内容
-e PATTERN, --exclude PATTERN PATTERNで一致するパスを除外
--exclude-from EXCLUDEFILE EXCLUDEFILEにに一致するパスを除外
--pattern PATTERN [試験運用]パターンに一致するパスを含める/除外する
--patterns-from PATTERNFILE [試験運用]PATTERNFILEに一致するパスを含める/除外する

borg delete(アーカイブの手動削除)

borg [共通オプション] delete [オプション] [ターゲット] [アーカイブ...]
例:
borg delete /path/to/backupdir::bk01
解説:
リポジトリからアーカイブを削除します。完全な削除の場合(--cache-onlyを使用しない)、ローカルキャッシュも削除されます。

引数 内容
-s, --stats 削除したアーカイブの内容を表示する
--cache-only 指定したリポジトリのローカルキャッシュのみ削除する
--force 破損したアーカイブを強制削除し、使用できなくする
--save-space 低速だが、スペースを節約して動作する

アーカイブフィルタ

引数 内容
-P PREFIX, --prefix PREFIX PREFIXで始まるアーカイブ名を指定
-a GLOB, --glob-archives GLOB GLOBと一致するアーカイブ名を指定。sh規則が適用できます。borg help patternを参照。
--sort-by KEYS KEYSでソートします。timestamp,name,idを指定可。デフォルト:timestamp
--first N 抽出した最初のN個のアーカイブを指定
--last N 抽出した最後のN個のアーカイブを指定

borg prune(アーカイブの複数削除)

borg [共通オプション] prune [オプション] [リポジトリ]
例:過去10日間の全てのバックアップ、週末の4つのアーカイブ、毎月のアーカイブを保存する
borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/backupdir
例:1週間以内のアーカイブのみ残す
borg prune -v --list --keep-weekly 1 /path/to/backupdir
解説:
※アーカイブフィルタについては公式ドキュメントを参照ください。
borg deleteと違い、保有期間を指定して該当しないアーカイブを全て削除します。
--keep-XXXは複数設定することが可能です。
--keep-withinについては、を引数に設定します。利用できる文字はH,d,w,m,yです。文字を記入しない場合は--keep-secondlyとして捉えられるため、注意が必要です。

引数 内容
-n, --dry-run (テストモード)リポジトリを変更しない
--force 破損したアーカイブを強制削除する
-s, --stats 削除するアーカイブの統計を表示
--list 保存/削除するアーカイブの詳細を表示
--keep-within INTERVAL INTERVALの時間全てのアーカイブを保持する
--keep-last, --keep-secondly アーカイブの保持期間を指定(秒単位)
--keep-minutely アーカイブの保持期間を指定(分単位)
-H, --keep-hourly アーカイブの保持期間を指定(時単位)
-d, --keep-daily アーカイブの保持期間を指定(日単位)
-w, --keep-weekly アーカイブの保持期間を指定(週単位)
-m, --keep-monthly アーカイブの保持期間を指定(月単位)
-y, --keep-yearly アーカイブの保持期間を指定(年単位)
--save-space 低速だが、スペースを節約して動作する

アーカイブフィルタ

引数 内容
-P PREFIX, --prefix PREFIX PREFIXで始まるアーカイブ名を指定
-a GLOB, --glob-archives GLOB GLOBと一致するアーカイブ名を指定。sh規則が適用できます。borg help patternを参照。

borg info(リポジトリの情報表示)

borg [共通オプション] info [オプション] [リポジトリまたはアーカイブ名]
例:
borg info /path/to/backupdir --last 1
解説:
リポジトリの容量などの情報を表示します。::アーカイブ名で指定した場合はアーカイブデータの情報を見ることもできます。

引数 内容
--json JSON形式の出力

アーカイブフィルタ

引数 内容
-P PREFIX, --prefix PREFIX PREFIXで始まるアーカイブ名を指定
-a GLOB, --glob-archives GLOB GLOBと一致するアーカイブ名を指定。sh規則が適用できます。borg help patternを参照。
--sort-by KEYS KEYSでソートします。timestamp,name,idを指定可。デフォルト:timestamp
--first N 抽出した最初のN個のアーカイブを指定
--last N 抽出した最後のN個のアーカイブを指定

その他

エラーコード

コード 内容
0 成功
1 警告(操作は正常終了したが、警告がある)
2 エラー(致命的なエラー、ローカルまたはリモートの例外)
128+N 信号Nでkillされた(例:137 = kill - 9)

環境変数

一般

BORG_REPO
アーカイブを指定する時に使用する::部分を変更します。
BORG_PASSPHRASE
パスワードを質問された際に自動的に答えるパスワードを設定します。
BORG_PASSCOMMAND
パスワードを質問された際に設定されたコマンドを実行します。BORG_PASSPHRASEを設定している場合はそちらが優先されます。
BORG_NEW_PASSPHRASE
新しいパスワードを質問された際に自動的に答えるパスワードを設定します。
BORG_RSH
リモートアクセス(ssh)を行う際に、sshコマンドにオプションをつけるために設定します。秘密鍵の設定などがそれにあたります。
BORG_REMOTE_PATH
リモートで実行する際に参照するパスを設定します。デフォルトではborgコマンドを直接実行します。
BORG_FILES_CACHE_TTL
数値を設定すると、ファイルキャッシュエントリの最大値(持続時間)を決めることができます。ファイルキャッシュは、ファイルが変更されていないかどうかを迅速に判断するために使用されるファイルです。デフォルトは20です。
BORG_SHOW_SYSINFO
no(デフォルトはyes)に設定すると、例外のシステム情報(OS、Pythonのバージョンなど)が表示されなくなります。問題を分析するのが難しくなるため、設定は慎重に行ってください。
TMPDIR
一時ファイルが保存される場所を指定します。(一部の操作では、一時的なスペースが必要になる場合があります。)

ディレクトリ・ファイル

BORG_BASE_DIR
borgで使用するベースとなるディレクトリです。デフォルトは'\$HOME', '~$USER', '~'の順に読み込まれます。
BORG_CONFIG_DIR
設定ファイルがあるディレクトリです。リポジトリの情報なども保存されています。デフォルトは~/.config/borgです。
BORG_CACHE_DIR
キャッシュの保存先です。リポジトリの情報なども保存されています。デフォルトは~/.cache/borgです。
BORG_SECURITY_DIR
セキュリティ関連データを追跡するために使用する情報が保存されています。デフォルトは'~/.config/borg/security'です。
BORG_KEYS_DIR
リポジトリのキーが保存されています。デフォルトは~/.config/borg/keysです。
BORG_KEY_FILE
設定すると、指定されたファイル名をリポジトリキーファイルとして使用します。
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account log in.