Aggiornamento, rollback e reset

Questi comandi si occupano di un dispositivo che esegue IronFlockOS. os update installa una release, os rollback torna alla release che era in esecuzione prima, e os reset riporta il dispositivo allo stato di un dispositivo appena scritto.

Slot di root e partizione dati

Il disco di un dispositivo IronFlockOS contiene:

• Due slot di root, A e B — ciascuno contiene un sistema IronFlockOS completo. Uno è in esecuzione. L’altro contiene il sistema che era in esecuzione prima, o ancora nulla su un dispositivo appena scritto. RAUC, lo strumento di aggiornamento usato da IronFlockOS, scrive una release nello slot che non è in esecuzione e annota quale slot si avvierà la prossima volta.
• La partizione dati (/data) — le app e i loro dati, e l’agente del dispositivo con la sua copia del file di configurazione del dispositivo (.flock). Entrambi i sistemi la usano, quindi un aggiornamento o un rollback lascia le app e i loro dati come sono.
• La partizione IRONFLOCKOS (montata in /boot/efi) — una piccola partizione FAT. Il dispositivo si registra con un file .flock che vi trova al suo avvio, e os reset vi scrive la sua richiesta.

Un nuovo sistema deve dimostrare di funzionare: il dispositivo lo mantiene dopo che l’agente del dispositivo ha raggiunto IronFlock da esso e lo ha segnato come valido. Un sistema che non si avvia, o non arriva a quel punto, viene abbandonato al riavvio successivo a favore di quello che era in esecuzione prima. ironflock status mostra gli slot:

System:        IronFlockOS 0.13.0 (amd64-efi, base)
  Image:       ironflockos-amd64-efi-base (build 20261105T120000Z-g1a2b3c4)
  Slot A:      inactive, good
  Slot B:      booted, good, 0.13.0 installed 2026-11-05T14:00:00Z
  Next boot:   slot B

Dove vengono eseguiti i comandi

I tre comandi vengono eseguiti su un dispositivo che esegue IronFlockOS, richiedono root e chiedono conferma prima di agire. Su un altro sistema (macOS, un Linux che non è IronFlockOS, la chiavetta di installazione di IronFlockOS) terminano con il codice di uscita 3.

• Sul dispositivo — le release di IronFlockOS successive alla 0.15.0 portano con sé ironflock. Accedi al dispositivo ed esegui il comando con sudo.
• Da un altro computer — le release di IronFlockOS fino alla 0.15.0 non portano con sé ironflock. Esegui il comando da un computer Linux o macOS con --host, come utente SSH del dispositivo: l’account che il file .flock configura per il proprietario del progetto, operator negli esempi. --host copia ironflock sul dispositivo per l’esecuzione ed esegue lì il comando tramite sudo.

ironflock --host operator@kitchen-pc os update --reboot --yes

os update e os rollback vengono eseguiti su più dispositivi contemporaneamente (--host più volte, oppure --hosts) quando è indicato --yes. os reset viene eseguito su un dispositivo alla volta; su più dispositivi termina con il codice di uscita 2. I flag globali sono descritti in Flag, output e codici di uscita.

ironflock os update

Installa la release di IronFlockOS offerta dal canale del dispositivo nello slot di root che non è in esecuzione. Il nuovo sistema si avvia al prossimo riavvio, oppure subito con --reboot.

ironflock os update [flags]

Il canale del dispositivo è quello seguito dal suo agente del dispositivo, dall’environment del file .flock dell’agente: test sulla piattaforma di test di IronFlock e production negli altri casi. Quando il catalogo non ha il canale del dispositivo, è production. La base di download viene da --download-base, poi da IRONFLOCK_DL_BASE, poi dal server di aggiornamento (update_url) del file .flock dell’agente (su un dispositivo di un IronFlock Appliance, il mirror di download dell’Appliance, l’unico che un dispositivo di questo tipo può raggiungere), altrimenti è il cloud IronFlock.

Cosa fa, in questo ordine:

1. Legge il catalogo firmato di IronFlockOS e prende il bundle di aggiornamento dell’immagine del dispositivo nella release del canale (o di --version).
2. Dice quale release è in esecuzione in quale slot, quale release installa, in quale slot, cosa contiene ora quello slot, e la dimensione del download. Poi chiede.
3. Scarica il bundle in /var/cache/ironflockos, sulla partizione dati. Un download interrotto viene ripreso. Il file viene usato solo quando la sua dimensione e il suo SHA-256 sono quelli del catalogo.
4. Fa installare a RAUC il bundle nello slot che non è in esecuzione. RAUC verifica la firma del bundle, scrive lo slot e lo imposta come quello che si avvierà la prossima volta. Ciò che lo slot conteneva prima viene sovrascritto. Il bundle viene rimosso una volta installato.
5. Con --reboot, riavvia il dispositivo nel nuovo sistema.

Il sistema in esecuzione resta com’è fino al riavvio. Le app e i loro dati restano. Lo slot ora in esecuzione mantiene la sua release, e il dispositivo vi torna quando la nuova release non si avvia o non raggiunge IronFlock.

Non viene installato nulla, e il codice di uscita è 0, quando il dispositivo esegue già la release, e quando la release è già installata nell’altro slot e attende il riavvio. Nel secondo caso, --reboot chiede e riavvia il dispositivo.

# Installa la release del canale del dispositivo; si avvia al prossimo riavvio
sudo ironflock os update
# Installala e riavvia nel nuovo sistema, senza domande
sudo ironflock os update --reboot --yes
# Installa una release più vecchia del catalogo
sudo ironflock os update --version 0.13.0

L’avanzamento va su stderr: il download e la sua verifica, poi ogni passo indicato da RAUC. Ecco cosa stampa os update --yes su un dispositivo che esegue la 0.13.0 nello slot A:

Download base: https://instance-registry.ironflock.com/dl (from default)
IronFlockOS catalog of 2026-11-20T09:00:00Z, signed with key 036ef3bd: production 0.14.0, test 0.14.0.
This device runs IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) from slot A.
IronFlockOS 0.14.0, the release of the production channel, is installed into slot B, which holds nothing yet:
  - the bundle (580.2 MB) is downloaded into /var/cache/ironflockos
  - RAUC checks its signature and writes it into slot B
  - it starts with the next restart
Slot A keeps IronFlockOS 0.13.0: the device goes back to it when 0.14.0 does not start or does not reach IronFlock. Apps and their data stay.
Downloading: 0% (0 B of 580.2 MB)
...
Installing IronFlockOS 0.14.0 into slot B.
Installing:   0% Installing
...
Installing:  82% Copying image to rootfs.1
...
Installing: 100% Installing done.
IronFlockOS 0.14.0, the release of the production channel, is installed in slot B and starts with the next restart ('sudo reboot').

Con --json l’installazione è la fase di avanzamento installing, in percentuale. Il risultato di os update --reboot --yes --json:

{"action":"installed","image":"ironflockos-amd64-efi-base","channel":"production","version":"0.14.0","running_version":"0.13.0","slot":"B","up_to_date":false,"reboot":true}

Rifiuta quando, con il codice di uscita 3:

• non viene eseguito come root, su una macchina che non esegue IronFlockOS e sulla chiavetta di installazione.
• RAUC sta già installando un bundle, avviato da IronFlock Studio tramite l’agente o da un’altra chiamata. RAUC ne installa uno alla volta.
• la release non ha un bundle per l’immagine del dispositivo.
• la release è più vecchia di quella in esecuzione, a meno che --version non la indichi. Quando l’altro slot contiene quella release, il messaggio indica os rollback.
• /var/cache/ironflockos non ha spazio sufficiente per ciò che resta da scaricare. Il messaggio elenca i bundle di aggiornamenti precedenti nella cartella, che puoi eliminare.

Righe di comando errate, codice di uscita 2: --channel e --version insieme, una versione non valida, un canale o una release che il catalogo non ha.

Fallisce quando, con il codice di uscita 1: il catalogo non supera la verifica o non può essere letto; il download si interrompe (ciò che è arrivato resta in /var/cache/ironflockos, e lo stesso comando lo riprende); il download non è il file del catalogo; RAUC rifiuta il bundle o non riesce a installarlo. L’errore indica il motivo fornito da RAUC. Se RAUC aveva iniziato a scrivere, lo slot viene segnato come difettoso e non contiene un sistema utilizzabile, e il dispositivo continua ad avviare il sistema in esecuzione. Il bundle resta nella cache per il tentativo successivo.

Ctrl-C durante il download, o subito dopo, termina il comando con il codice di uscita 130 prima che venga installato o riavviato qualcosa; lo stesso comando riprende il download. Una domanda a cui è stato risposto no termina con il codice di uscita 4.

ironflock os rollback

Imposta l’altro slot di root come quello che si avvia e riavvia il dispositivo in esso: si torna al sistema che era in esecuzione prima dell’ultimo aggiornamento. Usalo per un sistema che si avvia ma funziona male. Un sistema che non si avvia, o non raggiunge IronFlock, viene abbandonato da IronFlockOS stesso al riavvio successivo.

ironflock os rollback [flags]

Il comando non ha flag propri. Riavvia sempre il dispositivo: un rollback senza riavvio non cambierebbe nulla fino al riavvio successivo.

È idoneo solo uno slot il cui sistema si è avviato su questo dispositivo:

• uno slot il cui sistema è stato segnato come valido mentre era in esecuzione, e da allora non è stato provato di nuovo. Uno slot provato e mai segnato come valido non è idoneo.
• lo slot con cui è stato scritto il dispositivo (A), finché non vi è stato installato nulla e non è stato segnato come difettoso.

Le app e i loro dati restano, perché entrambi i sistemi usano la stessa partizione dati. Lo slot che era in esecuzione mantiene la sua release. Dopo il riavvio il sistema più vecchio deve dimostrare di nuovo di funzionare: il dispositivo lo mantiene dopo che l’agente del dispositivo ha raggiunto IronFlock da esso. Su una macchina UEFI, uno slot che ci era già riuscito in precedenza viene mantenuto anche dopo essere rimasto attivo per due minuti. Fino ad allora un riavvio può riportare il sistema più recente. IronFlock Studio offre di nuovo la release del canale, e os update la installa.

# Torna al sistema nell'altro slot, dopo una domanda
sudo ironflock os rollback
# Senza domande
sudo ironflock os rollback --yes

Ecco cosa stampa os rollback --yes su un dispositivo che esegue la 0.14.0 nello slot B:

This device runs IronFlockOS 0.14.0 from slot B.
Slot A holds IronFlockOS 0.13.0, which ran on this device before. The rollback makes slot A the one that starts and restarts the device now.
Slot B keeps IronFlockOS 0.14.0. Apps and their data stay: both systems use the same data partition.
The device keeps IronFlockOS 0.13.0 once it has proven itself again (the device agent reaches IronFlock from it); until then a restart can bring back 0.14.0.
Rolled back to IronFlockOS 0.13.0 in slot A: the device restarts now.

Con --json, slot e version sono lo slot che si avvia e la sua release (vuota quando non può essere letta), from_slot e from_version il sistema che era in esecuzione:

{"action":"rolled_back","slot":"A","version":"0.13.0","from_slot":"B","from_version":"0.14.0"}

Rifiuta quando, con il codice di uscita 3, e dice perché:

• non viene eseguito come root, su una macchina che non esegue IronFlockOS, sulla chiavetta di installazione, e mentre RAUC installa un bundle.
• il dispositivo ha un bootloader che il comando non conosce: conosce GRUB (macchine UEFI) e quello del Raspberry Pi.
• l’altro slot non contiene ancora nulla (un dispositivo appena scritto), contiene un sistema che è stato provato e non segnato come valido, non contiene un sistema utilizzabile perché la sua installazione non si è conclusa, oppure è segnato come difettoso.
• l’altro slot attende il prossimo riavvio, dopo un aggiornamento installato o un rollback che non ha riavviato. sudo reboot lo avvia, e sudo rauc status mark-bad other lo scarta.

Fallisce quando, con il codice di uscita 1: RAUC non riesce a impostare lo slot come quello che si avvia (non è stato modificato nulla); il riavvio fallisce (lo slot si avvia allora al riavvio successivo). Una domanda a cui è stato risposto no termina con il codice di uscita 4.

ironflock os reset

Richiede il reset di fabbrica di IronFlockOS e riavvia il dispositivo. Durante il boot successivo il dispositivo cancella ciò che hanno lasciato il suo proprietario, le sue app e la registrazione, e si avvia come un dispositivo appena scritto; con -c si registra come il dispositivo di un nuovo file .flock.

ironflock os reset [-c <new.flock>] [flags]

IronFlockOS 0.15.0 è la prima release con il reset di fabbrica. Su una release precedente il comando rifiuta; os update ne installa una più recente.

Il reset cancella, sulla partizione dati e in entrambi gli slot di root:

• le app con i loro dati, e i container, le immagini e i volumi di Docker.
• l’identità del dispositivo presso IronFlock: l’agente del dispositivo con la sua copia del file .flock, il suo database e il suo servizio. Il nome host torna a ironflockos, e il machine ID viene generato di nuovo.
• l’utente SSH e ogni altro account utente, con le loro cartelle home e le regole sudo.
• i log, le chiavi host SSH, gli aggiornamenti scaricati e la messa a punto real-time.
• senza --keep-network: i profili di rete (compreso il WiFi), l’impostazione del proxy (proxy.conf) e l’impostazione PTP (ptp.conf).

Mantiene i sistemi IronFlockOS negli slot di root, quello in esecuzione e l’altro quando contiene un sistema, e il record che RAUC ne tiene, quindi aggiornamenti e rollback funzionano come prima. Con --keep-network mantiene anche le impostazioni di rete indicate sopra. Non annulla ciò che è stato modificato a mano nel sistema stesso, come un pacchetto o un file in /etc; per questo occorre scrivere di nuovo IronFlockOS sul disco con os flash.

Cosa fa, in questo ordine:

1. Rifiuta ciò che il dispositivo non farebbe come richiesto (vedi sotto), e controlla il file .flock di -c: 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.
2. Dice su stderr cosa viene cancellato, cosa resta, come torna il dispositivo e cosa ha fatto il suo ultimo reset, poi ti chiede di digitare il nome del dispositivo: il suo nome nel file .flock dell’agente, come lo mostra ironflock status, oppure il nome host di un dispositivo non registrato. Qualsiasi altra cosa, anche Invio da solo, vale come no.
3. Scrive la richiesta sulla partizione IRONFLOCKOS, dopo che il controllo del dispositivo stesso l’ha accettata. Una richiesta già presente viene sostituita; questa è una nuova richiesta con tre tentativi propri.
4. Con -c, rimuove ogni altro file .flock dalla partizione, perché il dispositivo si registra con il più recente, e vi scrive il nuovo file .flock. Se questo fallisce, la richiesta viene rimossa di nuovo.
5. Riavvia il dispositivo. Durante l’avvio successivo il dispositivo si resetta, in pochi secondi (minuti su una scheda SD lenta), si riavvia ancora una volta e si avvia come un dispositivo appena scritto, con nuove chiavi host SSH.

Dopo il reset, con -c, il dispositivo si registra come il dispositivo di quel file .flock ed è raggiungibile via SSH come il suo utente SSH. Senza -c, attende un file .flock sulla sua partizione IRONFLOCKOS ed è raggiungibile solo dalla sua console: non ha un utente SSH né una connessione a IronFlock. Una connessione SSH al dispositivo, anche quella di --host, termina con il riavvio; senza -c non ne torna nessuna.

Nota: Se raggiungi il dispositivo solo tramite la rete, indica il nuovo file .flock con -c. Senza di esso, qualcuno deve trovarsi presso il dispositivo per riportarlo online.

Un tentativo che fallisce non riavvia il dispositivo: questo si avvia così com’è, e il suo avvio successivo, da parte di una persona o di un aggiornamento, ci riprova. Dopo tre tentativi falliti il reset rinuncia, e il dispositivo si avvia con ciò che c’è. Con i suoi vecchi dati resta il dispositivo che era, online con la sua vecchia identità, e il file .flock e l’impostazione del proxy arrivati con la richiesta vengono rimossi. Una richiesta conclusa, completata o abbandonata, non si attiva mai più, in nessuno slot e dopo nessun aggiornamento. Un disco che non risponde può trattenere un tentativo fino a 25 minuti. ironflock status mostra un reset fallito o abbandonato nella sua riga Last reset:.

Prima di chiedere, il comando mostra l’ultimo reset annotato dal dispositivo:

# Resetta il dispositivo; poi attende un file .flock
sudo ironflock os reset
# Resettalo e rendilo il dispositivo di new-device.flock
sudo ironflock os reset -c new-device.flock
# Mantieni le impostazioni di rete, senza domande
sudo ironflock os reset --keep-network --yes
# Da un altro computer, su IronFlockOS 0.15.0
ironflock --host operator@edge-01 os reset -c new-device.flock

Ecco cosa stampa os reset -c kitchen-pi.flock sul dispositivo edge-01, il cui ultimo reset ha rinunciato, con il nome digitato alla domanda:

This device runs IronFlockOS 0.15.0 from slot B and is the IronFlock device edge-01.
The last factory reset of this device: gave up after 3 attempts at 2026-11-11T09:00:00Z: the data partition is not the partition named data on the disk of the root slot; /data holds the old data; left of the old owner: the data partition, the booted root slot, the other root slot; the device stayed the device it was, online with its old identity, and the .flock and proxy.conf that came with the request were removed.
What can be done: request the reset again, as this command does now, with three new attempts; or write IronFlockOS to the device's disk anew ('ironflock os flash'), which clears everything.
The factory reset restarts the device now. During the next boot the device resets itself, in seconds (minutes on a slow SD card), and restarts once more. It clears:
  - the apps with their data, and Docker's containers, images and volumes
  - the device's identity at IronFlock: the agent with its copy of the .flock and its database; the hostname goes back to ironflockos
  - the SSH user and every other user account, with their home folders
  - the logs, the SSH host keys and the downloaded updates
  - the network profiles (the WiFi among them), the proxy setting and the PTP setting
It keeps IronFlockOS 0.15.0 in slot B, which runs, and IronFlockOS 0.14.0 in slot A, so updates and rollbacks work as before.
It does not undo what was changed by hand in the system itself, such as a package or a file in /etc.
Then the device starts as a freshly written one with kitchen-pi.flock, which goes onto its IRONFLOCKOS partition: it enrolls as kitchen-pi and can be reached over SSH as operator, with the device key of that .flock and new SSH host keys.
An attempt that fails does not restart the device: it comes up as it is, and its next start tries again; after three failed attempts the reset gives up, and the device starts with what is there. 'ironflock status' shows a failed or given-up reset.
An SSH connection to the device, also the one of --host, ends with the restart.
? Type the device's name, edge-01, to reset it: edge-01
Factory reset requested: the device restarts now, resets itself and enrolls as kitchen-pi.

Il risultato di os reset --keep-network --yes --json:

{"action":"reset","device":"edge-01","keep_network":true}

Rifiuta quando, con il codice di uscita 3, e dice perché e cosa fare:

• non viene eseguito come root, su una macchina che non esegue IronFlockOS, sulla chiavetta di installazione, e mentre RAUC installa un bundle.
• l’IronFlockOS in uso non ha il reset di fabbrica: lo porta una release più recente, che os update installa.
• /boot/efi non è la partizione IRONFLOCKOS montata: lì non è montato nulla, oppure un file system diverso da FAT.
• un reset è già iniziato: prosegue al prossimo avvio, e fino ad allora non va modificato nulla. Il messaggio indica l’ultimo tentativo.
• senza -c, sulla partizione IRONFLOCKOS si trova un file .flock: dopo il reset il dispositivo si registrerebbe con esso invece di attenderne uno.
• il prossimo avvio non sarebbe il sistema in esecuzione segnato come valido. Un aggiornamento o un rollback attende il suo riavvio: sudo reboot lo avvia, sudo rauc status mark-bad other lo scarta. Oppure il sistema in esecuzione non è ancora stato segnato come valido: sudo rauc status mark-good lo mantiene, os rollback torna indietro.
• il controllo del dispositivo stesso non accetta la richiesta: non viene richiesto nulla, e il messaggio indica il motivo del dispositivo.

Fallisce quando, con il codice di uscita 1:

• la tabella dei mount non può essere letta, quindi il comando non può stabilire se /boot/efi è la partizione IRONFLOCKOS. Non viene scritto nulla.
• il file .flock di -c non è valido.
• la richiesta o il file .flock non possono essere scritti, oppure un altro file .flock non può essere rimosso. La richiesta viene ritirata, e l’errore dice cosa è stato rimosso.
• il riavvio fallisce. Il dispositivo si resetta allora al suo avvio successivo; rimuovere /boot/efi/factory-reset.conf e il file .flock dalla partizione IRONFLOCKOS annulla il reset.

Ctrl-C, SIGTERM o una sessione SSH persa mentre il comando scrive la sua richiesta gli fanno ritirare la richiesta: termina con il codice di uscita 130, e il dispositivo non si riavvia. Un nome digitato in modo errato alla domanda termina con il codice di uscita 4.

I codici di uscita di tutti i comandi sono spiegati in Flag, output e codici di uscita. Via --host, il codice di uscita 255 significa che la connessione SSH non è riuscita.