IronFlockOS auf ein Laufwerk schreiben

ironflock os flash bereitet das Laufwerk vor, von dem ein neues Gerät startet. Es schreibt IronFlockOS und die Gerätekonfigurationsdatei (.flock) auf das Laufwerk, und das Gerät registriert sich bei seinem ersten Boot: Es verbindet sich als Gerät dieser .flock-Datei mit IronFlock. Sie können Folgendes vorbereiten:

• einen USB-Stick, eine SD-Karte oder eine externe Festplatte, von der das Gerät startet,
• einen Installer-Stick, der IronFlockOS auf die interne Festplatte eines PCs installiert,
• eine Disk-Image-Datei, von der eine virtuelle Maschine startet.

FlockFlasher ist die Desktop-App für dieselbe Aufgabe. Wie Sie die .flock-Datei eines Geräts erhalten, steht unter Geräte verbinden.

Typischer Ablauf

# 1. Den Stick oder die SD-Karte einstecken, dann die Laufwerke auflisten, die beschrieben werden dürfen
ironflock os drives
# 2. Optional: die Images auflisten, die der Katalog anbietet
ironflock os images
# 3. IronFlockOS und die .flock-Datei des Geräts auf das Laufwerk schreiben
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash zeigt seinen Plan und fragt, bevor es das Laufwerk löscht. Wenn es fertig ist, stecken Sie das Laufwerk in das Gerät und starten das Gerät davon.

ironflock os images

Listet die IronFlockOS-Images auf, die sich auf ein Laufwerk schreiben lassen. Standardmäßig listet der Befehl die Images des Release im Produktionskanal auf.

ironflock os images [flags]

Läuft unter Linux und macOS. Braucht keine Root-Rechte. Fragt nichts.

Flags

Die Flags, die jeder Befehl akzeptiert, stehen unter Flags, Ausgabe & Exit-Codes.

Was der Befehl tut

Die Liste kommt aus dem signierten IronFlockOS-Katalog des Download-Servers, <download base>/ironflockos/manifest.json. ironflock verwendet den Katalog nur, wenn sich seine Ed25519-Signatur mit dem Katalogschlüssel bestätigen lässt, der in ironflock eingebaut ist. FlockFlasher und der Geräte-Agent haben denselben Schlüssel fest eingebaut. Kein Flag und keine Umgebungsvariable schaltet diese Prüfung ab. Die Download-Basis ist die IronFlock-Cloud, außer Sie nennen eine andere, siehe Download-Basis.

Der letzte Katalog, dessen Prüfung gelungen ist, wird in einem Cache-Ordner aufbewahrt, eine Kopie pro Download-Basis:

Ist der Download-Server nicht erreichbar, tritt die aufbewahrte Kopie an seine Stelle, mit einem Hinweis auf stderr. Ein Katalog derselben Download-Basis, der älter als die aufbewahrte Kopie ist, wird abgelehnt.

Ein Image ist nach seinem Hardware-Target, seiner Variante und seinem Kernel benannt: ironflockos-<target>-<variant>, mit -rt für den Echtzeit-Kernel. ironflockos-amd64-efi-base-rt ist das Basissystem mit dem Echtzeit-Kernel für x86-64-PCs mit UEFI. Die Targets sind:

• amd64-efi — x86-64-PC mit UEFI
• arm64-efi — ARM64-Maschine mit UEFI
• rpi-arm64 — Raspberry Pi 4, 400 und CM4; Raspberry Pi 5 und CM5

Die Varianten sind base, nvidia und installer. Das Installer-Image ergibt einen USB-Stick, der eines der mitgebrachten Images auf die Festplatte der Maschine installiert, die von ihm startet. Ein Image einer Variante, eines Kernels oder einer Architektur, die dieses ironflock nicht kennt (aus einem neueren Release), wird mit einem Hinweis auf stderr ausgelassen.

Beispiele

# Die Images des aktuellen Produktions-Release
ironflock os images
# Nur die Raspberry-Pi-Images
ironflock os images --target rpi-arm64
# Die Images des Testkanals als JSON
ironflock os images --channel test --json

Ergebnis

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

Mit --json (hier mit --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 und key_id beschreiben den Katalog, channels nennt das Release jedes Kanals, und from_cache ist true, wenn der Download-Server nicht geantwortet hat. Jedes Image hat seine Datei file mit url, size und sha256. boards sind die Board-Modelle, die eine .flock-Datei nennt (board.model), und hardware sind ihre Namen. Ein Installer-Image hat außerdem payloads, die IDs der Images, die es mitbringt.

Wann der Befehl fehlschlägt

• Exit-Code 2 — --channel und --version zusammen, eine Version, die keine ist, oder ein Kanal, ein Release, ein Target, eine Variante oder ein Kernel, den der Katalog nicht hat. Der Fehler nennt, was der Katalog hat.
• Exit-Code 1 — die Prüfung des Katalogs schlägt fehl, er ist größer als 64 KiB, ist keiner, den dieses ironflock lesen kann, oder ist älter als die aufbewahrte Kopie; oder er lässt sich nicht abrufen, und es ist keine Kopie aufbewahrt.

ironflock os drives

Listet die Laufwerke dieser Maschine auf, auf die ein IronFlockOS-Image geschrieben werden darf: USB-Sticks, SD-Karten, externe Festplatten. Der Befehl beschreibt kein Laufwerk, hängt keines aus und öffnet keines.

ironflock os drives [flags]

Läuft unter Linux und macOS. Braucht keine Root-Rechte. Fragt nichts. Unter Linux führt er lsblk (aus util-linux) aus und liest /proc und /sys. Unter macOS führt er diskutil list, diskutil info und hdiutil info aus.

Flags

Die Flags, die jeder Befehl akzeptiert, stehen unter Flags, Ausgabe & Exit-Codes.

Welche Laufwerke abgelehnt werden

os flash lehnt die Laufwerke ab, die os drives ablehnt, aus denselben Gründen. Ein Laufwerk wird abgelehnt, wenn es (angezeigt wird der erste zutreffende Grund):

1. eine Partition ist, etwa /dev/sdb1. Die Ablehnung nennt ihre Festplatte: Ein Image kommt auf die ganze Festplatte.
2. keine Festplatte ist: ein optisches Laufwerk, eine Festplatte im Arbeitsspeicher (zram), ein Volume, das auf anderen Laufwerken aufbaut (LVM, dm-crypt, RAID, device-mapper; unter macOS ein APFS-Container, ein AppleRAID-Set oder eine andere synthetisierte Festplatte), oder eine Art von Gerät, die der Befehl nicht kennt (nbd, mtdblock).
3. einen Teil des laufenden Systems enthält: /, /boot, /efi, /usr, /var, /etc oder einen Mount unterhalb davon (die EFI-Partition unter /boot/efi, die Daten von Docker unter /var/lib/docker), /home, /opt, /srv, /data, Swap oder das Medium eines Live-Systems. Das gilt unabhängig davon, wie das System auf dem Laufwerk liegt: in einer Partition, über LVM, dm-crypt, RAID oder device-mapper, in einem btrfs-Dateisystem über mehrere Laufwerke, in einem ZFS-Pool, in einem Overlay oder in einer Datei, die ein Loop-Device liest. Unter macOS: / und die Volumes unter /System, über ihre APFS-Container bis hinunter zu der Festplatte, die sie enthält.
4. in Gebrauch ist: durch LVM, dm-crypt, RAID oder device-mapper, durch einen ZFS-Pool mit einem eingehängten Dataset oder durch ein Loop-Device, das eine Datei darauf liest. Unter macOS auch durch einen APFS-Container darauf, ein AppleRAID-Set, ein Disk-Image, dessen Datei darauf liegt, oder durch Core Storage, AppleRAID oder einen APFS-Container, der nicht eingebunden ist. macOS gibt einen Stick mit einem APFS-Container erst frei, wenn der Stick gelöscht wird, daher nennt der Grund den Befehl, der ihn löscht, zum Beispiel diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6 (oder Löschen im Festplattendienstprogramm).
5. eine interne Festplatte der Maschine ist: eine SATA- oder NVMe-Festplatte, der eMMC-Speicher eines Boards. Ein Laufwerk ist intern, außer es ist über USB oder einen anderen Bus angeschlossen, dessen Geräte sich abziehen lassen. Ein eingebauter Kartenleser ist intern, seine SD-Karte aber ist ein Wechselmedium und wird angeboten, auch auf einem Mac. Unter macOS gilt eine Festplatte, die nicht sagt, wo sie sitzt, als intern. os flash --allow-internal beschreibt eine interne Festplatte, die --drive nennt, wenn kein anderer Grund sie ablehnt.
6. einen Teil des laufenden Systems enthalten kann: Lässt sich ein Teil des laufenden Systems keinem Laufwerk zuordnen, wird jedes Laufwerk abgelehnt. Das ist in einem Container der Fall, dessen System auf seinem Host liegt, und unter macOS bei einem System auf einem Volume, das zu keiner physischen Festplatte führt, etwa bei Core Storage.
7. schreibgeschützt ist, etwa eine gesperrte SD-Karte.
8. kein Medium hat, etwa ein Kartenleser ohne Karte.

Ein Laufwerk mit eingehängten Dateisystemen wird angeboten; mounted listet sie auf, und os flash hängt sie aus, bevor es schreibt. Loop-Devices und unter macOS eingebundene Disk-Images werden nicht aufgelistet, aber os flash beschreibt eines, das --drive nennt.

Auf einem Gerät, das IronFlockOS ausführt, warnt der Befehl auf stderr und in warnings: Jedes IronFlockOS-Image eines Targets hat dieselben Partitions-UUIDs, sodass das laufende System, solange ein zweites IronFlockOS-Laufwerk angeschlossen ist, seine eigenen Partitionen nicht von denen des Laufwerks unterscheiden kann.

Beispiele

# Die Laufwerke, die beschrieben werden dürfen
ironflock os drives
# Alle Laufwerke, mit dem Grund für jedes abgelehnte
ironflock os drives --all
# Die Laufwerke als JSON
ironflock os drives --json

Ergebnis

Unter Linux:

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

Mit --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

Auf einem Mac, mit --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

Mit --json (gekürzt):

{"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":[]}

Gibt es kein Laufwerk, auf das sich schreiben lässt, sagt der Text das, drives ist leer, und der Exit-Code ist 0.

Wann der Befehl fehlschlägt

• Exit-Code 3 — unter Linux ist lsblk nicht installiert; oder der Befehl läuft auf einem anderen System als Linux oder macOS.

ironflock os flash

Schreibt IronFlockOS auf ein Laufwerk (einen USB-Stick, eine SD-Karte, eine externe Festplatte) und legt die .flock-Datei des Geräts in die Partition IRONFLOCKOS des Laufwerks, die FAT32-Partition dieses Namens, die jedes IronFlockOS-Laufwerk hat. Das Gerät registriert sich mit dieser Datei bei seinem ersten Boot. Mit --output schreibt der Befehl dasselbe stattdessen in eine Disk-Image-Datei für eine virtuelle Maschine.

Warnung: Alles auf dem Laufwerk wird gelöscht. Prüfen Sie den Namen des Laufwerks mit ironflock os drives, bevor Sie schreiben. os flash wählt nie selbst ein Laufwerk.

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

Ohne Root-Rechte nennt der Fehler die einzugebende Befehlszeile mit sudo davor. Unter macOS braucht ein Benutzer, der das Raw-Device des Laufwerks beschreiben darf, keine Root-Rechte: der Benutzer, der ein Disk-Image eingebunden hat, oder ein Benutzer, dem der Eigentümer der Maschine das Laufwerk überlassen hat, zum Beispiel mit sudo chown <user> /dev/disk4 /dev/rdisk4. Mit --output braucht der Befehl keine Root-Rechte. Siehe auch Root-Rechte.

Flags

Die Flags, die jeder Befehl akzeptiert, stehen unter Flags, Ausgabe & Exit-Codes.

Was der Befehl tut

1. Prüft das Laufwerk. Er löst --drive auf und lehnt es aus den Gründen ab, die os drives nennt, bevor er irgendetwas liest, abruft oder fragt. Ohne --drive (und ohne --output) nennt er die Laufwerke, die er beschreiben darf, und endet mit Exit-Code 2.
2. Liest die .flock-Datei. Sie muss eine Datei namens *.flock mit höchstens 5 MiB sein, ein JSON-Objekt mit secret und device_key, dessen name und serial_number einfache Namen sind.
3. Wählt das Image aus dem signierten Katalog, den er abruft und prüft wie os images. Er nimmt das Image, das --image nennt, sonst das Standard-Image (Variante base, Standard-Kernel) der Hardware, die die .flock-Datei nennt: ihr board.model, sonst ihre architecture, wenn der Katalog dafür genau eine Hardware hat. Mit --installer nimmt er den Installer-Stick dieser Hardware, der das Image mitbringt.
4. Zeigt den Plan auf stderr: das Image, woher seine Datei kommt, die .flock-Datei (mit ihrem Namen), das WLAN, das Laufwerk und die Dateisysteme des Laufwerks, die er aushängt. Dann fragt er. „Nein“ ist vorausgewählt, sodass Enter allein nichts löscht.
5. Holt die Image-Datei: die Datei von --image-file, sonst die Kopie im Cache, sonst einen Download in den Cache, der dort fortgesetzt wird, wo ein früherer Download aufgehört hat. Als root ist der Cache /var/cache/ironflock/images unter Linux und /var/root/Library/Caches/ironflock/images unter macOS. Der Download geht in eine .part-Datei. Jede Datei wird nur geschrieben, wenn ihre Größe und ihr SHA-256 denen des Katalogs entsprechen. Ein Downloadversuch, der eine Minute lang kein Byte bringt, endet, und der Download gibt nach drei solchen Versuchen in Folge auf.
6. Prüft das Laufwerk erneut. Es muss das Laufwerk sein, das der Plan gezeigt hat, und darf weiterhin nicht abgelehnt sein: dasselbe Blockgerät, dieselbe Größe, Seriennummer und dasselbe Medium. Unter Linux gehören dazu der Hersteller, das Modell, der Bus und jede Partition mit ihrem Dateisystem, Label, ihrer UUID und Größe. Unter macOS, das keine Seriennummer nennt, sind es das Modell, der Bus, die Stelle im Gerätebaum und die Partitionen mit ihren UUIDs. Ein Stick, der seit dem Plan abgezogen wurde, überlässt seinen Namen dem nächsten eingesteckten Laufwerk; ein solches Laufwerk wird nicht beschrieben, und nichts wird ausgehängt. Dann hängt der Befehl die Dateisysteme aus, die der Plan aufgelistet hat, und nur diese, und öffnet das Laufwerk exklusiv zum Schreiben. Unter macOS schreibt er über das Raw-Device (/dev/rdisk4), das ein zweites os flash nicht gleichzeitig öffnen kann.
7. Schreibt das Image, liest das Laufwerk dann zurück und vergleicht es.
8. Schreibt die .flock-Datei in den Wurzelordner der Partition IRONFLOCKOS, ohne sie einzuhängen. Ein Installer-Stick erhält außerdem installer.conf. Mit --wifi-ssid nennt die Kopie auf dem Laufwerk dieses Netzwerk; die .flock-Datei selbst bleibt unverändert.
9. Wirft unter macOS das Laufwerk aus (diskutil eject), damit Sie es herausnehmen können. Schlägt das Auswerfen fehl, ist das Laufwerk trotzdem beschrieben: Der Befehl warnt, und Sie werfen das Laufwerk im Finder aus, bevor Sie es herausnehmen.

Als root verwendet der Befehl einen Cache-Ordner nur, wenn er ein Ordner und kein Link ist, root gehört und von niemandem sonst beschrieben werden kann. Einen fehlenden legt er mit Modus 0700 an, und bei jedem anderen hält er an, bevor er dort irgendetwas liest, löscht oder herunterlädt. Bevor er ein Image des Katalogs abruft, löscht er die Image-Dateien im Cache, die der Katalog nicht mehr aufführt, und ihre unvollständigen Downloads.

Ein --image für andere Hardware als die, die die .flock-Datei nennt, wird nach einer Warnung im Plan geschrieben: Das Gerät würde seine Apps nicht ausführen. Auf einem Gerät, das IronFlockOS ausführt, warnt der Plan wie os drives. Mit --allow-internal warnt der Plan, dass das Laufwerk eine interne Festplatte ist.

--yes beantwortet die Frage mit Ja. Ohne Terminal (eine Pipe, ein Skript) und ohne --yes fragt der Befehl nicht und endet mit Exit-Code 4. Auch --json fragt nichts und braucht daher --yes, um ein Laufwerk zu beschreiben. Mit --json wird der Plan nicht ausgegeben: stderr enthält nur die Fortschrittsereignisse, und die Warnungen stehen im Ergebnis. Siehe Fragen und Bestätigung und Ausgabe und JSON.

WLAN

Das Gerät verbindet sich mit dem WLAN, das seine .flock-Datei nennt. --wifi-ssid gibt ihm ein anderes Netzwerk. IronFlockOS verbindet sich nur mit einem WLAN mit Passphrase, daher gehören --wifi-ssid und --wifi-password-file immer zusammen. Die Passphrase kommt aus einer Datei oder einer Pipe, nie von der Befehlszeile, wo ps und der Shell-Verlauf sie zeigen würden. Der Befehl gibt sie nirgends aus. Die Kopie der .flock-Datei auf dem Laufwerk nennt das Netzwerk in wlanssid und password.

Hinweis: Kommt die Passphrase über /dev/stdin, ist stdin kein Terminal, und der Befehl kann nicht fragen. Geben Sie zusätzlich --yes an.

Installer-Stick

Mit --installer wird das Laufwerk zum Installer-Stick für einen PC mit UEFI (amd64-efi, arm64-efi); ironflock os images --variant installer listet die Installer-Images auf. Der Stick bringt mehrere Images seiner Hardware mit; installer.conf auf dem Stick nennt das, das er installiert (payload, das Image, das wie in Schritt 3 gewählt wird), und enthält die --installer-*-Flags, die Sie angegeben haben. Wenn der PC vom Stick startet, geht der Installer so vor:

1. Er wählt die Festplatte nach --installer-disk: die größte Festplatte (Standard), die Festplatte /dev/<name> oder die Festplatte mit der ID by-id:<id>. Eine USB-Festplatte beschreibt er nur mit --installer-allow-usb yes.
2. Er fragt an der Konsole des PCs, bevor er schreibt, außer mit --installer-confirm no.
3. Er schreibt das Image und die .flock-Datei des Geräts auf diese Festplatte.
4. Er schaltet den PC aus (Standard) oder startet ihn mit --installer-after reboot neu.

Nehmen Sie den Stick heraus, und starten Sie den PC von seiner internen Festplatte. Das Gerät registriert sich bei seinem ersten Boot.

Warnung: Ein Stick, der mit --installer-confirm no geschrieben wurde, löscht ohne Frage die Festplatte jedes PCs, der von ihm startet. Beschriften Sie einen solchen Stick, und halten Sie ihn von anderen Maschinen fern.

Um das Linux einer laufenden Maschine ohne Stick zu ersetzen, siehe Linux durch IronFlockOS ersetzen.

Eine heruntergeladene Image-Datei

--image-file schreibt eine Image-Datei, die Sie vorher heruntergeladen haben, etwa auf einer Maschine, die die Image-Dateien des Katalogs nicht herunterladen kann. Die Adresse der Datei steht in url von os images --json. Die Datei wird nur geschrieben, wenn sie die Größe und den SHA-256 hat, die der Katalog für das Image nennt.

Der Befehl braucht trotzdem den signierten Katalog, um die Datei zu prüfen. Er ruft den Katalog ab oder verwendet, wenn der Download-Server nicht erreichbar ist, die Kopie, die er beim letzten Mal aufbewahrt hat, als ein Katalog derselben Download-Basis die Prüfung bestanden hat. Diese Kopie gibt es pro Benutzer: Als root ist es die Kopie von root. Ein eigener Server funktioniert ebenso: Mit einer anderen Download-Basis (--download-base oder IRONFLOCK_DL_BASE) ruft der Befehl den Katalog von <download base>/ironflockos/manifest.json und die Image-Datei von <download base>/ironflockos/<version>/<file> ab.

Hinweis: Die Datei wird beim Schreiben noch einmal gelesen, und ihr SHA-256 steht erst nach dem Schreiben wieder fest. Bewahren Sie die Datei dort auf, wo kein anderer Benutzer sie ändern kann.

Eine Image-Datei für eine virtuelle Maschine

--output <file> schreibt das Image und die Dateien des Geräts statt auf ein Laufwerk in eine reguläre Datei: ein Raw-Disk-Image, von dem eine virtuelle Maschine als ihrer Festplatte startet. Das Image, seine Prüfungen und die Dateien in IRONFLOCKOS sind dieselben wie bei einem Laufwerk. Kein Laufwerk wird gesucht, ausgehängt oder geöffnet, daher braucht der Befehl keine Root-Rechte. --image, --image-file, --installer mit seinen Flags und --wifi-ssid funktionieren wie bei einem Laufwerk.

• Größe — Der Plan nennt die Datei und ihre Größe: die Größe des entpackten Images. Muss das Image erst noch heruntergeladen werden, folgt diese Zeile nach dem Download.
• Frage — Eine neue Datei löscht nichts, und der Befehl fragt nicht. Eine vorhandene Datei wird ersetzt: Der Plan sagt das, und der Befehl fragt vorher.
• Zuerst unter einem anderen Namen — Das Image kommt in eine neue Datei im selben Ordner, <file>.<number>.part. Den Namen <file> erhält sie erst, wenn sie das ganze Image enthält, zurückgelesen wurde und die Dateien des Geräts in ihrer Partition IRONFLOCKOS hat. Ein Schreiben, das fehlschlägt oder unterbrochen wird, entfernt die .part-Datei, und unter dem Namen liegt nichts oder unverändert die Datei, die vorher dort lag. Ein kill -9 oder ein Stromausfall kann die .part-Datei zurücklassen.
• Privat — Die Datei enthält das Secret des Geräts, wie die .flock-Datei. Sie erhält Modus 0600, auch wenn sie eine Datei mit weiter gefasstem Modus ersetzt.
• Sparse — Wo das Image einen ganzen Block aus Nullen hat (Blöcke von 4 MiB), erhält die Datei auf einem Dateisystem, das Löcher unterstützt, ein Loch. Sie liest sich gleich und belegt weniger Platz.

# Eine Disk-Image-Datei für eine virtuelle Maschine schreiben, ohne Root-Rechte
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.

Das Image enthält die Partition IRONFLOCKOS und den ersten der zwei System-Slots, die IronFlockOS abwechselnd aktualisiert (Slot A). Bei seinem ersten Boot legt IronFlockOS Slot B an, so groß wie Slot A, und die Datenpartition /data über den Rest der Festplatte. Vergrößern Sie die Datei, bevor die virtuelle Maschine zum ersten Mal davon startet: auf mindestens 10 GiB für base und 18 GiB für nvidia. Was die Datei hinzugewinnt, sind Nullen, die das Dateisystem als Loch speichert. Ein Hypervisor, der Raw-Festplatten annimmt, verwendet die Datei unverändert. Für ein anderes Format wandeln Sie die vergrößerte Datei um, etwa mit qemu-img convert -f raw -O qcow2 device.img device.qcow2.

Die Images von amd64-efi und arm64-efi starten in QEMU, das Image des Raspberry Pi (rpi-arm64) nicht. Für amd64-efi unter Linux mit KVM und der UEFI-Firmware aus dem Paket ovmf (Debian, Ubuntu):

# Die Datei vergrößern, die Variablen der Firmware kopieren und die Maschine starten
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 legt die erste serielle Schnittstelle auf das Terminal, wohin GRUB und der Kernel schreiben. Strg+A X beendet QEMU.
• -device i6300esb ist ein Watchdog, über den IronFlockOS eine Maschine neu startet, die hängt.
• -netdev user gibt der Maschine das Netzwerk des Hosts, über das das Gerät IronFlock erreicht.
• Ohne KVM (kein /dev/kvm oder ein Host einer anderen Architektur) lassen Sie -accel kvm weg und verwenden -cpu max. QEMU emuliert die Maschine dann, was viel langsamer ist.

arm64-efi startet mit qemu-system-aarch64 -machine virt und der Firmware aus dem Paket qemu-efi-aarch64 (/usr/share/AAVMF/AAVMF_CODE.fd und eine Kopie von AAVMF_VARS.fd), ohne den Watchdog. Auf einem Mac mit Apple Silicon startet QEMU aus Homebrew es mit -accel hvf -cpu host und der Firmware /opt/homebrew/share/qemu/edk2-aarch64-code.fd, mit einer Kopie von edk2-arm-vars.fd.

Beispiele

# Das Standard-Image für die Hardware der .flock-Datei auf einen USB-Stick schreiben
sudo ironflock os flash -c device.flock -d /dev/sdb
# Einen Installer-Stick schreiben, der das NVIDIA-Image auf einen PC installiert
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# Eine SD-Karte für ein Gerät schreiben, das sich mit dem WLAN „Workshop“ verbindet
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Einen Stick auf einem Mac schreiben
sudo ironflock os flash -c device.flock -d /dev/disk4

Ergebnis

Der Plan und der Fortschritt gehen auf stderr; die letzten Zeilen sind das Ergebnis. Unter 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.

Auf einem Mac, zuerst ohne Root-Rechte, dann mit 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.

Mit --json, hier für einen Installer-Stick (--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":[]}

Mit --output hat das Ergebnis output statt drive, zum Beispiel "output":{"file":"/home/anna/device.img","replaced":true}.

Wann der Befehl ablehnt

Exit-Code 3, und nichts wird geschrieben:

• Das Laufwerk ist eines, das os drives ablehnt; der Fehler nennt den Grund, und --yes ändert nichts. Die einzige Ausnahme ist eine interne Festplatte dieser Maschine: --allow-internal beschreibt sie, wenn --drive sie nennt, und der Fehler nennt das Flag, wenn es das Laufwerk beschreibbar machen würde. Das Flag hebt keine andere Ablehnung auf und beantwortet nicht die Frage.
• Das Laufwerk hat sich zwischen dem Plan und dem Schreiben geändert oder wird dann abgelehnt. Der Fehler sagt, was sich geändert hat.
• Das Laufwerk ist in Gebrauch, wenn es geöffnet wird: Ein Dateisystem ist eingehängt, das der Plan nicht aufgelistet hat, ein Dateisystem lässt sich nicht aushängen, oder ein Programm hält das Laufwerk.
• Der Befehl läuft nicht als root (oder unter macOS nicht als ein Benutzer, der das Raw-Device des Laufwerks beschreiben darf). Der Fehler nennt die Befehlszeile mit sudo.
• Mit --output: Der Name ist keine reguläre Datei (eine Gerätedatei, ein Ordner, eine Named Pipe oder ein beliebiger symbolischer Link), oder sein Ordner existiert nicht, bevor irgendetwas gelesen oder abgerufen wird. Ein Ordner, der keine neue Datei aufnimmt (keine Berechtigung, ein schreibgeschütztes Dateisystem), wird nach dem Plan und vor dem Download abgelehnt. Eine Datei, die den Namen eingenommen hat, während das Image geschrieben wurde, wo der Plan eine neue Datei genannt hat, wird nicht ersetzt.

Exit-Code 2, eine falsche Befehlszeile:

• Weder --drive noch --output, auch mit --allow-internal. --output mit --drive oder mit --allow-internal, ohne Namen oder mit -. Ein --output, das die .flock-Datei von -c oder die Datei von --image-file nennt.
• Ein --installer-*-Flag ohne --installer oder mit einem Wert, den der Installer nicht annimmt.
• --wifi-ssid ohne --wifi-password-file oder umgekehrt.
• Eine .flock-Datei, die nicht sagt, für welche Hardware sie ist; dann wählt --image das Image.
• Ein Image, das der Katalog nicht hat, ein Installer-Stick, der das Image nicht mitbringt, oder eine Hardware ohne Installer-Stick.
• Mit --host: --image-file und --output, da --host die Image-Datei nicht auf die andere Maschine kopiert und keine Datei zurückholt. Führen Sie den Befehl hier ohne --host aus oder auf der Maschine selbst. Die .flock-Datei und die Passphrasendatei gehen dagegen mit.

Exit-Code 4: Die Frage wurde mit Nein beantwortet (Enter allein oder Esc), oder sie konnte nicht gestellt werden, und --yes war nicht angegeben.

Exit-Code 1, der Befehl ist fehlgeschlagen:

• Die .flock-Datei oder die Passphrasendatei ist keine solche, oder die Image-Datei ist nicht die des Katalogs.
• Der Katalog ist nicht verwendbar, aus den Gründen, aus denen os images fehlschlägt.
• Der Download, das Schreiben oder das Zurücklesen schlägt fehl. Ein Schreiben, das nach seinem ersten Block fehlschlägt (ein E/A-Fehler, ein Laufwerk kleiner als das Image), sagt, dass das Laufwerk jetzt einen Teil des Images enthält, der nichts startet: Schreiben Sie es erneut.
• Das Image ist auf dem Laufwerk und zurückgelesen, aber die .flock-Datei ließ sich nicht in IRONFLOCKOS schreiben. Ohne sie registriert sich das Gerät nicht; derselbe Befehl schreibt beides erneut.
• Mit --output: Das Dateisystem ist voll, die Dateien des Geräts lassen sich nicht in das Image bringen, oder der Eintrag der .part-Datei wurde ersetzt, während das Image geschrieben wurde. Der Name ist dann so wie vorher.

Exit-Code 130: Strg+C, während das Image heruntergeladen, geschrieben oder zurückgelesen wird. Ein unterbrochener Download hat nichts geschrieben, und derselbe Befehl setzt ihn fort. Ein Schreiben oder Zurücklesen hält beim nächsten Block an, und der Fehler sagt, was das Laufwerk enthält. Sobald der letzte Block zurückgelesen ist, führt der Befehl seine letzten kurzen Schritte zu Ende und endet mit 0. Ein zweites Strg+C beendet den Befehl sofort; mit --output kann es die .part-Datei zurücklassen.