Update, Rollback & Zurücksetzen

Diese Befehle kümmern sich um ein Gerät, auf dem IronFlockOS läuft. os update installiert ein Release, os rollback kehrt zu dem Release zurück, das vorher lief, und os reset macht das Gerät wieder zu einem frisch geschriebenen.

Root-Slots und die Datenpartition

Die Festplatte eines IronFlockOS-Geräts enthält:

• Zwei Root-Slots, A und B — jeder enthält ein vollständiges IronFlockOS-System. Eines davon läuft. Der andere Slot enthält das System, das vorher lief, oder auf einem frisch geschriebenen Gerät noch nichts. RAUC, das Update-Werkzeug, das IronFlockOS verwendet, schreibt ein Release in den Slot, der nicht läuft, und hält fest, welcher Slot als Nächstes startet.
• Die Datenpartition (/data) — die Apps und ihre Daten sowie der Geräte-Agent mit seiner Kopie der Gerätekonfigurationsdatei (.flock). Beide Systeme verwenden sie, sodass ein Update oder ein Rollback die Apps und ihre Daten unverändert lässt.
• Die IRONFLOCKOS-Partition (eingehängt unter /boot/efi) — eine kleine FAT-Partition. Das Gerät registriert sich bei seinem Start mit einer .flock-Datei, die es dort findet, und os reset schreibt seine Anforderung dorthin.

Ein neues System muss sich bewähren: Das Gerät behält es, sobald der Geräte-Agent von ihm aus IronFlock erreicht und es als gut markiert hat. Ein System, das nicht startet oder es nicht so weit schafft, wird beim nächsten Neustart zugunsten des Systems verlassen, das vorher lief. ironflock status zeigt die Slots:

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

Wo die Befehle laufen

Die drei Befehle laufen auf einem Gerät, auf dem IronFlockOS läuft, brauchen Root-Rechte und fragen, bevor sie handeln. Auf einem anderen System (macOS, ein Linux, das nicht IronFlockOS ist, der IronFlockOS-Installer-Stick) enden sie mit Exit-Code 3.

• Auf dem Gerät — die IronFlockOS-Releases nach 0.15.0 bringen ironflock mit. Melden Sie sich auf dem Gerät an, und führen Sie den Befehl mit sudo aus.
• Von einem anderen Computer aus — die IronFlockOS-Releases bis 0.15.0 bringen ironflock nicht mit. Führen Sie den Befehl von einem Linux- oder macOS-Computer aus mit --host aus, als SSH-Benutzer des Geräts: das Konto, das die .flock-Datei für den Projekteigentümer einrichtet, in den Beispielen operator. --host kopiert ironflock für den Lauf auf das Gerät und führt den Befehl dort über sudo aus.

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

os update und os rollback laufen auf mehreren Geräten gleichzeitig (--host mehrfach angegeben oder --hosts), wenn --yes angegeben ist. os reset läuft jeweils nur auf einem Gerät; auf mehreren endet es mit Exit-Code 2. Die globalen Flags stehen unter Flags, Ausgabe & Exit-Codes.

ironflock os update

Installiert das Release von IronFlockOS, das der Kanal des Geräts anbietet, in den Root-Slot, der nicht läuft. Das neue System startet mit dem nächsten Neustart oder mit --reboot sofort.

ironflock os update [flags]

Der Kanal des Geräts ist der, dem sein Geräte-Agent folgt, aus dem environment der .flock-Datei des Agenten: test auf der Testplattform von IronFlock und sonst production. Hat der Katalog den Kanal des Geräts nicht, ist es production. Die Download-Basis kommt aus --download-base, dann aus IRONFLOCK_DL_BASE, dann vom Update-Server (update_url) der .flock-Datei des Agenten (auf einem Gerät einer IronFlock-Appliance der Download-Spiegel der Appliance, der einzige Server, den ein solches Gerät erreichen darf), sonst ist sie die IronFlock-Cloud.

Was der Befehl tut, in dieser Reihenfolge:

1. Liest den signierten IronFlockOS-Katalog und nimmt das Update-Bundle des Images des Geräts im Release des Kanals (oder von --version).
2. Sagt, welches Release in welchem Slot läuft, welches Release er in welchen Slot installiert, was dieser Slot jetzt enthält und wie groß der Download ist. Dann fragt er.
3. Lädt das Bundle nach /var/cache/ironflockos auf der Datenpartition herunter. Ein unterbrochener Download wird fortgesetzt. Die Datei wird nur verwendet, wenn ihre Größe und ihr SHA-256 denen des Katalogs entsprechen.
4. Lässt RAUC das Bundle in den Slot installieren, der nicht läuft. RAUC prüft die Signatur des Bundles, beschreibt den Slot und macht ihn zu dem, der als Nächstes startet. Was der Slot vorher enthielt, wird überschrieben. Das Bundle wird entfernt, sobald es installiert ist.
5. Startet das Gerät mit --reboot in das neue System neu.

Das laufende System bleibt bis zum Neustart, wie es ist. Apps und ihre Daten bleiben. Der Slot, der jetzt läuft, behält sein Release, und das Gerät kehrt zu ihm zurück, wenn das neue Release nicht startet oder IronFlock nicht erreicht.

Nichts wird installiert, und der Exit-Code ist 0, wenn das Gerät das Release bereits ausführt und wenn das Release bereits im anderen Slot installiert ist und auf den Neustart wartet. Im zweiten Fall fragt --reboot und startet das Gerät neu.

# Das Release des Kanals des Geräts installieren; es startet mit dem nächsten Neustart
sudo ironflock os update
# Es installieren und ohne Frage in das neue System neu starten
sudo ironflock os update --reboot --yes
# Ein älteres Release des Katalogs installieren
sudo ironflock os update --version 0.13.0

Der Fortschritt geht auf stderr: der Download und seine Prüfung, dann jeder Schritt, den RAUC nennt. Was os update --yes auf einem Gerät ausgibt, das 0.13.0 in Slot A ausführt:

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').

Mit --json ist die Installation die Fortschrittsphase installing, in Prozent. Das Ergebnis von 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}

Lehnt ab mit Exit-Code 3:

• ohne Root-Rechte, auf einer Maschine ohne IronFlockOS und auf dem Installer-Stick.
• wenn RAUC bereits ein Bundle installiert, eines, das IronFlock Studio über den Agenten oder ein anderer Aufruf gestartet hat. RAUC installiert immer nur eines.
• wenn das Release kein Bundle für das Image des Geräts hat.
• wenn das Release älter als das laufende ist, außer --version nennt es. Enthält der andere Slot dieses Release, nennt die Meldung os rollback.
• wenn /var/cache/ironflockos nicht genug Platz für das hat, was noch herunterzuladen ist. Die Meldung listet die Bundles früherer Updates im Ordner auf, die Sie löschen können.

Falsche Befehlszeilen, Exit-Code 2: --channel und --version zusammen, eine Version, die keine ist, ein Kanal oder ein Release, den der Katalog nicht hat.

Schlägt fehl mit Exit-Code 1, wenn die Prüfung des Katalogs fehlschlägt oder er sich nicht lesen lässt, wenn der Download abbricht (was angekommen ist, bleibt in /var/cache/ironflockos, und derselbe Befehl setzt den Download fort), wenn der Download nicht die Datei des Katalogs ist und wenn RAUC das Bundle ablehnt oder es nicht installieren kann. Der Fehler nennt den Grund von RAUC. Hatte RAUC zu schreiben begonnen, wird der Slot als fehlerhaft markiert und enthält kein verwendbares System, und das Gerät startet weiterhin das System, das läuft. Das Bundle bleibt für den nächsten Versuch im Cache.

Strg+C während des Downloads oder direkt danach beendet den Befehl mit Exit-Code 130, bevor irgendetwas installiert oder neu gestartet wird; derselbe Befehl setzt den Download fort. Eine mit Nein beantwortete Frage beendet ihn mit Exit-Code 4.

ironflock os rollback

Macht den anderen Root-Slot zu dem, der startet, und startet das Gerät in ihn neu: zurück zu dem System, das vor dem letzten Update lief. Verwenden Sie den Befehl für ein System, das startet, sich aber falsch verhält. Ein System, das nicht startet oder IronFlock nicht erreicht, verlässt IronFlockOS beim nächsten Neustart von selbst.

ironflock os rollback [flags]

Der Befehl hat keine eigenen Flags. Er startet das Gerät immer neu: Ein Rollback ohne Neustart würde bis zum nächsten Neustart nichts ändern.

Nur ein Slot, dessen System auf diesem Gerät gestartet ist, kommt infrage:

• ein Slot, dessen System als gut markiert wurde, während es lief, und seitdem nicht erneut versucht wurde. Ein Slot, der versucht und nie als gut markiert wurde, kommt nicht infrage.
• der Slot, mit dem das Gerät geschrieben wurde (A), solange nichts in ihn installiert und er nicht als fehlerhaft markiert wurde.

Apps und ihre Daten bleiben, da beide Systeme dieselbe Datenpartition verwenden. Der Slot, der lief, behält sein Release. Nach dem Neustart muss sich das ältere System erneut bewähren: Das Gerät behält es, sobald der Geräte-Agent von ihm aus IronFlock erreicht hat. Auf einer UEFI-Maschine wird ein Slot, der das schon einmal geschafft hat, auch behalten, sobald er zwei Minuten läuft. Bis dahin kann ein Neustart das neuere System zurückbringen. IronFlock Studio bietet das Release des Kanals wieder an, und os update installiert es.

# Zum System im anderen Slot zurückkehren, nach einer Frage
sudo ironflock os rollback
# Ohne Frage
sudo ironflock os rollback --yes

Was os rollback --yes auf einem Gerät ausgibt, das 0.14.0 in Slot B ausführt:

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.

Mit --json sind slot und version der Slot, der startet, und sein Release (leer, wenn es sich nicht lesen lässt), from_slot und from_version das System, das lief:

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

Lehnt ab mit Exit-Code 3 und sagt, warum:

• ohne Root-Rechte, auf einer Maschine ohne IronFlockOS, auf dem Installer-Stick und während RAUC ein Bundle installiert.
• wenn das Gerät einen Bootloader hat, den der Befehl nicht kennt: Er kennt GRUB (UEFI-Maschinen) und den des Raspberry Pi.
• wenn der andere Slot noch nichts enthält (ein frisch geschriebenes Gerät), ein System enthält, das versucht und nicht als gut markiert wurde, kein verwendbares System enthält, weil seine Installation nicht fertig wurde, oder als fehlerhaft markiert ist.
• wenn der andere Slot auf den nächsten Neustart wartet, nach einem installierten Update oder einem Rollback ohne Neustart. sudo reboot startet ihn, und sudo rauc status mark-bad other verwirft ihn.

Schlägt fehl mit Exit-Code 1, wenn RAUC den Slot nicht zu dem machen kann, der startet (nichts wurde geändert), und wenn der Neustart fehlschlägt (der Slot startet dann mit dem nächsten Neustart). Eine mit Nein beantwortete Frage beendet ihn mit Exit-Code 4.

ironflock os reset

Fordert das Zurücksetzen von IronFlockOS auf Werkseinstellungen an und startet das Gerät neu. Beim nächsten Boot entfernt das Gerät, was sein Eigentümer, seine Apps und die Registrierung hinterlassen haben, und startet als frisch geschriebenes Gerät; mit -c registriert es sich als Gerät einer neuen .flock-Datei.

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

IronFlockOS 0.15.0 ist das erste Release mit dem Zurücksetzen auf Werkseinstellungen. Auf einem älteren Release lehnt der Befehl ab; os update installiert ein neueres.

Das Zurücksetzen entfernt auf der Datenpartition und in beiden Root-Slots:

• die Apps mit ihren Daten sowie die Container, Images und Volumes von Docker.
• die Identität des Geräts bei IronFlock: den Geräte-Agenten mit seiner Kopie der .flock-Datei, seiner Datenbank und seinem Dienst. Der Hostname wird wieder ironflockos, und die Machine-ID wird neu erzeugt.
• den SSH-Benutzer und jedes andere Benutzerkonto, mit ihren Home-Verzeichnissen und sudo-Regeln.
• die Logs, die SSH-Host-Schlüssel, die heruntergeladenen Updates und das Echtzeit-Tuning.
• ohne --keep-network: die Netzwerkprofile (darunter das WLAN), die Proxy-Einstellung (proxy.conf) und die PTP-Einstellung (ptp.conf).

Es behält die IronFlockOS-Systeme in den Root-Slots, das laufende und das andere, wenn der andere Slot ein System enthält, sowie das, was RAUC über sie festhält, sodass Updates und Rollbacks wie bisher funktionieren. Mit --keep-network behält es außerdem die oben genannten Netzwerkeinstellungen. Es macht nicht rückgängig, was im System selbst von Hand geändert wurde, etwa ein Paket oder eine Datei in /etc; das leistet nur ein neues Schreiben von IronFlockOS auf die Festplatte mit os flash.

Was der Befehl tut, in dieser Reihenfolge:

1. Lehnt ab, was das Gerät nicht wie verlangt tun würde (siehe unten), und prüft die .flock-Datei von -c: eine Datei namens *.flock mit höchstens 5 MiB, ein JSON-Objekt mit secret und device_key, dessen name und serial_number einfache Namen sind.
2. Sagt auf stderr, was verschwindet, was bleibt, wie das Gerät zurückkommt und was sein letztes Zurücksetzen getan hat, und bittet Sie dann, den Namen des Geräts einzutippen: seinen Namen in der .flock-Datei des Agenten, wie ironflock status ihn zeigt, oder den Hostnamen eines Geräts, das nicht registriert ist. Alles andere, auch Enter allein, beantwortet die Frage mit Nein.
3. Schreibt die Anforderung auf die IRONFLOCKOS-Partition, nachdem die eigene Prüfung des Geräts sie angenommen hat. Eine bereits vorhandene Anforderung wird ersetzt; diese ist eine neue Anforderung mit drei eigenen Versuchen.
4. Entfernt mit -c jede andere .flock-Datei von der Partition, da sich das Gerät mit der neuesten registriert, und schreibt die neue .flock-Datei dorthin. Schlägt das fehl, wird die Anforderung wieder entfernt.
5. Startet das Gerät neu. Beim nächsten Start setzt sich das Gerät zurück, in Sekunden (Minuten auf einer langsamen SD-Karte), startet noch einmal neu und kommt als frisch geschriebenes Gerät hoch, mit neuen SSH-Host-Schlüsseln.

Nach dem Zurücksetzen registriert sich das Gerät mit -c als Gerät dieser .flock-Datei und ist über SSH als deren SSH-Benutzer erreichbar. Ohne -c wartet es auf eine .flock-Datei auf seiner IRONFLOCKOS-Partition und ist nur über seine Konsole erreichbar: Es hat keinen SSH-Benutzer und keine Verbindung zu IronFlock. Eine SSH-Verbindung zum Gerät, auch die von --host, endet mit dem Neustart; ohne -c kommt keine zurück.

Hinweis: Wenn Sie das Gerät nur über das Netzwerk erreichen, geben Sie die neue .flock-Datei mit -c an. Ohne sie muss jemand am Gerät sein, um es wieder online zu bringen.

Ein fehlgeschlagener Versuch startet das Gerät nicht neu: Es kommt so hoch, wie es ist, und sein nächster Start, ob durch eine Person oder durch ein Update, versucht es erneut. Nach drei fehlgeschlagenen Versuchen gibt das Zurücksetzen auf, und das Gerät startet mit dem, was vorhanden ist. Mit seinen alten Daten bleibt es das Gerät, das es war, online mit seiner alten Identität, und die .flock-Datei und die Proxy-Einstellung, die mit der Anforderung kamen, werden entfernt. Eine beendete Anforderung, ob erledigt oder aufgegeben, wird nie wieder ausgelöst, in keinem Slot und nach keinem Update. Eine Festplatte, die nicht antwortet, kann einen Versuch bis zu 25 Minuten aufhalten. ironflock status zeigt ein fehlgeschlagenes oder aufgegebenes Zurücksetzen in seiner Zeile Last reset:.

Bevor er fragt, zeigt der Befehl das letzte Zurücksetzen, das das Gerät festgehalten hat:

# Das Gerät zurücksetzen; es wartet dann auf eine .flock-Datei
sudo ironflock os reset
# Es zurücksetzen und zum Gerät von new-device.flock machen
sudo ironflock os reset -c new-device.flock
# Die Netzwerkeinstellungen behalten, ohne Frage
sudo ironflock os reset --keep-network --yes
# Von einem anderen Computer aus, auf IronFlockOS 0.15.0
ironflock --host operator@edge-01 os reset -c new-device.flock

Was os reset -c kitchen-pi.flock auf dem Gerät edge-01 ausgibt, dessen letztes Zurücksetzen aufgegeben wurde, mit dem bei der Frage eingetippten Namen:

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.

Das Ergebnis von os reset --keep-network --yes --json:

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

Lehnt ab mit Exit-Code 3 und sagt, warum und was zu tun ist:

• ohne Root-Rechte, auf einer Maschine ohne IronFlockOS, auf dem Installer-Stick und während RAUC ein Bundle installiert.
• wenn das IronFlockOS kein Zurücksetzen auf Werkseinstellungen kennt: Ein neueres Release bringt es mit, und os update installiert dieses.
• wenn /boot/efi nicht die eingehängte IRONFLOCKOS-Partition ist: Dort ist nichts eingehängt oder ein anderes Dateisystem als FAT.
• wenn ein Zurücksetzen begonnen hat: Es geht beim nächsten Start weiter, und bis dahin soll nichts geändert werden. Die Meldung nennt den letzten Versuch.
• ohne -c, wenn eine .flock-Datei auf der IRONFLOCKOS-Partition liegt: Nach dem Zurücksetzen würde sich das Gerät mit ihr registrieren, statt auf eine zu warten.
• wenn der nächste Start nicht das laufende, als gut markierte System wäre. Ein Update oder ein Rollback wartet auf seinen Neustart: sudo reboot startet es, sudo rauc status mark-bad other verwirft es. Oder das laufende System wurde noch nicht als gut markiert: sudo rauc status mark-good behält es, os rollback kehrt zurück.
• wenn die eigene Prüfung des Geräts die Anforderung nicht annimmt: Nichts wird angefordert, und die Meldung nennt den Grund des Geräts.

Schlägt fehl mit Exit-Code 1:

• wenn sich die Mount-Tabelle nicht lesen lässt, sodass der Befehl nicht erkennen kann, ob /boot/efi die IRONFLOCKOS-Partition ist. Nichts wird geschrieben.
• wenn die .flock-Datei von -c nicht gültig ist.
• wenn sich die Anforderung oder die .flock-Datei nicht schreiben oder eine andere .flock-Datei nicht entfernen lässt. Die Anforderung wird zurückgenommen, und der Fehler sagt, was schon entfernt ist.
• wenn der Neustart fehlschlägt. Das Gerät setzt sich dann bei seinem nächsten Start zurück; das Entfernen von /boot/efi/factory-reset.conf und der .flock-Datei von der IRONFLOCKOS-Partition bricht das Zurücksetzen ab.

Strg+C, SIGTERM oder eine verlorene SSH-Sitzung, während der Befehl seine Anforderung schreibt, lassen ihn die Anforderung zurücknehmen: Er endet mit Exit-Code 130, und das Gerät startet nicht neu. Ein bei der Frage falsch eingetippter Name beendet den Befehl mit Exit-Code 4.

Die Exit-Codes aller Befehle sind unter Flags, Ausgabe & Exit-Codes erklärt. Über --host bedeutet Exit-Code 255, dass die SSH-Verbindung fehlgeschlagen ist.