アップグレードとロールバック

このページで解決すること

パッケージ導入は custodexa.sh upgrade で更新します。スクリプトは停止時間をプレビューし、版を切り替える前に停止バックアップを自動で取り、更新後にサービスと証拠チェーンを確認します。更新前の版に戻すときは custodexa.sh rollback を使います。バックアップ手順はバックアップと復元を参照してください。

必要なもの

.env、データディレクトリ、四つの鍵の指紋の記録。
既存セッションの終了、監査キューの排出、データベース移行に必要な停止時間。
新版イメージを置ける Docker データフォルダの空きと、更新前バックアップを置けるバックアップフォルダの空き。スクリプトは開始前に空き容量を確認します。

設定のしかた

更新前

プレビューには開いている接続の数と停止時間の見込みが出るので、メンテナンスの時間帯を告知してセッションを終えてもらいます。スクリプトはサービスを止める前に監査キューが空になるのを待ち、空にならなければその場で止まり、サービスはそのまま動き続けます。SSH の切断で中断しないよう、ホスト上の tmux や screen の中で実行します。バージョン、イメージ ID、鍵の指紋、テーブル件数を記録します。DATA_PATH は絶対パスにします。

先にサービスを止めたいときは、custodexa.sh stop が確認を求め、未書き込みの監査記録が書き終わるのを待ってから停止します。custodexa.sh start は導入全体を起動し、バックエンドの準備ができるまで待ちます。

新版のエクスポート成果物は ${DATA_PATH}/exports に永続化され、標準のバックアップ範囲には入りません。旧版から手動更新する前に必要な成果物をコンテナ外へ移すか、ダウンロードします。

パッケージ導入

インストール済みの custodexa.sh で新版を照会し、メニューで対象を選ぶか、次を実行します。

sudo /opt/custodexa/custodexa.sh upgrade             # 照会のみ
sudo /opt/custodexa/custodexa.sh upgrade <version>   # 対象版
sudo /opt/custodexa/custodexa.sh status

ダウンロード済みパッケージのパスも指定できます。対象のない照会に --images-from は指定できません。インストール済みスクリプトが 1.14.0 以降なら、メニューでイメージソースを選べます。コマンドの --images-from auto|source は省略時に auto です。自動ではホスト、オフラインバンドル、GHCR、Docker Hub、最後にローカルビルドの順に試します。source はパッケージ内のソースを検証して backend と frontend をビルドします。上流イメージとビルド依存関係は別途取得するため、完全なオフライン手段ではありません。取得、検証、ビルドの長い処理は開始前に進捗、完了時に結果を表示します。

1.13.x から初めて 1.14.0 に上げるときは、インストール済みの旧スクリプトが開始します。旧スクリプトは --images-from を受け付けず、メニューにもソース選択がありません。フラグを省くと 1.14.0 側は auto を使います。1.14.0 のインストール後のアップグレードからソースビルドを選べます。データベース移行の結果はバックエンド起動ログで確認します。

更新前のバックアップ

版を切り替える前に、スクリプトは backend、guacd、frontend を止め、録画を含み暗号化しない単一ファイルの停止バックアップを書き出します。形式は custodexa.sh backup と同じです。外部データベースの構成もスクリプトがバックアップします。リリースには PostgreSQL 16、17、18 のクライアントが入っており、データベースサーバーのメジャーバージョンに合うものを使い、どのサービスも止める前にデータベースを確認します。

仮想マシンやストレージのスナップショットなど、自分のスナップショットを使うこともできます。端末ではスクリプトが先にバックアップを任せるかどうかを尋ねます。自分のスナップショットを選んだ場合は、サービスの停止後にスナップショットを開始し、データフォルダ、.env、tls/（外部データベースでは停止後に開始したデータベースのバックアップも）を含めてから、スナップショットの名前、開始時刻、復元手順の置き場所を入力します。端末がないときは、先に custodexa.sh stop でサービスを止め、停止後にスナップショットを開始してから、--backup-ref、--backup-time、--backup-restore をまとめて指定します。スクリプトがデータベースのクライアントを取得できない、または外部データベースに接続できないときは、プレビューが理由を示し、この手順は自分のスナップショットで行います。

旧イメージ

更新が成功すると、スクリプトは新版と一つ前の版の backend と frontend のイメージだけを残し、それより古いものを削除します。そのため rollback に必要なイメージは常に残ります。上流イメージ、コンテナが使っているイメージ、ほかのリポジトリのタグも付いたイメージは削除しません。最後の画面に削除した数と空いた容量が出ます。削除できなかったイメージは手動で実行する docker rmi コマンドとともに示され、更新は成功として扱われます。

すべてのイメージを残すには、upgrade に --keep-images を付けます。このオプションは更新を開始するインストール済みスクリプトが読むため、そのスクリプトが 1.17.6 以降である必要があります。イメージが削除された版のバックアップを復元するときは、レジストリへの接続か、その版のオフラインイメージバンドルを用意します。

古い git clone 導入の手動移行

古い git clone ツリー内で scripts/custodexa/custodexa.sh を直接実行するか、CUSTODEXA_HOME をそこに向けると、旧版のソース導入であること、導入ファイルとサービスは変更されていないことを説明して操作を拒否します。先にバックアップと導入設定を確認し、アップグレード SOP の手動移行手順に従うか、別の空のディレクトリへパッケージを導入してバックアップと復元に沿って手動復元します。既存データのディレクトリで install を直接実行しないでください。

検証とロールバック

ヘルスチェック、鍵の指紋、チェックポイントチェーン、古い録画の再生、新しい接続の監査を確認してから、利用者の接続を再開します。

更新前の版に戻すには、次を実行します。

sudo /opt/custodexa/custodexa.sh rollback

新版がまだデータベースを変更していなければ、rollback は導入を前の版に戻し、データ、.env、証明書を保ちます。変更済みの場合、rollback は版を切り替えず、その更新で取ったバックアップを復元する restore コマンドを画面に示します。ロールバックが中断したときは、rollback --resume で完了させ、rollback --revert で更新後の版に戻ります。rollback が戻すのは一つ前の版までで、戻り先は 1.16.0 以降です。1.16.0 から 1.15.x に戻すときは、バックアップと復元に沿って更新前のバックアップを手動で復元します。データベース移行は逆向きに実行しません。

バックアップの後で更新が失敗した場合は、restore を完了すれば upgrade を再実行でき、status にその復元で失敗に対処したことが表示されます。

監査で見えること

チェックポイント検証と新旧セッションで証拠チェーンを確認できます。テキストセッションの事実の出どころは録画で、エコーされない入力はコマンド本文の記録に残りません。クエリコンソールの構造化された文の記録は、そのクエリの事実の出どころです。