Перейти до основного вмісту

Довідник Palette Image Builder

Почніть зі створення власного образу Modalix. Тут описано додаткові можливості й операції з платою; обслуговування контейнера наведено в README збирача.

Встановлення​

Стандартна команда — sima-cli neat install sdk/pib. Інсталятор читає підкаталог метаданих pib/ вибраної публікації SDK, завантажує перевірений багатоплатформний образ і встановлює переносний засіб запуску на хості. Python надає середовище sima-cli; інструменти збирання залишаються в контейнері. Типово використовується main; sdk/pib@develop і sdk/pib@<release> вибирають інші публікації.

У Windows запускайте команди з PowerShell із Docker Desktop у режимі контейнерів Linux. Інсталятор створює pib.cmd та оновлює PATH користувача. У Linux/macOS він встановлює файли в ~/.local/bin і за потреби оновлює профіль оболонки. Образ amd64/arm64 вибирається автоматично. Хости Docker на Linux потребують підтримки loop-пристроїв, device-mapper і binfmt_misc у ядрі; настільні віртуальні машини мають надавати ці можливості. Їх перевіряє pib doctor. Повне створення образів перевірено на Linux x86/ARM та локально на Apple Silicon/Colima. Тести інсталятора Windows не підтверджують повне створення образів у Windows.

Для ручного використання Docker без sima-cli завантажте опублікований образ і витягніть засіб запуску (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 він реєструється в ядрі Linux хоста Docker лише за відсутності працездатного обробника ARM64. Наявний справний обробник зберігається; на ARM64 реєстрація не потрібна. Після перезавантаження хоста Docker налаштування повторюється автоматично. Пакети на хост не встановлюються.

Команди​

Для стиснення образів PIB використовує pigz на доступних ядрах процесора. Результати сумісні з gzip; підписування й перевірка охоплюють фактичні стиснені дані.

Щоб повторно використовувати завантаження Debian-пакетів, перед збиранням задайте каталог кешу на хості:

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

Кешуються лише байти пакетів. Кожне початкове збирання завантажує й автентифікує поточні метадані репозиторіїв, а потім перевіряє SHA256 і розмір кешованих пакетів. Пошкоджені дані видаляються та завантажуються знову. Коренева файлова система, встановлення пакетів, хуки, підписування й перевірка виконуються заново. Кеш може містити ваші власні пакети; зберігайте його у своєму каталозі користувача.

КомандаПризначення
pib doctorПеревірити інструменти, місце, loop-пристрої, 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]Перевірити підпис і дані; визначити типові CA й суміжний маніфест
pib diff --against MANIFESTПоказати відмінності пакетів від попереднього збирання
pib clean [--yes]Переглянути/видалити залишкові loop-пристрої й групи томів

Усі команди виконуються в контейнері. Засіб запуску хоста керує лише 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

Хуки виконуються послідовно через sh після хуків SiMa та встановлення пакетів. $1 — каталог rootfs. Записуйте файли всередині нього або використовуйте systemctl --root="$1"; chroot "$1" запускає програму ARM64 в образі. Шляхи хуків мають бути відносними до проєкту та містити лише літери, цифри й _ . / + -.

Видалення пакета, потрібного іншому пакету, спричиняє помилку залежностей APT. Зберігайте пакети, потрібні хукам плати, зокрема swupdate та kea для palette. Перехід із palette на minimal змінює також розміри образів і типові пакети.

Власні Debian-пакети потребують відокремлених підписів, які приймає debs.key у image.yaml. 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 ядра та виробничо підписаних завантажувальних пакетів для постачання. Цей варіант не кваліфікований тестом мінімального образу цього порту. Збирання --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.

Для шифрування даних виконайте 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 на хості. Паролі вводяться за запитом, зберігаються лише хеші. SSH-доступ root залишається лише за ключем. Або розмістіть дозволений відкритий ключ у overlay/root/.ssh/authorized_keys: права каталогу 700, файла 600. На першому завантаженні кожна плата створює власні ключі хоста SSH.

Встановлення SWU​

Ці команди змінюють плату. Явно виберіть підписаний .swu та потрібну плату. На платі має працювати сумісний образ SiMa/PIB eLxr із доступом SSH як sima та 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 не є сирим образом диска.

Поточна схема PIB має GPT boot.A, boot.B і розділ LVM із rootfs A/B та даними. Не застосовуйте до неї старі інструкції U-Boot для сирих розділів. Точна геометрія визначається шаблонами плати відповідного випуску.

Новий випуск платформи​

Завантажте потрібний образ збирача й витягніть його засіб запуску, потім створіть новий проєкт через pib init. Збережіть початковий CA та ключі підписування. Перенесіть накладання/хуки та об’єднайте власні налаштування з новим image.yaml, залишивши нові значення release та version.

Копіюйте лише Debian-пакети, сумісні з новою платформою. Оновіть власні сценарії/описи оновлення відповідно до нових типових файлів. Не копіюйте весь старий configs/ поверх нового. Для підтримки старого випуску збережіть старий проєкт і зафіксоване посилання на засіб запуску/образ.