概要
genpack で生成した SquashFS システムイメージをデプロイするためのツール群です。目的ごとに 3 つのコマンドに分かれています。
- GitHub: wbrxcorp/genpack-install
| コマンド | 役割 | root 権限 |
|---|---|---|
genpack-install |
物理ディスクへのインストール、稼働中システムのセルフアップデート | 必要 |
genpack-mkiso |
ブータブル ISO9660 イメージの作成 | 不要 |
genpack-mkzip |
システムイメージとブートファイルの ZIP アーカイブ作成 | 不要 |
genpack-mkiso / genpack-mkzip はシステムイメージを libsquashfs で直接読むため、ループバックマウントを行いません。ビルドホスト上で一般ユーザーとして実行できます。外部コマンドの起動も行いません（xorriso も unsquashfs も呼びません）。
これらは同一パッケージから提供されますが、ebuild の install / iso / zip USE フラグで個別に有効化できます。ISO や ZIP を生成しないアーティファクトでは iso / zip を外すことで、libisofs や minizip を持ち込まずに済みます。
イメージの素性表示
3 つのコマンドはいずれも、処理を始める前にイメージが持つメタデータを表示します。
artifact: owncloud
commit-id: b64fb642091c89cb5f5c6322da6673fb27eb357a (with local changes)
commit-id は include_commit_id を指定してビルドしたイメージにのみ含まれます。イメージファイルは system.img のようなありふれた名前になりがちで、ファイル名からは中身の素性が分かりません。書き込みを始める前にこれが目に入れば、意図と違うものを入れようとしていることに気付けますし、実行ログにも残ります。
genpack-install --disk では確認プロンプトより先に表示されます。-y を指定した場合もプロンプトが無いだけで、書き込み開始前に出力されます。
--require-clean-commit
3 つのコマンドすべてが受け付けるフラグで、素性の不明なイメージや未コミット変更が混じったイメージが本番へ入るのを防ぎます。次の場合にエラー終了します。
/.genpack/commit-idが無い（include_commit_idを指定せずにビルドされた）- 記録が clean でない
clean の判定は「空白区切りでちょうど 1 トークン、かつそれがコミット ID の長さ（40 桁または 64 桁）の 16 進文字列」です。(with local changes) という文言そのものは解釈しません。未知の形式やファイル不在は clean でないものとして扱います（誤って通すより、誤って拒否するほうが害が小さいため）。
オプトインなので、開発中に dirty なイメージを入れたい場合は付けなければ済みます。CI やデプロイスクリプトの既定に入れておき、必要なときだけ外す運用を想定しています。
これはガードレールであってセキュリティ機構ではありません。 イメージには署名がなく、イメージを作れる者はその内容を自由に書けます。詳細は ADR-0007 の「信頼境界」を参照してください。
genpack-install
genpack-install [オプション] [system_image]
root 権限が必要です。
位置引数
| 引数 | 必須 | 説明 |
|---|---|---|
system_image |
動作モードによる | システムイメージファイル（SquashFS） |
セルフアップデートモードでは必須です。--disk モードでは省略可能で、省略時は現在インストールされているシステムイメージが使用されます。
名前付きオプション
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
--disk <PATH> |
文字列 | (なし) | ディスクデバイスパス。list を指定するとインストール可能なディスクの一覧を表示 |
--system-cfg <PATH> |
パス | (なし) | 指定した system.cfg ファイルをインストール |
--system-ini <PATH> |
パス | (なし) | 指定した system.ini ファイルをインストール |
--label <NAME> |
文字列 | (なし) | ブートパーティションのボリュームラベル |
--gpt |
フラグ | false | MBR の代わりに常に GPT を使用 |
--superfloppy |
フラグ | false | パーティショニングせずディスク全体を使用 |
--no-esp |
フラグ | false | ブートパーティションを ESP としてマークしない |
--additional-boot-files <PATH> |
パス | (なし) | 追加のブートファイルを含む ZIP アーカイブ |
--require-clean-commit |
フラグ | false | アーティファクトの作業ツリーが clean だったことを示すコミット ID を持たないイメージを拒否 |
-y |
フラグ | false | 確認プロンプトをスキップ |
--debug |
フラグ | false | デバッグメッセージを表示 |
セルフアップデート（--disk なし）
genpack-install <system_image>
稼働中のシステムのシステムイメージをアトミックに更新します。
更新手順:
- 現在のシステムイメージのパスを特定（ブートパーティションの
system.imgまたはデータパーティションのsystem） - 新しいシステムイメージを検証
- ブートファイル（ブートローダー）を更新
- アトミックなリネーム操作で切り替え:
- 既存の
system.oldを削除（存在する場合） - 新しいイメージを
system.newとしてコピー - 現在のイメージを
system.curにリネーム（ロールバック用に保持） system.newを本来のイメージパスにリネームsyncを実行
- 既存の
失敗時は system.cur から自動復旧を試みます。
ディスクインストール（--disk）
genpack-install --disk=<デバイスパス> [オプション] [system_image]
genpack-install --disk=list
物理ディスクにシステムイメージをインストールします。
--disk=list を指定すると、インストール可能なディスクの一覧を表示します。読み取り専用デバイス、マウント済みデバイス、4GiB 未満のデバイスは除外されます。
パーティショニング:
- MBR/GPT の自動選択: ディスクが 2TiB 以下かつ論理セクタサイズが 512 バイトの場合は MBR、それ以外は GPT が選択されます
--gpt: 条件に関わらず GPT を強制使用--superfloppy: パーティションテーブルを作成せず、ディスク全体を FAT32 としてフォーマット（4GiB 未満のイメージのみ）。BIOS ブートローダーは設置されず、UEFI 専用になります（後述）
通常モード（パーティショニングあり）のレイアウト:
- ブートパーティション（FAT32）: ブートローダー、4GiB 未満のシステムイメージを格納
- データパーティション（Btrfs）: 4GiB 以上のシステムイメージを格納。ラベルは
data-{ブートパーティションUUID}
--no-esp を指定すると、ブートパーティションに ESP（EFI System Partition）フラグを付与しません。一部のブートローダーが ESP フラグを嫌う場合に使用します（MBR 時のみ有効）。
インストール前に確認プロンプトが表示されます。-y で確認をスキップできます。プロンプトの前にイメージの素性（artifact、commit-id 等）が表示されるので、書き込む対象を確認してから答えられます。
genpack-mkiso
genpack-mkiso [オプション] <出力ISOパス> <system_image>
ブータブル ISO9660 イメージを作成します。root 権限は不要です。
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
--label <NAME> |
文字列 | GENPACK |
ISO9660 イメージのボリュームラベル |
--add <DEST=SRC> |
文字列 | (なし) | ローカルファイル SRC を ISO 内の DEST として追加。複数指定可 |
--require-clean-commit |
フラグ | false | アーティファクトの作業ツリーが clean だったことを示すコミット ID を持たないイメージを拒否 |
--debug |
フラグ | false | デバッグメッセージを表示 |
genpack-mkiso --label=MYSYS out.iso ./myimage-x86_64.squashfs
genpack-mkiso --add=system.cfg=./mycfg out.iso ./myimage-x86_64.squashfs
ISO の構成:
| ISO 内パス | 内容 |
|---|---|
/system.img |
システムイメージ |
/boot/grub/grub.cfg |
ブートローダーの grub.cfg |
/boot/grub/i386-pc/eltorito.img |
BIOS ブート用 El Torito イメージ（eltorito-bios.img がある場合） |
| 追記パーティション 2 (0xEF) | EFI ブート用 FAT イメージ（eltorito-efi.img がある場合） |
- BIOS ブート: El Torito no-emulation + boot info table
- EFI ブート: 追記した FAT パーティションを El Torito の platform_id 0xEF エントリとして参照
- 両方のイメージが存在する場合はデュアルブート ISO が生成されます。どちらも存在しない場合は警告を表示し、起動不可能な ISO を生成します
ISO の生成には libisofs を直接使用します。xorriso（libisoburn）は不要です。
注意: ISO に
system.cfgを置いても、イメージ内に/boot/grub/grub.cfgを持つアーティファクトでは読まれません。ブートローダーの grub.cfg はloopback直後にイメージ内 grub.cfg があればconfigfileで処理を委譲してしまい、source ($BOOT_PARTITION)/system.cfgはその後ろにあるためです。
genpack-mkzip
genpack-mkzip [オプション] <出力ZIPパス> <system_image>
システムイメージとブートファイルを ZIP アーカイブにまとめます。root 権限は不要です。
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
--add <DEST=SRC> |
文字列 | (なし) | ローカルファイル SRC をアーカイブ内の DEST として追加。複数指定可 |
--require-clean-commit |
フラグ | false | アーティファクトの作業ツリーが clean だったことを示すコミット ID を持たないイメージを拒否 |
--debug |
フラグ | false | デバッグメッセージを表示 |
ZIP に含まれるファイル:
system.img— システムイメージ- Raspberry Pi のブートファイル（Raspberry Pi イメージの場合、イメージ内
boot/以下を再帰的に格納） --addで指定したファイル
ZIP64 は使用しません。格納対象ファイルの合計サイズが 4GiB 以上になる場合は、生成を開始せずエラーになります。
--add=DEST=SRC
genpack-mkiso と genpack-mkzip に共通のオプションです。
DESTはイメージ／アーカイブ内のパス、SRCはローカルファイルです。最初の=で分割します（SRCのパスに=が含まれていても構いません）- 省略形（
--add=fileのような=なし）は認められません。常にDEST=SRCの形が必要です SRCは通常ファイルのみです。ディレクトリを指定するとエラーになりますDESTにサブディレクトリを含めてよく、中間ディレクトリは自動生成されますDESTはパスを正規化してから重複判定されます。正規化後に同じDESTとなる指定は警告を表示して後勝ちになります- ブートファイルなど、ツールがあらかじめ配置するパスと重複した場合は警告を表示して後勝ちになります。必須ファイルを上書きして起動不能な成果物を作る可能性は利用者の責任です
- ただし次の 2 つは予約パスで、
--addで置き換えようとするとエラーになりますsystem.img— 位置引数で指定したシステムイメージが入ります。これを差し替えると、表示されるメタデータや--require-clean-commitが参照したイメージと、成果物に入るイメージが食い違うためです。別のイメージを入れたい場合は位置引数を変えてください- El Torito ブートカタログ（
boot/grub/i386-pc/boot.catまたはboot/grub/boot.cat、genpack-mkisoのみ）— libisofs が生成するもので、こちらから渡す手段がありません
旧 genpack-install --cdrom / --zip にあった --system-cfg / --system-ini は --add に一本化されています。
genpack-mkiso --add=system.cfg=./mycfg out.iso image.squashfs
genpack-mkzip --add=system.ini=./system.ini-for-thisvariant out.zip image.squashfs
出力ファイルの扱い
genpack-mkiso / genpack-mkzip は、出力先と同じディレクトリに一時ファイルを作ってそこに書き込み、すべての入力を読み終えて完全な成果物になってから rename で指定された出力先へ置き換えます。失敗時は一時ファイルを削除し、既存の出力ファイルには手を触れません。
出力先がシステムイメージまたは --add の SRC と同じファイル（シンボリックリンク／ハードリンク経由を含む）である場合は、入力を破壊しないよう生成開始前にエラーになります。
ブートローダー
genpack-install / genpack-mkiso は GRUB をブートローダーとして使用します。ブートローダーファイルは以下の順序で検索されます:
- システムイメージ内の
/usr/lib/genpack-install/ - ホスト側の
/usr/local/lib/genpack-install/ - ホスト側の
/usr/lib/genpack-install/
genpack-install がインストールするファイル:
- EFI ブートローダー:
boot*.efiファイルがefi/boot/にコピーされます - BIOS ブートローダー: 以下をすべて満たす場合にインストールされます
- パーティショニングを行った（
--superfloppyではない） - MBR が選択された（ディスクが 2TiB 以下かつ論理セクタサイズ 512 バイトで、
--gptを指定していない） boot.img、core.img、grub.cfgが揃っているgrub-bios-setupが利用可能
- パーティショニングを行った（
--superfloppyは UEFI 専用です。 パーティションテーブルを作らないモードでは BIOS ブートローダーは設置されません。これは現在のcore.imgの作りによる制約です。
core.imgはgrub-mkimage -p '(,msdos1)/boot/grub'でプレフィックスを埋め込んでいるため、パーティション 1 が存在しない superfloppy ではgrub.cfgに到達できませんgrub-bios-setupは MBR 直後のギャップにcore.imgを埋め込みますが、superfloppy はセクタ 0 が FAT32 の BPB で、そのギャップがありませんBIOS で起動する必要がある場合は
--superfloppyを使わずに通常のパーティショニングを行ってください。
対応アーキテクチャ:
| アーキテクチャ | BIOS | UEFI |
|---|---|---|
| x86_64 | boot.img + core.img | bootx64.efi |
| i386 | boot.img + core.img | bootia32.efi |
| aarch64 | — | bootaa64.efi |
| riscv64 | — | bootriscv64.efi |
Raspberry Pi のサポート:
システムイメージに boot/bootcode.bin が含まれる場合、Raspberry Pi イメージとして扱われます。boot/ ディレクトリの全ファイルがブートパーティション（genpack-install --disk）または ZIP アーカイブ（genpack-mkzip）に格納され、cmdline.txt の root= パラメータが root=systemimg:auto に書き換えられます。rootfstype= は除去されます。
genpack-install --disk では、既にブートパーティションに cmdline.txt / config.txt が存在する場合は上書きしません。
grub.cfg の system.img 検索ロジック:
- ブートパーティションに
system.imgが存在すればそれを使用 - 存在しない場合、
data-{ブートパーティションUUID}ラベルのパーティションを検索 - さらに
d-{ブートパーティションUUID}ラベルを検索 - 最終手段としてブートパーティション番号から推測（パーティション 1 → パーティション 2 を試行）
パーティション構成
ブートパーティション（FAT32）
- ブートローダー（GRUB EFI ファイル、BIOS イメージ）
grub.cfgsystem.cfg/system.ini（指定時）- 4GiB 未満のシステムイメージ:
system.imgとして格納
ブートパーティションサイズは、システムイメージが 4GiB 未満の場合は max(4, image_size_gib * 3 + 1) GiB、4GiB 以上の場合は 1 GiB です。
カーネル（boot/kernel）と initramfs（boot/initramfs）はブートパーティションには置かれません。GRUB が loopback でシステムイメージをマウントし、その中から直接読み込みます。
データパーティション（Btrfs）
--superfloppy使用時は作成されません- ラベル:
data-{ブートパーティションUUID} - 4GiB 以上のシステムイメージ:
systemとして格納
システムイメージの検証
3 つのツールはいずれも処理前にシステムイメージの検証を行います:
.genpack/ディレクトリが存在すること- 以下のいずれかを満たすこと:
boot/kernelとboot/initramfsが存在する（通常のイメージ）boot/bootcode.binが存在する（Raspberry Pi イメージ）
検証に通過すると、.genpack/artifact と .genpack/variant の内容が表示されます。
ソースリファレンス
このドキュメントは以下のリポジトリのスナップショットに基づいて作成されました:
- wbrxcorp/genpack-install（
isozipブランチ）
