Write IronFlockOS to a Drive

ironflock os flash prepares the drive a new device starts from. It writes IronFlockOS and the device configuration file (.flock) to the drive, and the device enrolls at its first boot: it connects to IronFlock as the device of that .flock file. You can prepare:

• a USB stick, an SD card or an external disk that the device starts from,
• an installer stick that installs IronFlockOS on the internal disk of a PC,
• a disk image file that a virtual machine starts from.

FlockFlasher is the desktop app for the same job. To get the .flock file of a device, see Connect Devices.

Typical Run

# 1. Plug in the stick or SD card, then list the drives that may be written
ironflock os drives
# 2. Optional: list the images the catalog offers
ironflock os images
# 3. Write IronFlockOS and the device's .flock file to the drive
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash shows its plan and asks before it erases the drive. When it is done, put the drive into the device and start the device from it.

ironflock os images

Lists the IronFlockOS images that can be written to a drive. By default it lists the images of the release on the production channel.

ironflock os images [flags]

Runs on Linux and macOS. Needs no root. Asks nothing.

Flags

The flags of every command are on Flags, Output & Exit Codes.

What It Does

The list comes from the signed IronFlockOS catalog of the download server, <download base>/ironflockos/manifest.json. ironflock uses the catalog only when its Ed25519 signature verifies against the catalog key built into ironflock. FlockFlasher and the device agent pin the same key. No flag and no environment variable turns this check off. The download base is the IronFlock cloud unless you name another one, see Download Base.

The last catalog that verified is kept in a cache folder, one copy per download base:

When the download server cannot be reached, the kept copy stands in for it, with a note on stderr. A catalog of the same download base that is older than the kept copy is refused.

An image is named after its hardware target, its variant and its kernel: ironflockos-<target>-<variant>, with -rt for the real-time kernel. ironflockos-amd64-efi-base-rt is the base system with the real-time kernel for x86-64 PCs with UEFI. The targets are:

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

The variants are base, nvidia and installer. The installer image makes a USB stick that installs one of the images it carries on the disk of the machine that starts from it. An image of a variant, kernel or architecture that this ironflock does not know (from a newer release) is left out, with a note on stderr.

Examples

# The images of the current production release
ironflock os images
# Only the Raspberry Pi images
ironflock os images --target rpi-arm64
# The images of the test channel, as JSON
ironflock os images --channel test --json

Result

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

With --json (here with --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 and key_id describe the catalog, channels names the release of each channel, and from_cache is true when the download server did not answer. Each image has its file with its url, size and sha256. boards are the board models a .flock file names (board.model), and hardware are their names. An installer image also has payloads, the ids of the images it carries.

Fails When

• Exit code 2 — --channel and --version together, a version that is not one, or a channel, release, target, variant or kernel that the catalog does not have. The error names what the catalog has.
• Exit code 1 — the catalog does not verify, is larger than 64 KiB, is not one this ironflock can read, or is older than the kept copy; or it cannot be fetched and no copy is kept.

ironflock os drives

Lists the drives of this machine that an IronFlockOS image may be written to: USB sticks, SD cards, external disks. It writes, unmounts and opens no drive.

ironflock os drives [flags]

Runs on Linux and macOS. Needs no root. Asks nothing. On Linux it runs lsblk (from util-linux) and reads /proc and /sys. On macOS it runs diskutil list, diskutil info and hdiutil info.

Flags

The flags of every command are on Flags, Output & Exit Codes.

Which Drives Are Refused

os flash refuses the drives that os drives refuses, for the same reasons. A drive is refused when it (the first reason that applies is the one shown):

1. is a partition, such as /dev/sdb1. The refusal names its disk: an image goes onto the whole disk.
2. is not a disk: an optical drive, a disk in memory (zram), a volume built on other drives (LVM, dm-crypt, RAID, device-mapper; on macOS an APFS container, an AppleRAID set or another synthesized disk), or a kind of device the command does not know (nbd, mtdblock).
3. holds part of the running system: /, /boot, /efi, /usr, /var, /etc or a mount below one of these (the EFI partition at /boot/efi, Docker’s data at /var/lib/docker), /home, /opt, /srv, /data, swap, or the medium of a live system. This holds however the system sits on the drive: in a partition, through LVM, dm-crypt, RAID or device-mapper, in a btrfs file system across several drives, in a ZFS pool, in an overlay, or in a file that a loop device reads. On macOS: / and the volumes below /System, through their APFS containers down to the disk that holds them.
4. is in use: by LVM, dm-crypt, RAID or device-mapper, by a ZFS pool with a mounted data set, or by a loop device that reads a file on it. On macOS also by an APFS container on it, an AppleRAID set, a disk image whose file is on it, or by Core Storage, AppleRAID or an APFS container that is not attached. macOS lets go of a stick with an APFS container only when the stick is erased, so the reason names the command that erases it, for example diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6 (or Erase in Disk Utility).
5. is an internal disk of the machine: a SATA or NVMe disk, the eMMC of a board. A drive is internal unless it is attached through USB or another bus whose devices can be unplugged. A built-in card reader is internal, but its SD card is removable media and is offered, on a Mac too. On macOS a disk that does not say where it is counts as internal. os flash --allow-internal writes an internal disk that --drive names, when no other reason refuses it.
6. may hold part of the running system: when a part of the running system cannot be traced to a drive, every drive is refused. This is the case in a container, whose system is on its host, and on macOS for a system on a volume that reaches no physical disk, such as Core Storage.
7. is read-only, such as a locked SD card.
8. has no medium, such as a card reader without a card.

A drive with mounted file systems is offered; mounted lists them, and os flash unmounts them before it writes. Loop devices and, on macOS, attached disk images are not listed, but os flash writes one that --drive names.

On a device that runs IronFlockOS, the command warns on stderr and in warnings: every IronFlockOS image of a target has the same partition UUIDs, so while a second IronFlockOS drive is attached, the running system cannot tell its own partitions from the drive’s.

Examples

# The drives that may be written
ironflock os drives
# All drives, with the reason for each refused one
ironflock os drives --all
# The drives as JSON
ironflock os drives --json

Result

On Linux:

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

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

On a Mac, with --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

With --json (shortened):

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

When there is no drive to write to, the text says so, drives is empty and the exit code is 0.

Fails When

• Exit code 3 — on Linux, lsblk is not installed; or the command runs on a system other than Linux or macOS.

ironflock os flash

Writes IronFlockOS to a drive (a USB stick, an SD card, an external disk) and puts the device’s .flock file into the drive’s IRONFLOCKOS partition, the FAT32 partition of that name that every IronFlockOS drive has. The device enrolls with that file at its first boot. With --output, it writes the same into a disk image file for a virtual machine instead.

Warning: Everything on the drive is erased. Check the drive name with ironflock os drives before you write. os flash never chooses a drive itself.

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

Without root, the error names the command line to type, with sudo in front. On macOS a user who may write the drive’s raw device needs no root: the user who attached a disk image, or a user the machine’s owner gave the drive, for example with sudo chown <user> /dev/disk4 /dev/rdisk4. With --output, the command needs no root. See also Root Privileges.

Flags

The flags of every command are on Flags, Output & Exit Codes.

What It Does

1. Checks the drive. It resolves --drive and refuses it for the reasons os drives gives, before it reads, fetches or asks anything. Without --drive (and without --output), it names the drives it may write and ends with exit code 2.
2. Reads the .flock file. It must be a file named *.flock of at most 5 MiB, a JSON object with a secret and a device_key, whose name and serial_number are plain names.
3. Chooses the image from the signed catalog, which it fetches and verifies as os images does. It takes the image --image names, else the default image (base variant, standard kernel) of the hardware the .flock file names: its board.model, else its architecture when the catalog has one hardware for it. With --installer, it takes the installer stick of that hardware that carries the image.
4. Shows the plan on stderr: the image, where its file comes from, the .flock file (by its name), the WiFi, the drive, and the file systems of the drive it unmounts. Then it asks. “No” is preselected, so Enter alone erases nothing.
5. Gets the image file: the file of --image-file, else the copy in the cache, else a download into the cache, resumed where an earlier download stopped. As root, the cache is /var/cache/ironflock/images on Linux and /var/root/Library/Caches/ironflock/images on macOS. The download goes into a .part file. Each file is written only when its size and SHA-256 are the catalog’s. A download attempt that brings no byte for a minute ends, and the download gives up after three such attempts in a row.
6. Checks the drive again. It has to be the drive the plan showed and still not refused: the same device, size, serial and medium. On Linux that includes the vendor, the model, the bus and every partition with its file system, label, UUID and size. On macOS, which names no serial, it is the model, the bus, the place in the device tree and the partitions with their UUIDs. A stick that was pulled since the plan leaves its name to the next drive that is plugged in; such a drive is not written, and nothing is unmounted. Then the command unmounts the file systems the plan listed, and only those, and opens the drive exclusively for writing. On macOS it writes through the raw device (/dev/rdisk4), which a second os flash cannot open at the same time.
7. Writes the image, then reads the drive back and compares it.
8. Writes the .flock file into the root folder of the IRONFLOCKOS partition, without mounting it. An installer stick also gets installer.conf. With --wifi-ssid, the copy on the drive names that network; the .flock file itself is not changed.
9. On macOS, ejects the drive (diskutil eject), so that you can take it out. When the eject fails, the drive is written all the same: the command warns, and you eject the drive in the Finder before you take it out.

As root, the command uses a cache folder only when it is a folder and not a link, belongs to root and can be written by nobody else. It makes a missing one with mode 0700 and stops at any other before it reads, deletes or downloads anything there. Before it fetches an image of the catalog, it deletes the image files in the cache that the catalog no longer lists, and their partial downloads.

An --image for other hardware than the .flock file names is written after a warning in the plan: the device would not run its apps. On a device that runs IronFlockOS, the plan warns as os drives does. With --allow-internal, the plan warns that the drive is an internal disk.

--yes answers the question with yes. Without a terminal (a pipe, a script) and without --yes, the command does not ask and ends with exit code 4. --json asks nothing either, so it needs --yes to write a drive. With --json, the plan is not printed: stderr carries only the progress events, and the warnings are in the result. See Questions and Confirmation and Output and JSON.

WiFi

The device joins the WiFi that its .flock file names. --wifi-ssid gives it another network. IronFlockOS joins a WiFi with a passphrase only, so --wifi-ssid and --wifi-password-file always go together. The passphrase comes from a file or a pipe, never from the command line, where ps and the shell history would show it. The command prints it nowhere. The copy of the .flock file on the drive names the network in wlanssid and password.

Note: When the passphrase comes through /dev/stdin, stdin is no terminal, so the command cannot ask. Add --yes.

Installer Stick

With --installer, the drive becomes an installer stick for a PC with UEFI (amd64-efi, arm64-efi); ironflock os images --variant installer lists the installer images. The stick carries several images of its hardware; installer.conf on the stick names the one it installs (payload, the image chosen as in step 3) and holds the --installer-* flags you gave. When the PC starts from the stick, the installer:

1. chooses the disk by --installer-disk: the largest disk (default), the disk /dev/<name>, or the disk with the id by-id:<id>. It writes a USB disk only with --installer-allow-usb yes.
2. asks on the PC’s console before it writes, unless --installer-confirm no.
3. writes the image and the device’s .flock file onto that disk.
4. powers the PC off (default), or restarts it with --installer-after reboot.

Take the stick out and start the PC from its internal disk. The device enrolls at its first boot.

Warning: A stick written with --installer-confirm no erases the disk of every PC that starts from it, without asking. Label such a stick and keep it away from other machines.

To replace the Linux of a running machine without a stick, see Replace Linux with IronFlockOS.

A Downloaded Image File

--image-file writes an image file that you downloaded before, for example on a machine that cannot download the catalog’s image files. Take the file’s address from the url of os images --json. The file is written only when it has the catalog’s size and SHA-256 for the image.

The command still needs the signed catalog to check the file. It fetches the catalog, or, when the download server cannot be reached, uses the copy it kept the last time a catalog of the same download base verified. That copy is per user: as root, it is root’s copy. A server of your own works as well: with another download base (--download-base or IRONFLOCK_DL_BASE), the command fetches the catalog from <download base>/ironflockos/manifest.json and the image file from <download base>/ironflockos/<version>/<file>.

Note: The file is read once more while it is written, and its SHA-256 is known again only after the write. Keep the file where no other user can change it.

An Image File for a Virtual Machine

--output <file> writes the image and the device’s files into a regular file instead of a drive: a raw disk image that a virtual machine starts from as its disk. The image, its checks and the files in IRONFLOCKOS are the same as for a drive. No drive is looked for, unmounted or opened, so the command needs no root. --image, --image-file, --installer with its flags, and --wifi-ssid work as with a drive.

• Size — The plan names the file and its size: the size of the image unpacked. When the image is still to be downloaded, that line follows the download.
• Question — A new file erases nothing, and the command does not ask. A file that is there is replaced: the plan says so, and the command asks first.
• Under another name first — The image goes into a new file in the same folder, <file>.<number>.part. It gets the name <file> only when it holds the whole image, has been read back and has the device’s files in its IRONFLOCKOS partition. A write that fails or is interrupted removes the .part file, and under the name there is nothing, or the file that was there, unchanged. A kill -9 or a power loss can leave the .part file behind.
• Private — The file holds the device’s secret, as the .flock file does. It gets mode 0600, also when it replaces a file with a wider mode.
• Sparse — Where the image has a whole block of zeros (blocks of 4 MiB), the file gets a hole on a file system that supports holes. It reads the same and takes less space.

# Write a disk image file for a virtual machine, without 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.

The image holds the IRONFLOCKOS partition and the first of the two system slots that IronFlockOS updates in turn (slot A). On its first boot, IronFlockOS makes slot B, as large as slot A, and the data partition /data over the rest of the disk. Grow the file before the virtual machine first starts from it: to at least 10 GiB for base and 18 GiB for nvidia. What the file gains is zeros, which the file system keeps as a hole. A hypervisor that takes raw disks uses the file as it is. For another format, convert the grown file, for example with qemu-img convert -f raw -O qcow2 device.img device.qcow2.

The images of amd64-efi and arm64-efi start in QEMU; the image of the Raspberry Pi (rpi-arm64) does not. For amd64-efi on Linux with KVM and the UEFI firmware of the package ovmf (Debian, Ubuntu):

# Grow the file, copy the firmware's variables, and start the 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 puts the first serial port on the terminal, where GRUB and the kernel write. Ctrl-A X ends QEMU.
• -device i6300esb is a watchdog, through which IronFlockOS restarts a machine that hangs.
• -netdev user gives the machine the network of the host, over which the device reaches IronFlock.
• Without KVM (no /dev/kvm, or a host of another architecture), leave out -accel kvm and use -cpu max. QEMU then emulates the machine, which is much slower.

arm64-efi starts with qemu-system-aarch64 -machine virt and the firmware of the package qemu-efi-aarch64 (/usr/share/AAVMF/AAVMF_CODE.fd, and a copy of AAVMF_VARS.fd), without the watchdog. On a Mac with Apple silicon, QEMU from Homebrew starts it with -accel hvf -cpu host and the firmware /opt/homebrew/share/qemu/edk2-aarch64-code.fd, with a copy of edk2-arm-vars.fd.

Examples

# Write the default image for the .flock file's hardware to a USB stick
sudo ironflock os flash -c device.flock -d /dev/sdb
# Write an installer stick that installs the NVIDIA image on a PC
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# Write an SD card for a device that joins the WiFi "Workshop"
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Write a stick on a Mac
sudo ironflock os flash -c device.flock -d /dev/disk4

Result

The plan and the progress go to stderr; the last lines are the result. On 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.

On a Mac, first without root, then with 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.

With --json, here for an 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":[]}

With --output, the result has output instead of drive, for example "output":{"file":"/home/anna/device.img","replaced":true}.

Refuses When

Exit code 3, and nothing is written:

• The drive is one that os drives refuses; the error gives the reason, and --yes changes nothing. The one exception is an internal disk of this machine: --allow-internal writes it when --drive names it, and the error names the flag when it would make the drive writable. The flag lifts no other refusal and does not answer the question.
• The drive changed between the plan and the write, or is refused then. The error says what changed.
• The drive is in use when it is opened: a file system is mounted that the plan did not list, a file system does not unmount, or a program holds the drive.
• The command does not run as root (or, on macOS, as a user who may write the drive’s raw device). The error names the command line with sudo.
• With --output: the name is not a regular file (a device, a folder, a named pipe, or any symbolic link), or its folder does not exist, before anything is read or fetched. A folder that takes no new file (no permission, a read-only file system) is refused after the plan and before the download. A file that took the name while the image was written, where the plan named a new file, is not replaced.

Exit code 2, a wrong command line:

• Neither --drive nor --output, also with --allow-internal. --output with --drive or with --allow-internal, without a name, or with -. An --output that names the .flock file of -c or the file of --image-file.
• An --installer-* flag without --installer, or with a value the installer does not take.
• --wifi-ssid without --wifi-password-file, or the other way round.
• A .flock file that does not say which hardware it is for; --image chooses the image then.
• An image the catalog does not have, an installer stick that does not carry the image, or a hardware without an installer stick.
• With --host: --image-file and --output, because --host does not copy the image file to the other machine and brings no file back. Run the command here without --host, or on the machine itself. The .flock file and the passphrase file do go along.

Exit code 4: the question was answered with no (Enter alone or Esc), or it could not be asked and --yes was not given.

Exit code 1, the command failed:

• The .flock file or the passphrase file is not one, or the image file is not the catalog’s.
• The catalog cannot be used, for the reasons os images fails with.
• The download, the write or the read back fails. A write that fails after its first block (an I/O error, a drive smaller than the image) says that the drive now holds a part of the image, which starts nothing: write it again.
• The image is on the drive and read back, but the .flock file could not be written into IRONFLOCKOS. Without it, the device does not enroll; the same command writes both again.
• With --output: the file system is full, the device’s files cannot be put into the image, or the entry of the .part file was replaced while the image was written. The name is then as it was before.

Exit code 130: Ctrl-C while the image is downloaded, written or read back. An interrupted download has written nothing, and the same command resumes it. A write or read back stops at the next block, and the error says what the drive holds. Once the last block is read back, the command finishes its last short steps and ends with 0. A second Ctrl-C ends the command at once; with --output it can leave the .part file behind.