Scrivere IronFlockOS su un’unità

ironflock os flash prepara l’unità da cui si avvia un nuovo dispositivo. Scrive sull’unità IronFlockOS e il file di configurazione del dispositivo (.flock), e il dispositivo si registra al primo boot: si connette a IronFlock come il dispositivo di quel file .flock. Puoi preparare:

• una chiavetta USB, una scheda SD o un disco esterno da cui si avvia il dispositivo,
• una chiavetta di installazione che installa IronFlockOS sul disco interno di un PC,
• un file immagine disco da cui si avvia una macchina virtuale.

FlockFlasher è l’app desktop per lo stesso compito. Per ottenere il file .flock di un dispositivo, vedi Connettere i Dispositivi.

Esecuzione tipica

# 1. Inserisci la chiavetta o la scheda SD, poi elenca le unità su cui si può scrivere
ironflock os drives
# 2. Facoltativo: elenca le immagini offerte dal catalogo
ironflock os images
# 3. Scrivi IronFlockOS e il file .flock del dispositivo sull'unità
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash mostra il suo piano e chiede conferma prima di cancellare l’unità. Al termine, inserisci l’unità nel dispositivo e avvia il dispositivo da essa.

ironflock os images

Elenca le immagini IronFlockOS che si possono scrivere su un’unità. Per impostazione predefinita elenca le immagini della release del canale di produzione.

ironflock os images [flags]

Funziona su Linux e macOS. Non richiede root. Non chiede nulla.

Flag

I flag comuni a ogni comando sono descritti in Flag, output e codici di uscita.

Cosa fa

L’elenco viene dal catalogo firmato di IronFlockOS sul server di download, <download base>/ironflockos/manifest.json. ironflock usa il catalogo solo quando la sua firma Ed25519 risulta valida con la chiave del catalogo integrata in ironflock. Anche FlockFlasher e l’agente del dispositivo accettano solo questa chiave. Nessun flag e nessuna variabile d’ambiente disattiva questo controllo. La base di download è il cloud IronFlock, a meno che tu non ne indichi un’altra, vedi Base di download.

L’ultimo catalogo verificato viene conservato in una cartella della cache, una copia per ogni base di download:

Quando il server di download non è raggiungibile, la copia conservata ne fa le veci, con una nota su stderr. Un catalogo della stessa base di download più vecchio della copia conservata viene rifiutato.

Un’immagine prende il nome dal suo target hardware, dalla sua variante e dal suo kernel: ironflockos-<target>-<variant>, con -rt per il kernel real-time. ironflockos-amd64-efi-base-rt è il sistema base con il kernel real-time per PC x86-64 con UEFI. I target sono:

• amd64-efi — PC x86-64 con UEFI
• arm64-efi — macchina ARM64 con UEFI
• rpi-arm64 — Raspberry Pi 4, 400 e CM4; Raspberry Pi 5 e CM5

Le varianti sono base, nvidia e installer. L’immagine installer crea una chiavetta USB che installa una delle immagini che contiene sul disco della macchina che si avvia da essa. Un’immagine di una variante, di un kernel o di un’architettura che questo ironflock non conosce (di una release più recente) viene tralasciata, con una nota su stderr.

Esempi

# Le immagini dell'attuale release di produzione
ironflock os images
# Solo le immagini per Raspberry Pi
ironflock os images --target rpi-arm64
# Le immagini del canale di test, come JSON
ironflock os images --channel test --json

Risultato

IMAGE                            VERSION  SIZE      HARDWARE
ironflockos-amd64-efi-base       0.13.0   638.1 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-base-rt    0.13.0   650.4 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-nvidia     0.13.0   1.0 GB    x86-64 PC with UEFI
ironflockos-amd64-efi-installer  0.13.0   2.5 GB    x86-64 PC with UEFI, installer stick for base, base-rt, nvidia
ironflockos-arm64-efi-base       0.13.0   582.4 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-base-rt    0.13.0   594.1 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-installer  0.13.0   1.5 GB    ARM64 machine with UEFI, installer stick for base, base-rt
ironflockos-rpi-arm64-base       0.13.0   639.4 MB  Raspberry Pi 4, 400 and CM4; Raspberry Pi 5 and CM5

Con --json (qui con --target rpi-arm64):

{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"channels":{"production":"0.13.0","test":"0.13.0"},"images":[{"image_id":"ironflockos-rpi-arm64-base","version":"0.13.0","channels":["production","test"],"target":"rpi-arm64","variant":"base","kernel":"std","architecture":"arm64","boards":["raspberrypi4","raspberrypi5"],"hardware":["Raspberry Pi 4, 400 and CM4","Raspberry Pi 5 and CM5"],"file":"ironflockos-rpi-arm64-base-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-rpi-arm64-base-0.13.0.img.gz","size":639408901,"sha256":"9abd17f2098dfa236d440005222d0a6b583546ea9768e5eca8807c4e24ec88db"}]}

issued_at e key_id descrivono il catalogo, channels indica la release di ogni canale, e from_cache è true quando il server di download non ha risposto. Ogni immagine ha il suo file con url, size e sha256. boards sono i modelli di scheda indicati da un file .flock (board.model), e hardware sono i loro nomi. Un’immagine installer ha anche payloads, gli id delle immagini che contiene.

Quando fallisce

• Codice di uscita 2 — --channel e --version insieme, una versione non valida, oppure un canale, una release, un target, una variante o un kernel che il catalogo non ha. L’errore indica ciò che il catalogo contiene.
• Codice di uscita 1 — il catalogo non supera la verifica, è più grande di 64 KiB, non è in un formato che questo ironflock sa leggere, o è più vecchio della copia conservata; oppure non può essere scaricato e non c’è alcuna copia conservata.

ironflock os drives

Elenca le unità di questa macchina su cui si può scrivere un’immagine IronFlockOS: chiavette USB, schede SD, dischi esterni. Non scrive, non smonta e non apre alcuna unità.

ironflock os drives [flags]

Funziona su Linux e macOS. Non richiede root. Non chiede nulla. Su Linux esegue lsblk (da util-linux) e legge /proc e /sys. Su macOS esegue diskutil list, diskutil info e hdiutil info.

Flag

I flag comuni a ogni comando sono descritti in Flag, output e codici di uscita.

Quali unità vengono rifiutate

os flash rifiuta le unità che os drives rifiuta, per gli stessi motivi. Un’unità viene rifiutata quando (il motivo mostrato è il primo che si applica):

1. è una partizione, come /dev/sdb1. Il rifiuto indica il suo disco: un’immagine va sull’intero disco.
2. non è un disco: un’unità ottica, un disco in memoria (zram), un volume costruito su altre unità (LVM, dm-crypt, RAID, device-mapper; su macOS un container APFS, un set AppleRAID o un altro disco sintetizzato), o un tipo di dispositivo che il comando non conosce (nbd, mtdblock).
3. contiene parte del sistema in esecuzione: /, /boot, /efi, /usr, /var, /etc o un mount sotto uno di questi (la partizione EFI in /boot/efi, i dati di Docker in /var/lib/docker), /home, /opt, /srv, /data, lo swap, o il supporto di un sistema live. Questo vale in qualunque modo il sistema si trovi sull’unità: in una partizione, tramite LVM, dm-crypt, RAID o device-mapper, in un file system btrfs distribuito su più unità, in un pool ZFS, in un overlay, o in un file letto da un loop device. Su macOS: / e i volumi sotto /System, attraverso i loro container APFS fino al disco che li contiene.
4. è in uso: da LVM, dm-crypt, RAID o device-mapper, da un pool ZFS con un dataset montato, o da un loop device che legge un file su di essa. Su macOS anche da un container APFS su di essa, da un set AppleRAID, da un’immagine disco il cui file si trova su di essa, oppure da Core Storage, AppleRAID o un container APFS non collegato. macOS rilascia una chiavetta con un container APFS solo quando la chiavetta viene cancellata, quindi il motivo indica il comando che la cancella, ad esempio diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6 (oppure Inizializza in Utility Disco).
5. è un disco interno della macchina: un disco SATA o NVMe, l’eMMC di una scheda. Un’unità è interna a meno che non sia collegata tramite USB o un altro bus i cui dispositivi si possono scollegare. Un lettore di schede integrato è interno, ma la sua scheda SD è un supporto rimovibile e viene proposta, anche su un Mac. Su macOS un disco che non dice dove si trova conta come interno. os flash --allow-internal scrive un disco interno indicato da --drive, quando nessun altro motivo lo rifiuta.
6. potrebbe contenere parte del sistema in esecuzione: quando una parte del sistema in esecuzione non può essere ricondotta a un’unità, ogni unità viene rifiutata. È il caso di un container, il cui sistema si trova sul suo host, e su macOS di un sistema su un volume che non arriva a nessun disco fisico, come Core Storage.
7. è di sola lettura, come una scheda SD bloccata.
8. non ha un supporto, come un lettore di schede senza scheda.

Un’unità con file system montati viene proposta; mounted li elenca, e os flash li smonta prima di scrivere. I loop device e, su macOS, le immagini disco collegate non vengono elencati, ma os flash scrive quello indicato da --drive.

Su un dispositivo che esegue IronFlockOS, il comando dà un avviso su stderr e in warnings: ogni immagine IronFlockOS di un target ha gli stessi UUID di partizione, quindi finché è collegata una seconda unità IronFlockOS, il sistema in esecuzione non riesce a distinguere le proprie partizioni da quelle dell’unità.

Esempi

# Le unità su cui si può scrivere
ironflock os drives
# Tutte le unità, con il motivo di ogni rifiuto
ironflock os drives --all
# Le unità come JSON
ironflock os drives --json

Risultato

Su Linux:

DEVICE        SIZE     BUS  MODEL
/dev/sdb      15.9 GB  usb  SanDisk Ultra
/dev/mmcblk0  31.9 GB  mmc  SD32G

Con --all:

DEVICE        SIZE     BUS   MODEL                    WRITABLE
/dev/sda      2.0 TB   sata  WDC WD20EZBX-00AYRA0     no: is an internal disk of this machine
/dev/sdb      15.9 GB  usb   SanDisk Ultra            yes
/dev/mmcblk0  31.9 GB  mmc   SD32G                    yes
/dev/nvme0n1  1.0 TB   nvme  Samsung SSD 980 PRO 1TB  no: holds / of the running system

Su un Mac, con --all:

DEVICE      SIZE      BUS             MODEL                 WRITABLE
/dev/disk0  500.3 GB  Apple Fabric    APPLE SSD AP0512R     no: holds / of the running system
/dev/disk1  524.3 MB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk2  5.4 GB    Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk3  494.4 GB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk5  15.9 GB   Secure Digital  Built In SDXC Reader  yes

Con --json (abbreviato):

{"drives":[{"device":"/dev/sdb","kind":"disk","size":15931539456,"bus":"usb","removable":true,"internal":false,"read_only":false,"vendor":"SanDisk","model":"Ultra","serial":"4C530001230812115352","mounted":[{"device":"/dev/sdb1","mountpoint":"/media/anna/STICK"}],"system":[],"maybe_system":[],"holders":[],"writable":true},{"device":"/dev/mmcblk0",...}],"warnings":[]}

Quando non c’è alcuna unità su cui scrivere, il testo lo dice, drives è vuoto e il codice di uscita è 0.

Quando fallisce

• Codice di uscita 3 — su Linux, lsblk non è installato; oppure il comando viene eseguito su un sistema diverso da Linux o macOS.

ironflock os flash

Scrive IronFlockOS su un’unità (una chiavetta USB, una scheda SD, un disco esterno) e mette il file .flock del dispositivo nella partizione IRONFLOCKOS dell’unità, la partizione FAT32 con quel nome che ogni unità IronFlockOS possiede. Il dispositivo si registra con quel file al primo boot. Con --output, scrive invece lo stesso contenuto in un file immagine disco per una macchina virtuale.

Avviso: Tutto ciò che si trova sull’unità viene cancellato. Controlla il nome dell’unità con ironflock os drives prima di scrivere. os flash non sceglie mai un’unità da solo.

ironflock os flash -c <device.flock> (-d <drive> | --output <file>) [flags]

Senza root, l’errore indica la riga di comando da digitare, con sudo davanti. Su macOS un utente che può scrivere sul dispositivo raw dell’unità non ha bisogno di root: l’utente che ha collegato un’immagine disco, o un utente a cui il proprietario della macchina ha assegnato l’unità, ad esempio con sudo chown <user> /dev/disk4 /dev/rdisk4. Con --output, il comando non richiede root. Vedi anche Privilegi di root.

Flag

I flag comuni a ogni comando sono descritti in Flag, output e codici di uscita.

Cosa fa

1. Controlla l’unità. Risolve --drive e la rifiuta per i motivi indicati da os drives, prima di leggere, scaricare o chiedere qualsiasi cosa. Senza --drive (e senza --output), indica le unità su cui può scrivere e termina con il codice di uscita 2.
2. Legge il file .flock. Deve essere un file chiamato *.flock di al massimo 5 MiB, un oggetto JSON con un secret e un device_key, i cui name e serial_number siano nomi semplici.
3. Sceglie l’immagine dal catalogo firmato, che scarica e verifica come fa os images. Prende l’immagine indicata da --image, altrimenti l’immagine predefinita (variante base, kernel standard) dell’hardware indicato dal file .flock: il suo board.model, altrimenti la sua architecture quando il catalogo ha un solo hardware per essa. Con --installer, prende la chiavetta di installazione di quell’hardware che contiene l’immagine.
4. Mostra il piano su stderr: l’immagine, da dove proviene il suo file, il file .flock (per nome), il WiFi, l’unità e i file system dell’unità che smonta. Poi chiede. «No» è preselezionato, quindi Invio da solo non cancella nulla.
5. Ottiene il file immagine: il file di --image-file, altrimenti la copia nella cache, altrimenti un download nella cache, ripreso dal punto in cui si era fermato un download precedente. Come root, la cache è /var/cache/ironflock/images su Linux e /var/root/Library/Caches/ironflock/images su macOS. Il download va in un file .part. Ogni file viene scritto solo quando la sua dimensione e il suo SHA-256 sono quelli del catalogo. Un tentativo di download che per un minuto non riceve alcun byte termina, e il download rinuncia dopo tre tentativi di questo tipo consecutivi.
6. Controlla di nuovo l’unità. Deve essere l’unità mostrata nel piano e non essere rifiutata nemmeno ora: lo stesso dispositivo, la stessa dimensione, lo stesso numero di serie e lo stesso supporto. Su Linux questo comprende il produttore, il modello, il bus e ogni partizione con il suo file system, etichetta, UUID e dimensione. Su macOS, che non indica un numero di serie, sono il modello, il bus, la posizione nell’albero dei dispositivi e le partizioni con i loro UUID. Una chiavetta estratta dopo il piano lascia il suo nome alla prossima unità inserita; un’unità di questo tipo non viene scritta, e non viene smontato nulla. Poi il comando smonta i file system elencati nel piano, e solo quelli, e apre l’unità in scrittura in modo esclusivo. Su macOS scrive tramite il dispositivo raw (/dev/rdisk4), che un secondo os flash non può aprire contemporaneamente.
7. Scrive l’immagine, poi rilegge l’unità e la confronta.
8. Scrive il file .flock nella cartella principale della partizione IRONFLOCKOS, senza montarla. Una chiavetta di installazione riceve anche installer.conf. Con --wifi-ssid, la copia sull’unità indica quella rete; il file .flock stesso non viene modificato.
9. Su macOS, espelle l’unità (diskutil eject), così puoi estrarla. Quando l’espulsione fallisce, l’unità è comunque scritta: il comando dà un avviso, e tu espelli l’unità nel Finder prima di estrarla.

Come root, il comando usa una cartella della cache solo quando è una cartella e non un link, appartiene a root e nessun altro può scriverci. Crea con modo 0700 una cartella mancante; davanti a qualsiasi altra si ferma, prima di leggere, eliminare o scaricare qualcosa al suo interno. Prima di scaricare un’immagine del catalogo, elimina i file immagine nella cache che il catalogo non elenca più, e i loro download parziali.

Un --image per un hardware diverso da quello indicato dal file .flock viene scritto dopo un avviso nel piano: il dispositivo non eseguirebbe le sue app. Su un dispositivo che esegue IronFlockOS, il piano dà un avviso come fa os drives. Con --allow-internal, il piano avvisa che l’unità è un disco interno.

--yes risponde sì alla domanda. Senza terminale (una pipe, uno script) e senza --yes, il comando non chiede e termina con il codice di uscita 4. Nemmeno --json chiede nulla, quindi richiede --yes per scrivere un’unità. Con --json, il piano non viene stampato: stderr riceve solo gli eventi di avanzamento, e gli avvisi sono nel risultato. Vedi Domande e conferma e Output e JSON.

WiFi

Il dispositivo si collega alla rete WiFi indicata dal suo file .flock. --wifi-ssid gli assegna un’altra rete. IronFlockOS si collega solo a reti WiFi con passphrase, quindi --wifi-ssid e --wifi-password-file vanno sempre insieme. La passphrase viene da un file o da una pipe, mai dalla riga di comando, dove ps e la cronologia della shell la mostrerebbero. Il comando non la stampa da nessuna parte. La copia del file .flock sull’unità indica la rete in wlanssid e password.

Nota: Quando la passphrase arriva tramite /dev/stdin, stdin non è un terminale, quindi il comando non può chiedere. Aggiungi --yes.

Chiavetta di installazione

Con --installer, l’unità diventa una chiavetta di installazione per un PC con UEFI (amd64-efi, arm64-efi); ironflock os images --variant installer elenca le immagini installer. La chiavetta contiene diverse immagini del suo hardware; installer.conf sulla chiavetta indica quella che installa (payload, l’immagine scelta come al passo 3) e contiene i flag --installer-* che hai indicato. Quando il PC si avvia dalla chiavetta, l’installer:

1. sceglie il disco in base a --installer-disk: il disco più grande (predefinito), il disco /dev/<name>, o il disco con l’id by-id:<id>. Scrive un disco USB solo con --installer-allow-usb yes.
2. chiede conferma sulla console del PC prima di scrivere, a meno di --installer-confirm no.
3. scrive l’immagine e il file .flock del dispositivo su quel disco.
4. spegne il PC (predefinito), oppure lo riavvia con --installer-after reboot.

Estrai la chiavetta e avvia il PC dal suo disco interno. Il dispositivo si registra al primo boot.

Avviso: Una chiavetta scritta con --installer-confirm no cancella il disco di ogni PC che si avvia da essa, senza chiedere. Etichetta una chiavetta di questo tipo e tienila lontana da altre macchine.

Per sostituire il Linux di una macchina in funzione senza chiavetta, vedi Sostituire Linux con IronFlockOS.

Un file immagine scaricato

--image-file scrive un file immagine che hai scaricato in precedenza, ad esempio su una macchina che non può scaricare i file immagine del catalogo. Prendi l’indirizzo del file dall’url di os images --json. Il file viene scritto solo quando ha la dimensione e lo SHA-256 che il catalogo indica per l’immagine.

Il comando ha comunque bisogno del catalogo firmato per controllare il file. Scarica il catalogo oppure, quando il server di download non è raggiungibile, usa la copia conservata l’ultima volta che un catalogo della stessa base di download è stato verificato. Quella copia è per utente: come root, è la copia di root. Funziona anche un server proprio: con un’altra base di download (--download-base o IRONFLOCK_DL_BASE), il comando scarica il catalogo da <download base>/ironflockos/manifest.json e il file immagine da <download base>/ironflockos/<version>/<file>.

Nota: Il file viene letto ancora una volta durante la scrittura, e il suo SHA-256 è di nuovo noto solo dopo la scrittura. Tieni il file dove nessun altro utente può modificarlo.

Un file immagine per una macchina virtuale

--output <file> scrive l’immagine e i file del dispositivo in un file normale invece che su un’unità: un’immagine disco raw da cui una macchina virtuale si avvia come dal suo disco. L’immagine, i suoi controlli e i file in IRONFLOCKOS sono gli stessi di un’unità. Non viene cercata, smontata o aperta alcuna unità, quindi il comando non richiede root. --image, --image-file, --installer con i suoi flag e --wifi-ssid funzionano come con un’unità.

• Dimensione — Il piano indica il file e la sua dimensione: la dimensione dell’immagine decompressa. Quando l’immagine deve ancora essere scaricata, quella riga segue il download.
• Domanda — Un file nuovo non cancella nulla, e il comando non chiede. Un file esistente viene sostituito: il piano lo dice, e il comando prima chiede.
• Prima con un altro nome — L’immagine va in un nuovo file nella stessa cartella, <file>.<number>.part. Riceve il nome <file> solo quando contiene l’intera immagine, è stato riletto e ha i file del dispositivo nella sua partizione IRONFLOCKOS. Una scrittura che fallisce o viene interrotta rimuove il file .part, e con quel nome non c’è nulla, oppure c’è il file di prima, invariato. Un kill -9 o un’interruzione di corrente possono lasciare il file .part.
• Privato — Il file contiene il segreto del dispositivo, come il file .flock. Riceve il modo 0600, anche quando sostituisce un file con un modo più permissivo.
• File sparso — Dove l’immagine ha un intero blocco di zeri (blocchi di 4 MiB), il file riceve un buco su un file system che supporta i buchi. Si legge allo stesso modo e occupa meno spazio.

# Scrivi un file immagine disco per una macchina virtuale, senza root
ironflock os flash -c device.flock --output device.img

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Output:       device.img, a new file: the image, unpacked; its size is known once the image is downloaded
(the progress of downloading, checking)
Unpacked, the image has 4.6 GB: the size of device.img.
(the progress of writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is in device.img and read back, with device.flock in its IRONFLOCKOS partition.
Grow the file to the size of the virtual machine's disk before the machine starts from it (truncate -s 20G device.img): on its first boot IronFlockOS makes slot B and /data in that space, and the device enrolls as kitchen-pc.

L’immagine contiene la partizione IRONFLOCKOS e il primo dei due slot di sistema che IronFlockOS aggiorna a turno (slot A). Al primo boot, IronFlockOS crea lo slot B, grande quanto lo slot A, e la partizione dati /data sul resto del disco. Ingrandisci il file prima che la macchina virtuale si avvii da esso per la prima volta: ad almeno 10 GiB per base e 18 GiB per nvidia. Lo spazio che il file guadagna è fatto di zeri, che il file system conserva come buco. Un hypervisor che accetta dischi raw usa il file così com’è. Per un altro formato, converti il file ingrandito, ad esempio con qemu-img convert -f raw -O qcow2 device.img device.qcow2.

Le immagini di amd64-efi e arm64-efi si avviano in QEMU; l’immagine del Raspberry Pi (rpi-arm64) no. Per amd64-efi su Linux con KVM e il firmware UEFI del pacchetto ovmf (Debian, Ubuntu):

# Ingrandisci il file, copia le variabili del firmware e avvia la macchina
truncate -s 20G device.img
cp /usr/share/OVMF/OVMF_VARS_4M.fd device-vars.fd
qemu-system-x86_64 -machine q35 -accel kvm -cpu host -m 2048 -smp 2 \
  -drive if=pflash,format=raw,unit=0,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,unit=1,file=device-vars.fd \
  -drive file=device.img,format=raw,if=virtio \
  -netdev user,id=net0 -device virtio-net-pci,netdev=net0 \
  -device i6300esb \
  -nographic

• -nographic porta la prima porta seriale sul terminale, dove scrivono GRUB e il kernel. Ctrl-A X chiude QEMU.
• -device i6300esb è un watchdog, tramite il quale IronFlockOS riavvia una macchina bloccata.
• -netdev user dà alla macchina la rete dell’host, tramite la quale il dispositivo raggiunge IronFlock.
• Senza KVM (nessun /dev/kvm, o un host di un’altra architettura), togli -accel kvm e usa -cpu max. QEMU allora emula la macchina, il che è molto più lento.

arm64-efi si avvia con qemu-system-aarch64 -machine virt e il firmware del pacchetto qemu-efi-aarch64 (/usr/share/AAVMF/AAVMF_CODE.fd, e una copia di AAVMF_VARS.fd), senza il watchdog. Su un Mac con Apple silicon, QEMU di Homebrew lo avvia con -accel hvf -cpu host e il firmware /opt/homebrew/share/qemu/edk2-aarch64-code.fd, con una copia di edk2-arm-vars.fd.

Esempi

# Scrivi su una chiavetta USB l'immagine predefinita per l'hardware del file .flock
sudo ironflock os flash -c device.flock -d /dev/sdb
# Scrivi una chiavetta di installazione che installa l'immagine NVIDIA su un PC
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# Scrivi una scheda SD per un dispositivo che si collega alla rete WiFi «Workshop»
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Scrivi una chiavetta su un Mac
sudo ironflock os flash -c device.flock -d /dev/disk4

Risultato

Il piano e l’avanzamento vanno su stderr; le ultime righe sono il risultato. Su Linux:

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Drive:        /dev/sdb: SanDisk Ultra, 15.9 GB, usb, serial 4C530001230812115352
Everything on /dev/sdb is erased. Unmounted first: /media/anna/STICK.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is on /dev/sdb and read back, with device.flock in its IRONFLOCKOS partition.
Start the device from it: it enrolls as kitchen-pc on its first boot.

Su un Mac, prima senza root, poi con sudo:

$ ironflock os flash -c pi.flock -d /dev/disk5
Error: "ironflock os flash" must run as root (sudo) to write a drive: sudo ironflock os flash -c pi.flock -d /dev/disk5
$ sudo ironflock os flash -c pi.flock -d /dev/disk5 --yes
IronFlockOS catalog of 2026-11-10T16:41:54Z, signed with key 036ef3bd.
Image:        ironflockos-rpi-arm64-base 0.14.0, for Raspberry Pi 4, 400 and CM4
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.14.0/ironflockos-rpi-arm64-base-0.14.0.img.gz (640.1 MB), downloaded and checked against the catalog
Device file:  pi.flock, for the device pi-workshop
WiFi:         Office (from the .flock)
Drive:        /dev/disk5: Built In SDXC Reader, 15.9 GB, Secure Digital
Everything on /dev/disk5 is erased. Unmounted first: /Volumes/UNTITLED.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.14.0 (ironflockos-rpi-arm64-base) is on /dev/disk5 and read back, with pi.flock in its IRONFLOCKOS partition.
/dev/disk5 is ejected and can be taken out.
Start the device from it: it enrolls as pi-workshop on its first boot.

Con --json, qui per una chiavetta di installazione (--installer --installer-confirm no --yes --json):

{"action":"flashed","device":"kitchen-pc","device_file":"device.flock","hardware":"x86-64 PC with UEFI","image":{"image_id":"ironflockos-amd64-efi-installer","version":"0.13.0","file":"ironflockos-amd64-efi-installer-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-installer-0.13.0.img.gz","size":2512345678,"sha256":"..."},"installer":{"payload":"ironflockos-amd64-efi-base","disk":"largest","confirm":"no","after":"poweroff","allow_usb":"no"},"wifi":{"ssid":"Office","from":"flock"},"drive":{"device":"/dev/sdb","size":15931539456,"bus":"usb","model":"SanDisk Ultra","serial":"4C530001230812115352","internal":false},"source":"download","unmounted":["/media/anna/STICK"],"bytes":6442450944,"verified":true,"ejected":false,"files":["device.flock","installer.conf"],"catalog":{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"notes":[]},"warnings":[]}

Con --output, il risultato ha output al posto di drive, ad esempio "output":{"file":"/home/anna/device.img","replaced":true}.

Quando rifiuta

Codice di uscita 3, e non viene scritto nulla:

• L’unità è una di quelle che os drives rifiuta; l’errore indica il motivo, e --yes non cambia nulla. L’unica eccezione è un disco interno di questa macchina: --allow-internal lo scrive quando --drive lo indica, e l’errore indica il flag quando renderebbe l’unità scrivibile. Il flag non annulla nessun altro rifiuto e non risponde alla domanda.
• L’unità è cambiata tra il piano e la scrittura, o in quel momento viene rifiutata. L’errore dice cosa è cambiato.
• L’unità è in uso quando viene aperta: è montato un file system che il piano non elencava, un file system non si smonta, o un programma tiene occupata l’unità.
• Il comando non viene eseguito come root (o, su macOS, come un utente che può scrivere sul dispositivo raw dell’unità). L’errore indica la riga di comando con sudo.
• Con --output: il nome non è un file normale (un dispositivo, una cartella, una named pipe o qualsiasi link simbolico), o la sua cartella non esiste; questo viene rifiutato prima di leggere o scaricare qualsiasi cosa. Una cartella che non accetta nuovi file (nessun permesso, un file system di sola lettura) viene rifiutata dopo il piano e prima del download. Un file che ha preso quel nome mentre l’immagine veniva scritta, quando il piano indicava un file nuovo, non viene sostituito.

Codice di uscita 2, una riga di comando errata:

• Né --drive né --output, anche con --allow-internal. --output con --drive o con --allow-internal, senza un nome, o con -. Un --output che indica il file .flock di -c o il file di --image-file.
• Un flag --installer-* senza --installer, o con un valore che l’installer non accetta.
• --wifi-ssid senza --wifi-password-file, o viceversa.
• Un file .flock che non dice per quale hardware è; in tal caso è --image a scegliere l’immagine.
• Un’immagine che il catalogo non ha, una chiavetta di installazione che non contiene l’immagine, o un hardware senza chiavetta di installazione.
• Con --host: --image-file e --output, perché --host non copia il file immagine sull’altra macchina e non riporta indietro alcun file. Esegui il comando qui senza --host, oppure sulla macchina stessa. Il file .flock e il file della passphrase invece vengono trasferiti.

Codice di uscita 4: alla domanda è stato risposto no (Invio da solo o Esc), oppure non è stato possibile porla e --yes non era indicato.

Codice di uscita 1, il comando è fallito:

• Il file .flock o il file della passphrase non è valido, oppure il file immagine non è quello del catalogo.
• Il catalogo non può essere usato, per i motivi per cui fallisce os images.
• Il download, la scrittura o la rilettura falliscono. Una scrittura che fallisce dopo il suo primo blocco (un errore di I/O, un’unità più piccola dell’immagine) dice che ora l’unità contiene una parte dell’immagine, da cui non si avvia nulla: scrivila di nuovo.
• L’immagine è sull’unità ed è stata riletta, ma non è stato possibile scrivere il file .flock in IRONFLOCKOS. Senza di esso il dispositivo non si registra; lo stesso comando scrive di nuovo entrambi.
• Con --output: il file system è pieno, non è possibile inserire i file del dispositivo nell’immagine, oppure la voce del file .part è stata sostituita mentre l’immagine veniva scritta. Il nome resta allora com’era prima.

Codice di uscita 130: Ctrl-C mentre l’immagine viene scaricata, scritta o riletta. Un download interrotto non ha scritto nulla, e lo stesso comando lo riprende. Una scrittura o una rilettura si ferma al blocco successivo, e l’errore dice cosa contiene l’unità. Quando l’ultimo blocco è stato riletto, il comando completa i suoi ultimi brevi passi e termina con 0. Un secondo Ctrl-C termina subito il comando; con --output può restare il file .part.