Creazione di immagini Fedora IoT personalizzate con image-builder

image-builder è uno strumento da riga di comando per creare immagini di sistemi operativi personalizzate per Fedora, CentOS e RHEL. Questa guida spiega come utilizzare image-builder per creare immagini Fedora IoT personalizzate con le proprie selezioni di pacchetti, configurazioni utente e impostazioni.

Per le immagini Fedora IoT precompilate senza personalizzazioni, vedere Ottenere immagini.

Installazione di image-builder

Per installare image-builder su Fedora:

$ sudo dnf install image-builder ostree

Tipi di immagini Fedora IoT disponibili

image-builder supporta diversi tipi di immagini specifiche per IoT per le architetture x86_64 e aarch64:

  • iot-commit - Archivio tar OSTree (la base per le immagini personalizzate)

  • iot-installer -ISO del programma di installazione Anaconda per installazione interattiva

  • iot-simplified-installer - Programma di installazione automatico (zero-touch) tramite FDO o Ignition

  • iot-raw-xz – Immagine disco raw compressa per dispositivi fisici (ad es. Raspberry Pi)

  • iot-qcow2 – Immagine disco QCOW2 per macchine virtuali

  • iot-container – Container OCI con commit OSTree

  • iot-bootable-container – Immagine container avviabile

Per elencare tutti i tipi di immagini IoT disponibili:

$ image-builder list | grep iot

Creazione di immagini Fedora IoT personalizzate

Il flusso di lavoro tipico per creare immagini Fedora IoT personalizzate è:

  1. Creare un blueprint che descriva le personalizzazioni

  2. Creare un commit OSTree personalizzato con le proprie modifiche

  3. Servire localmente il commit OSTree

  4. Creare supporti di installazione o immagini disco dal commit personalizzato

Passaggio 1: Creare un Blueprint

I Blueprint sono file TOML che descrivono le personalizzazioni per la tua immagine. Permettono di:

  • Aggiungere o rimuovere pacchetti

  • Configurare utenti e gruppi

  • Configurare le chiavi SSH

  • Configurare le impostazioni di sistema

Creare un file blueprint (esempio: iot-custom.toml):

nome = "iot-custom"
Descrizione = "Immagine Fedora IoT personalizzata"
Versione= "0.0.1"

[[pacchetti]]
nome ="vim-enhanced"

[[pacchetti]]
nome = "htop"

[[pacchetti]]
nome = "tmux"

[[personalizzazioni.utente]]
nome = "admin"
descrizione = "Admin User"
password = "$6$rounds=4096$saltsalt$encrypted_password_hash"
gruppo = ["wheel"]

[[Personalizzazioni.chiavessh]]
utente = "admin"
chiave = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample admin@workstation"
Generare password cifrate con openssl passwd -6 (richiederà l’inserimento della password in modo interattivo)

Passaggio 2: Creare un commit OSTree personalizzato

Creare un tarball del commit OSTree con le tue personalizzazioni. Utilizza il modello ufficiale per la denominazione del ref (fedora/stable, fedora/devel, or fedora/rawhide):

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./iot-commit-output

# Nota per aarch64 usare `fedora/stable/aarch64/iot`

Questo crea un tarball contenente il tuo commit OSTree personalizzato.

Passaggio 3: Configurare un repository OSTree locale

Estrarre il tarball del commit e servire il repository OSTree:

$ tar -xf ./iot-commit-output/*.tar
$ mv repo ostree-repo
$ cd ostree-repo
$ python3 -m http.server 8000

Il tarball contiene una directory repo/ con l’intero repository OSTree. Per eseguire il server HTTP in background, aggiungi & alla fine:

$ python3 -m http.server 8000 &

Il tuo repository OSTree personalizzato è ora disponibile su http://localhost:8000

Per verificare che il repository sia stato configurato correttamente:

$ ostree --repo=./ostree-repo refs
$ curl http://localhost:8000/refs/heads/fedora/stable/x86_64/iot

Creazione di immagini dal tuo OSTree personalizzato

Con il tuo commit OSTree personalizzato servito localmente, puoi ora creare diversi tipi di immagini.

Creazione di un ISO di installazione

Creare un ISO di installazione Anaconda che installerà la tua Fedora IoT personalizzata:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Creazione di un installer semplificato

L’installer semplificato offre il provisioning “zero-touch” utilizzando FDO o Ignition:

$ sudo image-builder build iot-simplified-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

See Avvio del Provisioner Semplificato per maggiori dettagli.

Creazione di immagini disco Raw

Per computer a scheda singola come il Raspberry Pi, creare un’immagine disco raw compressa:

$ sudo image-builder build iot-raw-xz \
  --distro fedora-43 \
  --arch aarch64 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/aarch64/iot \
  --output-dir ./images

Queste immagini possono essere scritte direttamente su schede SD o altri supporti di memoria.

Creazione di immagini QCOW2 per macchine virtuali

Per i test in macchine virtuali:

$ sudo image-builder build iot-qcow2 \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Creazione di immagini container

Creare un container OCI con il tuo commit OSTree:

$ sudo image-builder build iot-container \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Creare un’immagine container avviabile per workflow moderni container-native:

$ sudo image-builder build iot-bootable-container \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Vedi Fedora IoT Bootc Per ulteriori informazioni sulle immagini container avviabili.

Servire il tuo repository OSTree ad altre macchine

Per rendere il tuo repository OSTree personalizzato disponibile ad altre macchine sulla tua rete:

$ cd ostree-repo
$ python3 -m http.server 8000 --bind 0.0.0.0 &
Il & esegue il server in background. Per fermarlo successivamente, usa pkill -f "http.server 8000"

Poi usa l’indirizzo IP della tua macchina quando costruisci le immagini su altri sistemi:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
  --ostree-url http://192.168.1.100:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Opzioni avanzate

Aggiungere Repository Extra

Aggiungi repository di pacchetti aggiuntivi durante la costruzione del commit OSTree (non inclusi nell’immagine finale):

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --extra-repo "https://example.com/repo/fedora/43/x86_64" \
  --output-dir ./iot-commit-output
I repository aggiuntivi non sono verificati tramite GPG e vengono utilizzati solo durante la costruzione del commit.

Personalizzare i nomi di output

Personalizza il nome del file di output per le tue immagini:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-name my-custom-installer \
  --output-dir ./images

Output dettagliato per il debug

Abilita la modalità verbosa per vedere informazioni dettagliate sulla costruzione:

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --verbose \
  --output-dir ./iot-commit-output

Esportare gli artefatti di costruzione

Esporta il manifest di OSBuild e il log di costruzione per la risoluzione dei problemi:

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --with-manifest \
  --with-buildlog \
  --output-dir ./iot-commit-output

Descrizione dei tipi di immagine

Per vedere informazioni dettagliate su qualsiasi tipo di immagine IoT:

$ image-builder describe iot-installer --distro fedora-43
$ image-builder describe iot-qcow2 --distro fedora-43 --arch aarch64
$ image-builder describe iot-simplified-installer --distro fedora-43

Questo mostra i pacchetti, le pipeline e le opzioni di configurazione per ogni tipo di immagine.

Best Practices

  1. Testa prima con QCOW2 – Crea e testa le immagini iot-qcow2 su macchine virtuali prima di creare i media di installazione.

  2. Usa il controllo versione per i Blueprint – Conserva i file blueprint in git per tracciare le personalizzazioni.

  3. Minimizza l’aggiunta di pacchetti – Aggiungi solo i pacchetti essenziali; usa i container per le applicazioni.

  4. Usa password cifrate – Non utilizzare mai password in testo chiaro nei blueprint.

  5. Abilita la modalità verbosa per il debug – Usa --verbose quando fai il debug di problemi di costruzione.

Risoluzione dei problemi

La costruzione fallisce con errori OSTree

Verifica che il tuo repository OSTree locale sia configurato correttamente e che il ref esista:

$ ostree --repo=./ostree-repo refs
$ ostree --repo=./ostree-repo show fedora/stable/x86_64/iot

Assicurati che il tuo server HTTP sia in esecuzione e accessibile:

$ curl http://localhost:8000/config
$ curl http://localhost:8000/refs/heads/fedora/stable/x86_64/iot

Errori di permesso negato

La maggior parte delle operazioni di image-builder richiede privilegi di root:

$ sudo image-builder build iot-installer ...

Spazio su disco insufficiente

La creazione delle immagini richiede un notevole spazio su disco. Assicurati di avere almeno 10 GB di spazio libero in:

  • /var/cache/image-builder/ (build cache)

  • Directory di output

Pulisci la cache se necessario:

$ sudo rm -rf /var/cache/image-builder/store/*

Risorse aggiuntive

Want to help? Learn how to contribute to Fedora Docs ›