跳至主要内容

Palette Image Builder 參考

請先閱讀建立自訂 Modalix 映像。此頁說明選用功能與開發板操作;容器維護請參閱建置工具 README。

安裝​

標準安裝命令是 sima-cli neat install sdk/pib。它會讀取所選 SDK 發佈項目的 pib/ 中繼資料,取得已驗證的多平台映像,並安裝可攜式主機啟動器。Python 來自 sima-cli 環境,建置工具保留在容器內。預設使用 main,sdk/pib@develop 與 sdk/pib@<release> 可選取其他發佈項目。

Windows 請使用 PowerShell,並將 Docker Desktop 設為 Linux 容器模式。安裝程式會建立 pib.cmd 並更新使用者 PATH。Linux/macOS 則安裝至 ~/.local/bin,必要時更新殼層設定。各平台皆自動選取 amd64/arm64 映像。Linux Docker 主機須支援迴路裝置、device-mapper 與 binfmt_misc;桌面虛擬機也須提供這些功能。pib doctor 可執行檢查。完整映像建立已在原生 Linux x86/ARM 及 Apple Silicon/Colima 驗證。Windows 安裝測試不代表 Windows 完整映像建立已完成驗證。

若不使用 sima-cli,可手動取得公開 Docker 映像並擷取啟動器。PATH 中須有 Python 3:

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 主機重啟後也會自動重新設定,不會在主機安裝套件。

命令​

映像壓縮使用 pigz,充分利用建置主機可用的 CPU 核心。輸出仍相容 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 NAME產生 CA、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 會自動選取,且只能安裝一個核心。本機替換的 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 映像,並提供 sima 的 SSH 與 sudo 存取。

第一次安裝須經授權佈建程序建立 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

更新目標為非作用中槽位。開機選取與 watchdog 回復取決於平台開機/更新實作,需對您的映像進行硬體驗證。預設更新保留開發板的可寫入覆蓋層;清除覆蓋層的更新可能移除本機認證資訊與設定。首次 eMMC 寫入請遵循平台復原指南;SWU 不是 raw 磁碟映像。

目前 PIB 配置使用 GPT boot.A、boot.B,以及包含 rootfs A/B 和資料的 LVM 分割區。不要在此配置套用舊版 raw 分割區 U-Boot 寫入指示。確切幾何配置以版本的開發板範本為準。

新平台版本​

取得適當的建置工具映像並擷取啟動器,再以 pib init 建立全新專案。保留原始 CA 與簽署身分,移入覆蓋層/掛鉤,並將客戶設定合併到新 image.yaml,保留新的 release 與 version 值。

只複製與新平台相容的 Debian 套件。自訂更新指令碼/描述須以該版本預設值為基礎更新。不要用舊 configs/ 整批覆蓋新目錄。維護舊版本時,請保留原專案與固定版本的啟動器/映像參照。