メインコンテンツまでスキップ

Palette Image Builder リファレンス

まず カスタム Modalix イメージの作成を参照してください。このページは追加機能とボード操作を説明します。コンテナの保守については ビルダー READMEを参照してください。

インストール​

標準のインストールコマンドは sima-cli neat install sdk/pib です。選択した SDK 公開物の pib/ メタデータから検証済みマルチプラットフォームイメージを取得し、ホストランチャーをインストールします。Python は sima-cli の環境を使用し、ビルドツールはコンテナ内にあります。既定は main で、sdk/pib@develop や sdk/pib@<release> で別の公開物を選択できます。

Windows では Docker Desktop を Linux コンテナモードにして PowerShell から実行します。インストーラーは pib.cmd を作成し、ユーザー PATH を更新します。Linux/macOS では ~/.local/bin にインストールし、必要に応じてシェルプロファイルを更新します。いずれも amd64/arm64 イメージを自動選択します。Linux Docker ホストはループデバイス、device-mapper、binfmt_misc のカーネル機能を提供する必要があり、デスクトップ VM でも同様です。pib doctor で確認します。完全なイメージ作成はネイティブ Linux x86/ARM と Apple Silicon/Colima で検証済みです。Windows のインストーラーテストは、Windows 上の完全なイメージ作成を保証するものではありません。

sima-cli を使わず Docker から手動で使用する場合は、公開イメージを取得してランチャーを取り出します。Python 3 を PATH に用意してください。

export PIB_IMAGE=ghcr.io/sima-neat/palette-image-builder-develop:latest
docker pull "$PIB_IMAGE"
mkdir -p "$HOME/.local/bin"
docker run --rm --entrypoint cat "$PIB_IMAGE" \
/usr/local/share/pib/host/pib > "$HOME/.local/bin/pib"
chmod +x "$HOME/.local/bin/pib"
export PATH="$HOME/.local/bin:$PATH"
pib doctor

x86 イメージにはエミュレーターが含まれます。特権 PIB の起動時に、動作する ARM64 ハンドラーがなければ Docker ホストの Linux カーネルに登録します。既存の動作するハンドラーは保持され、ネイティブ ARM64 では登録不要です。Docker ホスト再起動後の再登録も自動です。ホストにパッケージをインストールしません。

コマンド​

イメージの圧縮は、ビルダーで利用できる CPU コアを使用する pigz で行います。出力は gzip 互換であり、署名と検証は実際の圧縮ペイロードを対象とします。

ビルド間で Debian のダウンロードを再利用するには、ホストのキャッシュディレクトリを指定します。

export PIB_DEB_CACHE="$HOME/.cache/sima/pib-debs"
pib build --sign

キャッシュするのはパッケージのバイト列のみです。各 bootstrap は最新のリポジトリメタデータを取得して認証し、SHA256 とサイズでキャッシュを検証します。破損したデータは破棄して再取得します。ルートファイルシステム、パッケージのインストール、フック、署名、検証は毎回実行します。カスタムパッケージが含まれる場合があるので、キャッシュは自分のユーザーディレクトリに置いてください。

コマンド用途
pib doctorツール、空き容量、ループデバイス、device-mapper、エミュレーションの確認
pib init DIR --flavor minimalプロジェクト作成。minimal、palette、securepalette を選択可能
pib init DIR --example custom-image完全なサンプル定義と入力のコピー
pib shell現在のプロジェクトをマウントしたコンテナシェルを開く
pib keys init --cn NAMECA、SWU リーフ証明書、Debian 署名情報の生成
pib keys renew --cn NAME同じ CA でリーフ証明書を更新
pib sign-debs / pib verify-debsカスタム Debian パッケージの署名・確認
pib build [--sign] [--supplier NAME]ビルド、および任意の署名・検証
pib sign [FILE]バンドルに署名。既定は現在のプロジェクトバージョン
pib verify [FILE] [--ca CRT] [--manifest JSON]署名とペイロードを検証。プロジェクト設定と隣接マニフェストを自動選択
pib diff --against MANIFEST以前のビルドとのパッケージ差分
pib clean [--yes]ビルドのループデバイスとボリュームグループの確認・削除

すべてのコマンドはコンテナ内で実行されます。ホストランチャーは Docker、ワークスペースのマウント、明示的に指定した外部ファイルだけを扱います。build、doctor、clean、対話シェルは特権デバイスアクセスを使用します。署名、検証、鍵生成、プロジェクト作成には不要です。

カスタマイズ​

image.yaml を編集します。ボードサポートを開発する場合以外は、configs/ のリリース既定値を変更しないでください。

base: minimal
release: 3.0.0
version: 3.0.0.2
packages:
add: [my-app]
remove: []
overlay: overlay/
hooks: [hooks/enable-my-app.sh]
vendor: My Company

アプリケーションサービスを有効にするインストール後フックを作成します。

#!/bin/sh
set -eu
systemctl --root="$1" enable my-app.service

フックはパッケージのインストールと SiMa のフックの後に、指定順で sh によって実行されます。$1 は rootfs のディレクトリです。その配下に書き込むか systemctl --root="$1" を使用します。chroot "$1" はイメージ内の ARM64 プログラムを実行します。フックには、英数字と _ . / + - のみを含むワークスペース相対パスを指定してください。

別のパッケージが必要とするパッケージを削除すると、APT の依存関係解決が失敗します。swupdate や palette の kea など、ボードのフックが必要とするものは保持してください。palette から minimal に変更すると、イメージサイズや既定のパッケージ構成も変わります。

カスタム Debian パッケージには、image.yaml の debs.key で受け入れられる分離署名が必要です。pib sign-debs は生成した Debian 署名鍵を使用します。既存の GPG 識別情報を使用する場合は、公開鍵を keys/debs-signing.asc にエクスポートし、外部でパッケージに署名してビルド前に pib verify-debs を実行します。

カーネルは特別な扱いです。configs/images/image-params.yaml にあるリリースのカーネルパッケージ名を維持します。PIB はそのカーネルを自動選択し、インストール済みカーネルは 1 つである必要があります。ローカルの tRoot、ATF、U-Boot 置換パッケージは拒否されます。パッケージの U-Boot は fip.bin 内のものと一致する必要があります。

swu.description と swu.script を指定すると、更新手順を置き換えられます。最初に configs/images/files/ のリリース既定値をコピーしてください。バージョン・ハードウェア互換性のプレースホルダー、ハッシュ、必須のブート/SBOM メンバーを保持します。これらはインストール時にボードで動くため、復旧可能なボードで変更を試してください。

securepalette は追加のカーネル FIT 署名検証を行い、出荷用には本番署名されたブートパッケージが必要です。この移植の minimal イメージのスモークテストでは検証していません。--dev は一時的な署名情報を使用し、通常配布用の --sign と併用できません。開発用に生成する顧客 CA/リーフ鍵と --dev モードは別のものです。

署名​

イメージは signing.ca を更新の信頼ルートとして組み込みます。既存ボードを更新するときも、その CA を維持してください。ワークスペース外の鍵を使用する例です。

cp /path/to/public-ca.crt keys/ca.crt
SWU_SIGNING_KEY=/path/to/private-signing.key \
SWU_SIGNING_CERT=/path/to/public-signing.crt pib sign
pib verify

ランチャーはディレクトリ全体ではなく、選択した各ファイルを読み取り専用でマウントします。pib build --sign も同じ変数を受け付けます。より強い分離が必要なら、秘密鍵を別の署名マシンに置き、ビルドと署名を独立して実行します。CA 秘密鍵はリーフ証明書の発行・更新にだけ必要です。通常のビルドプロジェクトではなくオフラインで保管します。

生成したリーフを更新するには、一時的に ca.key を keys/ に戻し、初期設定と同じアルゴリズムで pib keys renew --cn 'My Company Development' を実行してから、CA 鍵を再びオフラインへ戻します。リーフ証明書の有効期間は 825 日です。

PKCS#11 には pib sign --pkcs11 'pkcs11:...' --cert keys/swu-signing.crt を使います。Docker ホストには pcscd とリーダードライバーが必要です。署名時にランチャーが利用可能な pcscd ソケットをマウントします。PIB_PCSCD_DIR で場所を変更できます。物理カード・トークンでの操作は、この移植では未検証です。macOS のホストソケットが Linux Docker VM から使用できるとは限りません。

暗号化する場合は pib keys payload を実行し、ビルド前に encryption: {key: keys/payload.key} を設定してから pib sign --encrypt を使います。イメージ自体に復号鍵が含まれるため、イメージを抽出できる相手からの保護にはなりません。暗号化ではビルドと署名を分けてください。build --sign は通常の非暗号化署名です。

ボードへのアクセス​

新しいイメージを書き込む前に、認証情報か許可済み SSH 鍵を設定します。root と sima のパスワードハッシュを指定する場合は、保護された資格情報ファイルをプロジェクト外に作成し、PIB_CREDENTIALS で指定します。

mkdir -p ../secure
chmod 700 ../secure
(umask 077; printf 'root:%s\nsima:%s\n' \
"$(openssl passwd -6)" "$(openssl passwd -6)" > ../secure/credentials)
PIB_CREDENTIALS="$(cd ../secure && pwd)/credentials" pib build --sign

この方法ではホストに OpenSSL が必要です。パスワードは入力を求められ、保存されるのはハッシュだけです。root の SSH 接続は鍵認証に限定されます。代わりに、許可された公開鍵を overlay/root/.ssh/authorized_keys に置くこともできます。ディレクトリを 700、ファイルを 600 にしてください。各ボードは初回起動時に独自の SSH ホスト鍵を生成します。

SWU をインストールする​

以下はボードを変更するコマンドです。署名済み .swu と対象ボードを明示的に選んでください。ボードは互換性のある SiMa/PIB eLxr イメージで動作し、sudo を使用できる sima の SSH アクセスが必要です。

初回は、認可されたプロビジョニング手順で CA の信頼を設定します。開発用ボードでの初期設定例を示します。

BOARD=192.0.2.10
SWU=out/your-image.swu
scp "$SWU" keys/ca.crt "sima@$BOARD:/tmp/"
ssh -t "sima@$BOARD" sudo swupdate -i "/tmp/$(basename "$SWU")" \
-k /tmp/ca.crt -e update,full
ssh -t "sima@$BOARD" sudo reboot

以降の更新では、インストール済み CA とバージョンポリシーを使用します。

scp "$SWU" "sima@$BOARD:/tmp/"
ssh -t "sima@$BOARD" sudo simaai-update "/tmp/$(basename "$SWU")" -e update,full
ssh -t "sima@$BOARD" sudo reboot

更新先は非アクティブスロットです。ブート選択とウォッチドッグによるロールバックはプラットフォームのブート・更新実装に依存するため、使用するイメージでハードウェア検証が必要です。既定ではボードの書き込み可能オーバーレイを保持します。オーバーレイを初期化する更新では、ローカルの認証情報や設定が消える場合があります。初回 eMMC 書き込みはプラットフォームの復旧手順に従ってください。SWU は raw ディスクイメージではありません。

現在のレイアウトは GPT の boot.A、boot.B と、rootfs A/B およびデータを含む LVM パーティションです。旧来の raw パーティション用 U-Boot 書き込み手順を適用しないでください。正確な構成は各リリースのボードテンプレートで定義されます。

新しいプラットフォームリリース​

対応するビルダーイメージを取得してランチャーを取り出し、pib init で新しいプロジェクトを作成します。元の CA と署名情報は維持してください。オーバーレイとフックを移行し、新しい release と version を保持したまま顧客設定を image.yaml にマージします。

新しいプラットフォームと互換性のある Debian パッケージだけを移してください。独自の更新スクリプト・定義は、そのリリースの既定値を基に更新します。古い configs/ を丸ごとコピーしないでください。旧リリースを保守する場合は、以前のプロジェクトと固定したランチャー・イメージ参照も保存します。