Fleetd クライアントはどう更新する?署名検証、バージョン判定、障害からの復旧

Fleetd v0.3.0のソースから、署名、アーキテクチャ、バージョンの検証と実行ファイルの置き換えを解説。手動復旧と自動ロールバックの違いも整理。

リモート管理ツールで最も避けたいことの一つは、クライアントを更新したあと、そのマシンに二度と接続できなくなることだ。

サーバーが手元にあれば、ログインして修復できる。だが、別の場所にあるソフトウェアルーターでは、更新によって接続が切れると、管理画面の「再試行」ボタンは役に立たないかもしれない。

そこで、これまでの Fleetd 開発記録5本に続き、今回はクライアントの更新を扱う。単に新しいファイルをダウンロードするだけではない。そのファイルは信頼できるか、そのマシンに適しているか、入れ替えたあとに問題が起きたらどうするか、という三つの問いに答える必要がある。

まず対象範囲を明確にしておく。この記事は Fleetd v0.3.0、コミット c4a066d の公開ソースコードとドキュメントに基づく。このバージョンは管理者が開始するリモート更新に対応しているが、定期的に最新版を自動取得する機能も、稼働状態のヘルスチェックに基づく自動ロールバックもない。本文の障害時の受け入れ確認は提案であり、本番環境でのアップグレード演習を実施した結果ではない。

リモート更新では、まず「誰が何を決めるか」を分ける

Fleetd の更新フローは管理画面から始まる。管理者はリリースパッケージをアップロードし、オンラインのマシンを1台選んでバージョンを指定できる。同じアーキテクチャで、バージョンが古いオンラインのマシンを更新することもできる。[1]

サーバーはパッケージの配布と更新要求の伝達を担当し、クライアントはそれを受け入れるかどうかを判断する。

この違いは重要だ。自分の管理画面にファイルが表示されたからといって、自動的に信頼できるわけではない。クライアントにはリリース用公開鍵 release_key をローカルで設定し、パッケージを受け取ったら自ら署名を検証させる必要がある。この公開鍵が設定されていなければ、リモート更新は拒否される。[2]

サーバー側にもリリース用公開鍵が設定されていれば、アップロード時にリリースパッケージを検証する。ただし、サーバー側の検証はクライアント側の検証の代わりにはならない。ソースコード上、サーバーにリリース用公開鍵が設定されていない場合は、保存と表示のためにパッケージのマニフェストを解析するだけでもよい。そのため、「アップロード成功」はクライアントが必ず受け入れる証拠にはならない。[4]

リリース用秘密鍵は誰が信頼されるパッケージを作れるかを決め、公開鍵はクライアントが誰を信頼するかを決める。自分でデプロイする場合は、リリース鍵の管理主体を明確にすべきであり、ダウンロードした任意のリリースパッケージをインストール可能なファイルとして扱ってはならない。

これは前の記事のブラウザーコマンドの署名とも異なる。コマンド署名は個々の操作の認可に、リリース署名はソフトウェアパッケージの確認に使う。両者の役割と鍵管理を混同してはならない。

署名はファイルのハッシュを一つ計算するだけではない

v0.3.0 のリリースパッケージには、マニフェスト、署名、クライアントのバイナリが含まれる。マニフェストにはバージョン、CPU アーキテクチャ、ファイルサイズ、SHA-256 が記録される。[3]

署名の対象はマニフェストの元のバイト列であり、マニフェスト内のハッシュによってバイナリの内容が制約される。クライアントはまず信頼済みの公開鍵で Ed25519 署名を検証し、その後、バイナリのサイズとハッシュがマニフェストと一致するかを確認する。

これによって、つながりのある二つの問題を確認できる。

  • マニフェストは対応する秘密鍵の保持者が署名したものか。改変されていないか。
  • ダウンロードしたバイナリは、確かにそのマニフェストが記述するファイルか。

ハッシュだけで信頼できる署名元がなければ、同じ役割は果たせない。攻撃者がファイルと、その横にあるハッシュ値の両方を差し替えられるなら、両者はなお「一致」してしまう。

ただし、有効な署名もソフトウェアにバグがないことは証明しない。ファイルが信頼済みの署名プロセスから来たことを示すのであって、あらゆるマシンでプログラムが正常に動くことを示すわけではない。リリース用秘密鍵の漏えい、ビルド環境の問題、あるいは保守担当者自身が欠陥のあるプログラムに署名した場合は、別途対処が必要になる。

バージョンとアーキテクチャはクライアントでもう一度判断する

署名検証後、クライアントはマニフェストのアーキテクチャが自身の runtime.GOARCH と一致するか、またマニフェストのバージョンが現在稼働中のバージョンより新しいかを確認する。[2]

したがって、署名が正しい arm64 パッケージでも、管理画面の一覧に表示されているというだけで amd64 クライアントにインストールすることはできない。

バージョン判定にも具体的な境界がある。v0.3.0 が比較するのは、メジャー、マイナー、パッチを構成する三つの整数であり、ハイフン以降の接尾辞は無視する。[3]

例えば、この関数の規則では、0.4.0-dev と 0.4.0 のバージョン本体は同じで、後者は前者より新しいとは判定されない。これは SemVer のプレリリースを含む完全な順序付け規則ではない。一般的な SemVer の感覚をソースコード上の挙動の代わりにしてはならない。

同一バージョンと古いバージョンは拒否される。これにより、通常の更新経路から安易にダウングレードすることは防げるが、あらゆる経路でのロールバック防止を意味するわけではない。ローカルファイルを変更する権限がある人はプログラムを置き換えられるし、古いファイルへの復旧はドキュメントにも明示された保守手段だ。

通常のリリースでは、リリースマニフェストとバイナリに埋め込まれたバージョンを一致させるべきだ。プロジェクトのビルドスクリプトはプログラムのバージョンを設定する。リリースバージョンと署名用秘密鍵ファイルを指定すると、対応するアーキテクチャの署名済みパッケージも生成する。[5]

入れ替える前に、新しいプログラムに一度バージョンを答えさせる

クライアントはダウンロード直後に自分自身を上書きするわけではない。

まず検証済みのバイナリを実行ファイルの隣に .new ファイルとして書き込み、その新しいファイルの version サブコマンドを実行する。プログラムが制限時間内に終了し、出力が署名済みマニフェストのバージョンと一致することを求める。[2]

この手順では、プログラムを起動できない、ビルド成果物が違う、別のバージョンを報告するといった、明らかな誤りの一部を防げる。

それでも、これはごく小さな自己テストにすぎない。バージョンを出力できても、設定の読み込み、サーバーへの接続、メトリクスの収集、認可された操作の実行といった経路がすべて正常とは限らない。version を通過したプログラムでも、通常起動時に失敗する可能性はある。

自己テストを通過すると、プログラムは古いファイルを .old として残そうとし、その後、リネームによって .new を正式なパスに置き換える。一時ファイルを同じディレクトリに置くことは、この置き換え手順の一部だ。任意のファイルシステム間コピーでも同じ挙動が得られると解釈してはならない。

置き換え完了後、現在のプロセスは結果を報告して終了し、その後の起動は systemd または procd に委ねられる。プロジェクトのインストールテンプレートには、これらの再起動の仕組みが設定されている。クライアントを手動で実行している場合やサービス設定を変更している場合は、誰が新しいプログラムを起動するのかを別途確認する必要がある。

つまり、管理画面がインストール成功の結果を受け取る時点と、新しいプロセスが健全な状態でオンラインになる時点は異なる。

障害からの復旧は、どこで失敗したかによる

「失敗したらロールバックする」という言い方は大ざっぱすぎる。v0.3.0 の実装では、少なくとも次の段階を区別する必要がある。

失敗した段階 現在の実装が行うこと さらに確認すべきこと
ダウンロード、署名、内容、アーキテクチャ、またはバージョンのチェックに失敗 エラーを返し、正式なプログラムは置き換えない エラーの原因が記録されているか、元のクライアントが引き続き正常に動いているか
新しいプログラムのバージョン自己テストに失敗 一時ファイルを削除し、正式なプログラムを残す ビルド、実行環境、またはバージョン表記の問題か
置き換え時のリネームに失敗 エラーを返して一時ファイルを削除する ディレクトリの権限、ファイルシステム、ディスクの状態
置き換え後、新しいプロセスの起動または通常運用に失敗 稼働状態に基づく自動ロールバック処理はない 帯域外でのログイン、旧ファイル、設定のバックアップ、手動での復旧手段

見落としやすい点もある。ソースコードはまずハードリンクで古いプログラムを保存しようとし、失敗すると読み書きによるコピーを試みる。この代替経路では、一部の失敗がその後の置き換えを止めない。[2]

したがって、実装に .old が登場するというだけで、毎回使用可能なバックアップが作られたとは約束できない。正式リリース前には旧ファイルが実際に存在し、内容が正しく、実行可能であることを確認し、独立した復旧経路も確保すべきだ。

同様に、リネームによる置き換えはマシン全体のアップグレードトランザクションではなく、電源断後のデータ永続性の保証でもない。この記事では、電源断、ディスク障害、実際の OpenWrt デバイスでの検証は行っていない。

まず1台を更新し、それから一括更新を考える

プロジェクトのドキュメントには、全自動更新を実装していないことが明記されている。欠陥のあるバージョンをすべてのマシンに同時に配布すると、全クライアントがオフラインになる可能性があり、そうなれば管理画面に頼って修復することはできない。[1]

更新の受け入れ確認は、三段階に分けるのがよいと考える。

第一段階は、インストール前の拒否テストだ。隔離された環境で、誤った署名、改変された内容、異なるアーキテクチャ、同一または古いバージョンを用意し、クライアントがインストールを拒否して正式なファイルを置き換えないことを確認する。

第二段階は置き換えのテストだ。新しいプログラムのバージョン自己テスト、旧ファイルの保存、そしてサービスマネージャーが実際に新しいプロセスを起動したかを確認する。

第三段階は、オンライン復帰後の通常運用の確認だ。新バージョンが再接続し、メトリクスの送信が続き、必要な操作を完了できることを確認する。自身の運用に適した時間だけ様子を見てから、対象を広げる。ここでは「何分待てば安全」という一律の基準は設けない。

リポジトリにはリリースパッケージとインストール処理のテストがあり、不正な署名、ファイルの改変、バージョンとアーキテクチャによる拒否、バージョン出力の不一致、正常な置き換え後の旧ファイル保存などの経路を対象としている。[6] 今回これらのテストは読んだが、再実行はしておらず、実機でのアップグレード成功を示す証拠ともみなしていない。

新しいプログラムがすでに接続できなくなった場合、復旧作業はデプロイ環境に応じて行う必要がある。公式ガイドが示すのは、古いバイナリに手動で置き換えてからサービスを再起動する方法だ。Linux と OpenWrt ではプログラムのパスもサービス管理方法も異なるため、別の種類のマシン向けのコマンドをそのまま使うべきではない。[1]

信頼できる更新は、「マシンが再びオンラインになり、必要な仕事を完了したこと」を終了条件にすべきだ。署名とバージョンのチェックは前段の関門であり、その先の復旧経路も残しておかなければならない。

参考資料

確認日:2026-11-09。実装の分析対象は v0.3.0 に固定しており、後続バージョンの挙動を示すものではない。前の記事:サーバー監視の次に、アラートを本当に役立つものにするには?

  1. Fleetd v0.3.0:クライアント更新ガイド。
  2. クライアントの更新と自己テストの実装。
  3. リリースパッケージの署名、検証、バージョン比較。
  4. サーバー側のリリースパッケージのアップロードと配布。
  5. ビルドスクリプトとクライアントサービスのインストールテンプレート。
  6. インストールテストとリリースパッケージのテスト。

AI生成の概念図です。製品の実測写真、実際の画面、配線図ではありません。

コメント・議論

質問や実践の経験をお寄せください。コメントは承認後に表示されます。メールアドレスは公開されません。 コメントのプライバシー

コメントを読み込み中…