Écrire IronFlockOS sur un lecteur

ironflock os flash prépare le lecteur à partir duquel démarre un nouvel appareil. La commande écrit IronFlockOS et le fichier de configuration de l’appareil (.flock) sur le lecteur, et l’appareil s’enrôle à son premier démarrage : il se connecte à IronFlock en tant qu’appareil de ce fichier .flock. Vous pouvez préparer :

• une clé USB, une carte SD ou un disque externe à partir duquel l’appareil démarre,
• une clé d’installation qui installe IronFlockOS sur le disque interne d’un PC,
• un fichier image disque à partir duquel démarre une machine virtuelle.

FlockFlasher est l’application de bureau qui fait le même travail. Pour obtenir le fichier .flock d’un appareil, voir Connecter des appareils.

Déroulement type

# 1. Brancher la clé ou la carte SD, puis lister les lecteurs sur lesquels l'écriture est possible
ironflock os drives
# 2. Facultatif : lister les images que propose le catalogue
ironflock os images
# 3. Écrire IronFlockOS et le fichier .flock de l'appareil sur le lecteur
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash affiche son plan et pose la question avant d’effacer le lecteur. Une fois l’écriture terminée, insérez le lecteur dans l’appareil et démarrez l’appareil à partir de celui-ci.

ironflock os images

Liste les images IronFlockOS qui peuvent être écrites sur un lecteur. Par défaut, la commande liste les images de la version du canal de production.

ironflock os images [flags]

S’exécute sous Linux et macOS. Ne nécessite pas root. Ne pose aucune question.

Options

Les options valables pour chaque commande sont décrites dans Options, sortie et codes de sortie.

Ce que fait la commande

La liste provient du catalogue IronFlockOS signé du serveur de téléchargement, <download base>/ironflockos/manifest.json. ironflock n’utilise le catalogue que lorsque sa signature Ed25519 se vérifie avec la clé du catalogue intégrée à ironflock. FlockFlasher et l’agent de l’appareil épinglent la même clé. Aucune option et aucune variable d’environnement ne désactive cette vérification. La base de téléchargement est le cloud IronFlock, sauf si vous en indiquez une autre ; voir Base de téléchargement.

Le dernier catalogue vérifié est conservé dans un dossier de cache, une copie par base de téléchargement :

Lorsque le serveur de téléchargement ne peut pas être joint, la copie conservée le remplace, avec une remarque sur stderr. Un catalogue de la même base de téléchargement plus ancien que la copie conservée est refusé.

Une image est nommée d’après sa cible matérielle, sa variante et son noyau : ironflockos-<target>-<variant>, avec -rt pour le noyau temps réel. ironflockos-amd64-efi-base-rt est le système de base avec le noyau temps réel pour les PC x86-64 avec UEFI. Les cibles sont :

• amd64-efi — PC x86-64 avec UEFI
• arm64-efi — machine ARM64 avec UEFI
• rpi-arm64 — Raspberry Pi 4, 400 et CM4 ; Raspberry Pi 5 et CM5

Les variantes sont base, nvidia et installer. L’image d’installation crée une clé USB qui installe l’une des images qu’elle contient sur le disque de la machine qui démarre à partir d’elle. Une image d’une variante, d’un noyau ou d’une architecture que cet ironflock ne connaît pas (issue d’une version plus récente) est omise, avec une remarque sur stderr.

Exemples

# Les images de la version de production actuelle
ironflock os images
# Uniquement les images pour Raspberry Pi
ironflock os images --target rpi-arm64
# Les images du canal de test, en JSON
ironflock os images --channel test --json

Résultat

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

Avec --json (ici avec --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 et key_id décrivent le catalogue, channels nomme la version de chaque canal, et from_cache vaut true lorsque le serveur de téléchargement n’a pas répondu. Chaque image a son file avec son url, sa size et son sha256. boards sont les modèles de carte que nomme un fichier .flock (board.model), et hardware leurs noms. Une image d’installation a aussi payloads, les identifiants des images qu’elle contient.

Cas d’échec

• Code de sortie 2 — --channel et --version ensemble, une version qui n’en est pas une, ou un canal, une version, une cible, une variante ou un noyau que le catalogue ne contient pas. L’erreur nomme ce que contient le catalogue.
• Code de sortie 1 — le catalogue ne se vérifie pas, dépasse 64 Kio, n’est pas un catalogue que cet ironflock sait lire, ou est plus ancien que la copie conservée ; ou il ne peut pas être récupéré et aucune copie n’est conservée.

ironflock os drives

Liste les lecteurs de cette machine sur lesquels une image IronFlockOS peut être écrite : clés USB, cartes SD, disques externes. La commande n’écrit sur aucun lecteur, n’en démonte aucun et n’en ouvre aucun.

ironflock os drives [flags]

S’exécute sous Linux et macOS. Ne nécessite pas root. Ne pose aucune question. Sous Linux, la commande exécute lsblk (de util-linux) et lit /proc et /sys. Sous macOS, elle exécute diskutil list, diskutil info et hdiutil info.

Options

Les options valables pour chaque commande sont décrites dans Options, sortie et codes de sortie.

Lecteurs refusés

os flash refuse les lecteurs que refuse os drives, pour les mêmes raisons. Un lecteur est refusé lorsqu’il (la raison affichée est la première qui s’applique) :

1. est une partition, comme /dev/sdb1. Le refus nomme son disque : une image s’écrit sur le disque entier.
2. n’est pas un disque : un lecteur optique, un disque en mémoire (zram), un volume construit sur d’autres lecteurs (LVM, dm-crypt, RAID, device-mapper ; sous macOS, un conteneur APFS, un ensemble AppleRAID ou un autre disque synthétisé), ou un type de périphérique que la commande ne connaît pas (nbd, mtdblock).
3. contient une partie du système en cours d’exécution : /, /boot, /efi, /usr, /var, /etc ou un point de montage situé sous l’un d’eux (la partition EFI sous /boot/efi, les données de Docker sous /var/lib/docker), /home, /opt, /srv, /data, le swap, ou le support d’un système live. Cela vaut quelle que soit la façon dont le système se trouve sur le lecteur : dans une partition, via LVM, dm-crypt, RAID ou device-mapper, dans un système de fichiers btrfs réparti sur plusieurs lecteurs, dans un pool ZFS, dans un overlay, ou dans un fichier que lit un périphérique loop. Sous macOS : / et les volumes sous /System, à travers leurs conteneurs APFS jusqu’au disque qui les contient.
4. est utilisé : par LVM, dm-crypt, RAID ou device-mapper, par un pool ZFS dont un jeu de données est monté, ou par un périphérique loop qui lit un fichier situé sur le lecteur. Sous macOS, également par un conteneur APFS qui s’y trouve, un ensemble AppleRAID, une image disque dont le fichier s’y trouve, ou par Core Storage, AppleRAID ou un conteneur APFS non attaché. macOS ne libère une clé contenant un conteneur APFS que lorsque la clé est effacée : la raison nomme donc la commande qui l’efface, par exemple diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6 (ou Effacer dans Utilitaire de disque).
5. est un disque interne de la machine : un disque SATA ou NVMe, l’eMMC d’une carte. Un lecteur est interne sauf s’il est raccordé par USB ou par un autre bus dont les périphériques peuvent être débranchés. Un lecteur de cartes intégré est interne, mais sa carte SD est un support amovible et elle est proposée, sur un Mac aussi. Sous macOS, un disque qui n’indique pas où il se trouve compte comme interne. os flash --allow-internal écrit sur un disque interne que désigne --drive, lorsqu’aucune autre raison ne le refuse.
6. peut contenir une partie du système en cours d’exécution : lorsqu’une partie du système en cours d’exécution ne peut pas être rattachée à un lecteur, chaque lecteur est refusé. C’est le cas dans un conteneur, dont le système se trouve sur son hôte, et sous macOS pour un système situé sur un volume qui n’aboutit à aucun disque physique, comme Core Storage.
7. est en lecture seule, comme une carte SD verrouillée.
8. n’a pas de support, comme un lecteur de cartes sans carte.

Un lecteur dont des systèmes de fichiers sont montés est proposé ; mounted les liste, et os flash les démonte avant d’écrire. Les périphériques loop et, sous macOS, les images disque attachées ne sont pas listés, mais os flash écrit sur un tel périphérique lorsque --drive le désigne.

Sur un appareil qui tourne sous IronFlockOS, la commande émet un avertissement sur stderr et dans warnings : chaque image IronFlockOS d’une cible a les mêmes UUID de partition ; tant qu’un second lecteur IronFlockOS est branché, le système en cours d’exécution ne peut donc pas distinguer ses propres partitions de celles du lecteur.

Exemples

# Les lecteurs sur lesquels l'écriture est possible
ironflock os drives
# Tous les lecteurs, avec la raison de chaque refus
ironflock os drives --all
# Les lecteurs en JSON
ironflock os drives --json

Résultat

Sous Linux :

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

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

Sur un Mac, avec --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

Avec --json (raccourci) :

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

Lorsqu’il n’y a aucun lecteur sur lequel écrire, le texte le dit, drives est vide et le code de sortie est 0.

Cas d’échec

• Code de sortie 3 — sous Linux, lsblk n’est pas installé ; ou la commande s’exécute sur un autre système que Linux ou macOS.

ironflock os flash

Écrit IronFlockOS sur un lecteur (une clé USB, une carte SD, un disque externe) et place le fichier .flock de l’appareil dans la partition IRONFLOCKOS du lecteur, la partition FAT32 de ce nom que possède chaque lecteur IronFlockOS. L’appareil s’enrôle avec ce fichier à son premier démarrage. Avec --output, la commande écrit la même chose dans un fichier image disque pour une machine virtuelle.

Avertissement : Tout ce qui se trouve sur le lecteur est effacé. Vérifiez le nom du lecteur avec ironflock os drives avant d’écrire. os flash ne choisit jamais de lecteur à votre place.

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

Sans root, l’erreur indique la ligne de commande à taper, précédée de sudo. Sous macOS, un utilisateur autorisé à écrire sur le périphérique brut du lecteur n’a pas besoin de root : l’utilisateur qui a attaché une image disque, ou un utilisateur à qui le propriétaire de la machine a attribué le lecteur, par exemple avec sudo chown <user> /dev/disk4 /dev/rdisk4. Avec --output, la commande ne nécessite pas root. Voir aussi Privilèges root.

Options

Les options valables pour chaque commande sont décrites dans Options, sortie et codes de sortie.

Ce que fait la commande

1. Elle vérifie le lecteur. Elle résout --drive et le refuse pour les raisons que donne os drives, avant de lire, de récupérer ou de demander quoi que ce soit. Sans --drive (et sans --output), elle nomme les lecteurs sur lesquels elle peut écrire et se termine avec le code de sortie 2.
2. Elle lit le fichier .flock. Ce doit être un fichier nommé *.flock d’au plus 5 Mio, un objet JSON avec un secret et un device_key, dont le name et le serial_number sont des noms simples.
3. Elle choisit l’image dans le catalogue signé, qu’elle récupère et vérifie comme le fait os images. Elle prend l’image que nomme --image, sinon l’image par défaut (variante base, noyau standard) du matériel que nomme le fichier .flock : son board.model, sinon son architecture lorsque le catalogue a un seul matériel pour celle-ci. Avec --installer, elle prend la clé d’installation de ce matériel qui contient l’image.
4. Elle affiche le plan sur stderr : l’image, la provenance de son fichier, le fichier .flock (par son nom), le WiFi, le lecteur, et les systèmes de fichiers du lecteur qu’elle démonte. Elle pose ensuite la question. « No » est présélectionné : Entrée seule n’efface donc rien.
5. Elle obtient le fichier image : le fichier de --image-file, sinon la copie du cache, sinon un téléchargement dans le cache, repris là où un téléchargement antérieur s’est arrêté. En tant que root, le cache est /var/cache/ironflock/images sous Linux et /var/root/Library/Caches/ironflock/images sous macOS. Le téléchargement va dans un fichier .part. Chaque fichier n’est écrit que lorsque sa taille et son SHA-256 sont ceux du catalogue. Une tentative de téléchargement qui n’apporte aucun octet pendant une minute prend fin, et le téléchargement abandonne après trois tentatives de ce type d’affilée.
6. Elle vérifie à nouveau le lecteur. Ce doit être le lecteur que le plan a affiché, et il ne doit toujours pas être refusé : même périphérique, même taille, même numéro de série et même support. Sous Linux, cela comprend le fabricant, le modèle, le bus et chaque partition avec son système de fichiers, son étiquette, son UUID et sa taille. Sous macOS, qui n’indique pas de numéro de série, ce sont le modèle, le bus, la place dans l’arborescence des périphériques et les partitions avec leurs UUID. Une clé retirée depuis le plan laisse son nom au prochain lecteur branché ; la commande n’écrit pas sur un tel lecteur, et rien n’est démonté. La commande démonte ensuite les systèmes de fichiers que le plan a listés, et seulement ceux-là, puis ouvre le lecteur en écriture exclusive. Sous macOS, elle écrit via le périphérique brut (/dev/rdisk4), qu’un second os flash ne peut pas ouvrir en même temps.
7. Elle écrit l’image, puis relit le lecteur et compare.
8. Elle écrit le fichier .flock dans le dossier racine de la partition IRONFLOCKOS, sans la monter. Une clé d’installation reçoit aussi installer.conf. Avec --wifi-ssid, la copie sur le lecteur nomme ce réseau ; le fichier .flock lui-même n’est pas modifié.
9. Sous macOS, elle éjecte le lecteur (diskutil eject), afin que vous puissiez le retirer. Lorsque l’éjection échoue, le lecteur est tout de même écrit : la commande émet un avertissement, et vous éjectez le lecteur dans le Finder avant de le retirer.

En tant que root, la commande n’utilise un dossier de cache que s’il s’agit d’un dossier et non d’un lien, qu’il appartient à root et que personne d’autre ne peut y écrire. Elle crée un dossier manquant avec le mode 0700 et s’arrête devant tout autre cas, avant d’y lire, d’y supprimer ou d’y télécharger quoi que ce soit. Avant de récupérer une image du catalogue, elle supprime les fichiers image du cache que le catalogue ne liste plus, ainsi que leurs téléchargements partiels.

Une --image pour un autre matériel que celui que nomme le fichier .flock est écrite après un avertissement dans le plan : l’appareil n’exécuterait pas ses apps. Sur un appareil qui tourne sous IronFlockOS, le plan émet le même avertissement que os drives. Avec --allow-internal, le plan avertit que le lecteur est un disque interne.

--yes répond oui à la question. Sans terminal (un pipe, un script) et sans --yes, la commande ne pose pas la question et se termine avec le code de sortie 4. --json ne pose aucune question non plus : il faut donc --yes pour écrire sur un lecteur. Avec --json, le plan n’est pas affiché : stderr ne transporte que les événements de progression, et les avertissements figurent dans le résultat. Voir Questions et confirmation et Sortie et JSON.

WiFi

L’appareil rejoint le WiFi que nomme son fichier .flock. --wifi-ssid lui donne un autre réseau. IronFlockOS ne rejoint qu’un WiFi protégé par une phrase secrète : --wifi-ssid et --wifi-password-file vont donc toujours ensemble. La phrase secrète provient d’un fichier ou d’un pipe, jamais de la ligne de commande, où ps et l’historique du shell l’afficheraient. La commande ne l’affiche nulle part. La copie du fichier .flock sur le lecteur nomme le réseau dans wlanssid et password.

Note : Lorsque la phrase secrète arrive par /dev/stdin, stdin n’est pas un terminal : la commande ne peut donc pas poser de question. Ajoutez --yes.

Clé d’installation

Avec --installer, le lecteur devient une clé d’installation pour un PC avec UEFI (amd64-efi, arm64-efi) ; ironflock os images --variant installer liste les images d’installation. La clé contient plusieurs images de son matériel ; installer.conf sur la clé nomme celle qu’elle installe (payload, l’image choisie comme à l’étape 3) et contient les options --installer-* que vous avez données. Lorsque le PC démarre à partir de la clé, l’installateur :

1. choisit le disque selon --installer-disk : le plus grand disque (par défaut), le disque /dev/<name>, ou le disque dont l’identifiant est by-id:<id>. Il n’écrit sur un disque USB qu’avec --installer-allow-usb yes.
2. pose la question sur la console du PC avant d’écrire, sauf avec --installer-confirm no.
3. écrit l’image et le fichier .flock de l’appareil sur ce disque.
4. éteint le PC (par défaut), ou le redémarre avec --installer-after reboot.

Retirez la clé et démarrez le PC à partir de son disque interne. L’appareil s’enrôle à son premier démarrage.

Avertissement : Une clé écrite avec --installer-confirm no efface, sans poser de question, le disque de chaque PC qui démarre à partir d’elle. Étiquetez une telle clé et tenez-la à l’écart des autres machines.

Pour remplacer le Linux d’une machine en fonctionnement sans clé, voir Remplacer Linux par IronFlockOS.

Un fichier image téléchargé

--image-file écrit un fichier image que vous avez téléchargé au préalable, par exemple sur une machine qui ne peut pas télécharger les fichiers image du catalogue. Prenez l’adresse du fichier dans l’url de os images --json. Le fichier n’est écrit que lorsqu’il a la taille et le SHA-256 que le catalogue indique pour l’image.

La commande a tout de même besoin du catalogue signé pour vérifier le fichier. Elle récupère le catalogue ou, lorsque le serveur de téléchargement ne peut pas être joint, utilise la copie qu’elle a conservée la dernière fois qu’un catalogue de la même base de téléchargement a été vérifié. Cette copie est propre à chaque utilisateur : en tant que root, c’est la copie de root. Votre propre serveur fonctionne aussi : avec une autre base de téléchargement (--download-base ou IRONFLOCK_DL_BASE), la commande récupère le catalogue depuis <download base>/ironflockos/manifest.json et le fichier image depuis <download base>/ironflockos/<version>/<file>.

Note : Le fichier est lu une seconde fois pendant l’écriture, et son SHA-256 n’est de nouveau connu qu’après l’écriture. Conservez le fichier là où aucun autre utilisateur ne peut le modifier.

Un fichier image pour une machine virtuelle

--output <file> écrit l’image et les fichiers de l’appareil dans un fichier ordinaire au lieu d’un lecteur : une image disque brute à partir de laquelle une machine virtuelle démarre comme depuis son disque. L’image, ses vérifications et les fichiers dans IRONFLOCKOS sont les mêmes que pour un lecteur. Aucun lecteur n’est recherché, démonté ni ouvert : la commande ne nécessite donc pas root. --image, --image-file, --installer avec ses options, et --wifi-ssid fonctionnent comme avec un lecteur.

• Taille — Le plan nomme le fichier et sa taille : la taille de l’image décompressée. Lorsque l’image reste à télécharger, cette ligne suit le téléchargement.
• Question — Un nouveau fichier n’efface rien, et la commande ne pose pas de question. Un fichier existant est remplacé : le plan le dit, et la commande pose d’abord la question.
• D’abord sous un autre nom — L’image va dans un nouveau fichier du même dossier, <file>.<number>.part. Celui-ci ne prend le nom <file> que lorsqu’il contient l’image entière, qu’il a été relu et que les fichiers de l’appareil se trouvent dans sa partition IRONFLOCKOS. Une écriture qui échoue ou qui est interrompue supprime le fichier .part, et sous le nom il n’y a rien, ou le fichier qui s’y trouvait, inchangé. Un kill -9 ou une coupure de courant peut laisser le fichier .part derrière lui.
• Privé — Le fichier contient le secret de l’appareil, comme le fichier .flock. Il reçoit le mode 0600, y compris lorsqu’il remplace un fichier au mode plus permissif.
• Creux — Là où l’image contient un bloc entier de zéros (blocs de 4 Mio), le fichier reçoit un trou sur un système de fichiers qui prend en charge les trous. Il se lit de la même façon et occupe moins de place.

# Écrire un fichier image disque pour une machine virtuelle, sans 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’image contient la partition IRONFLOCKOS et le premier des deux slots système qu’IronFlockOS met à jour à tour de rôle (slot A). À son premier démarrage, IronFlockOS crée le slot B, aussi grand que le slot A, et la partition de données /data sur le reste du disque. Agrandissez le fichier avant que la machine virtuelle ne démarre pour la première fois à partir de lui : à au moins 10 Gio pour base et 18 Gio pour nvidia. Ce que le fichier gagne, ce sont des zéros, que le système de fichiers conserve sous forme de trou. Un hyperviseur qui accepte les disques bruts utilise le fichier tel quel. Pour un autre format, convertissez le fichier agrandi, par exemple avec qemu-img convert -f raw -O qcow2 device.img device.qcow2.

Les images de amd64-efi et de arm64-efi démarrent dans QEMU ; l’image du Raspberry Pi (rpi-arm64) non. Pour amd64-efi sous Linux avec KVM et le firmware UEFI du paquet ovmf (Debian, Ubuntu) :

# Agrandir le fichier, copier les variables du firmware et démarrer la machine
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 place le premier port série sur le terminal, où écrivent GRUB et le noyau. Ctrl-A X quitte QEMU.
• -device i6300esb est un watchdog, par lequel IronFlockOS redémarre une machine qui se bloque.
• -netdev user donne à la machine le réseau de l’hôte, par lequel l’appareil joint IronFlock.
• Sans KVM (pas de /dev/kvm, ou un hôte d’une autre architecture), omettez -accel kvm et utilisez -cpu max. QEMU émule alors la machine, ce qui est beaucoup plus lent.

arm64-efi démarre avec qemu-system-aarch64 -machine virt et le firmware du paquet qemu-efi-aarch64 (/usr/share/AAVMF/AAVMF_CODE.fd, et une copie de AAVMF_VARS.fd), sans le watchdog. Sur un Mac avec Apple silicon, le QEMU de Homebrew démarre cette image avec -accel hvf -cpu host et le firmware /opt/homebrew/share/qemu/edk2-aarch64-code.fd, avec une copie de edk2-arm-vars.fd.

Exemples

# Écrire l'image par défaut pour le matériel du fichier .flock sur une clé USB
sudo ironflock os flash -c device.flock -d /dev/sdb
# Écrire une clé d'installation qui installe l'image NVIDIA sur un PC
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# Écrire une carte SD pour un appareil qui rejoint le WiFi « Workshop »
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Écrire une clé sur un Mac
sudo ironflock os flash -c device.flock -d /dev/disk4

Résultat

Le plan et la progression vont sur stderr ; les dernières lignes sont le résultat. Sous 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.

Sur un Mac, d’abord sans root, puis avec 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.

Avec --json, ici pour une clé d’installation (--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":[]}

Avec --output, le résultat contient output au lieu de drive, par exemple "output":{"file":"/home/anna/device.img","replaced":true}.

Cas de refus

Code de sortie 3, et rien n’est écrit :

• Le lecteur fait partie de ceux que refuse os drives ; l’erreur donne la raison, et --yes n’y change rien. La seule exception est un disque interne de cette machine : --allow-internal écrit dessus lorsque --drive le désigne, et l’erreur nomme l’option lorsque celle-ci rendrait le lecteur inscriptible. L’option ne lève aucun autre refus et ne répond pas à la question.
• Le lecteur a changé entre le plan et l’écriture, ou il est refusé à ce moment-là. L’erreur dit ce qui a changé.
• Le lecteur est utilisé au moment où il est ouvert : un système de fichiers que le plan n’a pas listé est monté, un système de fichiers ne se démonte pas, ou un programme tient le lecteur.
• La commande ne s’exécute pas en tant que root (ou, sous macOS, sous un utilisateur autorisé à écrire sur le périphérique brut du lecteur). L’erreur nomme la ligne de commande avec sudo.
• Avec --output, avant que quoi que ce soit ne soit lu ou récupéré : le nom n’est pas un fichier ordinaire (un périphérique, un dossier, un pipe nommé ou un lien symbolique, quel qu’il soit), ou son dossier n’existe pas. Un dossier qui n’accepte aucun nouveau fichier (pas d’autorisation, système de fichiers en lecture seule) est refusé après le plan et avant le téléchargement. Un fichier qui a pris le nom pendant l’écriture de l’image, alors que le plan nommait un nouveau fichier, n’est pas remplacé.

Code de sortie 2, une ligne de commande erronée :

• Ni --drive ni --output, y compris avec --allow-internal. --output avec --drive ou avec --allow-internal, sans nom, ou avec -. Un --output qui désigne le fichier .flock de -c ou le fichier de --image-file.
• Une option --installer-* sans --installer, ou avec une valeur que l’installateur n’accepte pas.
• --wifi-ssid sans --wifi-password-file, ou inversement.
• Un fichier .flock qui n’indique pas à quel matériel il est destiné ; --image choisit alors l’image.
• Une image que le catalogue ne contient pas, une clé d’installation qui ne contient pas l’image, ou un matériel sans clé d’installation.
• Avec --host : --image-file et --output, car --host ne copie pas le fichier image sur l’autre machine et ne rapporte aucun fichier. Exécutez la commande ici sans --host, ou sur la machine elle-même. Le fichier .flock et le fichier de phrase secrète, eux, sont bien transmis.

Code de sortie 4 : la question a reçu la réponse non (Entrée seule ou Échap), ou elle n’a pas pu être posée et --yes n’a pas été donné.

Code de sortie 1, la commande a échoué :

• Le fichier .flock ou le fichier de phrase secrète n’en est pas un, ou le fichier image n’est pas celui du catalogue.
• Le catalogue ne peut pas être utilisé, pour les raisons qui font échouer os images.
• Le téléchargement, l’écriture ou la relecture échoue. Une écriture qui échoue après son premier bloc (une erreur d’E/S, un lecteur plus petit que l’image) indique que le lecteur contient maintenant une partie de l’image, qui ne démarre rien : écrivez-le à nouveau.
• L’image est sur le lecteur et relue, mais le fichier .flock n’a pas pu être écrit dans IRONFLOCKOS. Sans lui, l’appareil ne s’enrôle pas ; la même commande écrit à nouveau les deux.
• Avec --output : le système de fichiers est plein, les fichiers de l’appareil ne peuvent pas être placés dans l’image, ou l’entrée du fichier .part a été remplacée pendant l’écriture de l’image. Le nom est alors tel qu’il était auparavant.

Code de sortie 130 : Ctrl-C pendant le téléchargement, l’écriture ou la relecture de l’image. Un téléchargement interrompu n’a rien écrit, et la même commande le reprend. Une écriture ou une relecture s’arrête au bloc suivant, et l’erreur dit ce que contient le lecteur. Une fois le dernier bloc relu, la commande achève ses dernières étapes, qui sont courtes, et se termine avec 0. Un second Ctrl-C met fin à la commande immédiatement ; avec --output, il peut laisser le fichier .part derrière lui.