Update, Roll Back & Reset

These commands look after a device that runs IronFlockOS. os update installs a release, os rollback goes back to the release that ran before, and os reset makes the device a freshly written one again.

Root Slots and the Data Partition

The disk of an IronFlockOS device holds:

• Two root slots, A and B — each holds a complete IronFlockOS system. One runs. The other holds the system that ran before, or nothing yet on a freshly written device. RAUC, the update tool that IronFlockOS uses, writes a release into the slot that does not run and records which slot starts next.
• The data partition (/data) — the apps and their data, and the device agent with its copy of the device configuration file (.flock). Both systems use it, so an update or a rollback leaves the apps and their data as they are.
• The IRONFLOCKOS partition (mounted at /boot/efi) — a small FAT partition. The device enrolls with a .flock file it finds there at its start, and os reset writes its request there.

A new system has to prove itself: the device keeps it once the device agent has reached IronFlock from it and marked it good. A system that does not start, or does not get there, is left at the next restart for the one that ran before. ironflock status shows the slots:

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

Where the Commands Run

The three commands run on a device that runs IronFlockOS, need root and ask before they act. On another system (macOS, a Linux that is not IronFlockOS, the IronFlockOS installer stick) they end with exit code 3.

• On the device — the IronFlockOS releases after 0.15.0 carry ironflock. Log in to the device and run the command with sudo.
• From another computer — the IronFlockOS releases up to 0.15.0 do not carry ironflock. Run the command from a Linux or macOS computer with --host, as the device’s SSH user: the account that the .flock file sets up for the project owner, operator in the examples. --host copies ironflock to the device for the run and runs the command there through sudo.

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

os update and os rollback run on several devices at once (--host more than once, or --hosts) when --yes is given. os reset runs on one device at a time; on several it ends with exit code 2. The global flags are on the conventions page.

ironflock os update

Installs the release of IronFlockOS that the device’s channel offers into the root slot that does not run. The new system starts with the next restart, or at once with --reboot.

ironflock os update [flags]

The device’s channel is the one its device agent follows, from the environment of the agent’s .flock file: test on IronFlock’s test platform and production otherwise. When the catalog does not have the device’s channel, it is production. The download base is taken from --download-base, then from IRONFLOCK_DL_BASE, then from the update server (update_url) of the agent’s .flock file (on a device of an IronFlock appliance, the appliance’s download mirror, which is all such a device may reach), else it is the IronFlock cloud.

What it does, in this order:

1. Reads the signed IronFlockOS catalog and takes the update bundle of the device’s image in the release of the channel (or of --version).
2. Says which release runs in which slot, which release it installs, into which slot, what that slot holds now, and the size of the download. Then it asks.
3. Downloads the bundle into /var/cache/ironflockos, on the data partition. An interrupted download is resumed. The file is used only when its size and SHA-256 are the catalog’s.
4. Has RAUC install the bundle into the slot that does not run. RAUC checks the bundle’s signature, writes the slot and makes it the one that starts next. What the slot held before is overwritten. The bundle is removed once it is installed.
5. With --reboot, restarts the device into the new system.

The running system stays as it is until the restart. Apps and their data stay. The slot that runs now keeps its release, and the device goes back to it when the new release does not start or does not reach IronFlock.

Nothing is installed, and the exit code is 0, when the device runs the release already, and when the release is installed in the other slot already and waits for the restart. In the second case, --reboot asks and restarts the device.

# Install the release of the device's channel; it starts with the next restart
sudo ironflock os update
# Install it and restart into it, without a question
sudo ironflock os update --reboot --yes
# Install an older release of the catalog
sudo ironflock os update --version 0.13.0

Progress goes to stderr: the download and its check, then each step RAUC names. What os update --yes prints on a device that runs 0.13.0 in slot A:

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

With --json the installation is the progress phase installing, in percent. The result of os update --reboot --yes --json:

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

Refuses when, with exit code 3:

• it does not run as root, on a machine that does not run IronFlockOS, and on the installer stick.
• RAUC installs a bundle already, one that IronFlock Studio started through the agent or another call. RAUC installs one at a time.
• the release has no bundle for the device’s image.
• the release is older than the one that runs, unless --version names it. When the other slot holds that release, the message names os rollback.
• /var/cache/ironflockos has not got the space for what is still to download. The message lists the bundles of earlier updates in the folder, which you can delete.

Wrong command lines, exit code 2: --channel and --version together, a version that is not one, a channel or release that the catalog does not have.

Fails when, with exit code 1: the catalog does not verify or cannot be read; the download breaks off (what arrived stays in /var/cache/ironflockos, and the same command resumes it); the download is not the catalog’s file; RAUC refuses the bundle or fails to install it. The error gives RAUC’s reason. When RAUC had begun to write, the slot is marked bad and holds no usable system, and the device keeps starting the system that runs. The bundle stays in the cache for the next attempt.

Ctrl-C during the download, or right after it, ends the command with exit code 130 before anything is installed or restarted; the same command resumes the download. A question answered with no ends with exit code 4.

ironflock os rollback

Makes the other root slot the one that starts, and restarts the device into it: back to the system that ran before the last update. Use it for a system that starts but misbehaves. A system that does not start, or does not reach IronFlock, is left by IronFlockOS itself at the next restart.

ironflock os rollback [flags]

The command has no flags of its own. It always restarts the device: a rollback without the restart would change nothing until the next one.

Only a slot whose system started on this device qualifies:

• a slot whose system was marked good while it ran, and was not tried again since. A slot that was tried and never marked good does not qualify.
• the slot the device was written with (A), as long as nothing was installed into it and it was not marked bad.

Apps and their data stay, as both systems use the same data partition. The slot that ran keeps its release. After the restart the older system has to prove itself again: the device keeps it once the device agent has reached IronFlock from it. On a UEFI machine, a slot that did so before is also kept once it has been up for two minutes. Until then a restart can bring back the newer system. IronFlock Studio offers the channel’s release again, and os update installs it.

# Go back to the system in the other slot, after a question
sudo ironflock os rollback
# Without a question
sudo ironflock os rollback --yes

What os rollback --yes prints on a device that runs 0.14.0 in slot B:

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

With --json, slot and version are the slot that starts and its release (empty when it cannot be read), from_slot and from_version the system that ran:

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

Refuses when, with exit code 3, and says why:

• it does not run as root, on a machine that does not run IronFlockOS, on the installer stick, and while RAUC installs a bundle.
• the device has a bootloader the command does not know: it knows GRUB (UEFI machines) and the Raspberry Pi’s.
• the other slot holds nothing yet (a freshly written device), holds a system that was tried and not marked good, holds no usable system because its installation did not finish, or is marked bad.
• the other slot waits for the next restart, after an update that was installed or a rollback that did not restart. sudo reboot starts it, and sudo rauc status mark-bad other drops it.

Fails when, with exit code 1: RAUC cannot make the slot the one that starts (nothing was changed); the restart fails (the slot then starts with the next restart). A question answered with no ends with exit code 4.

ironflock os reset

Requests the factory reset of IronFlockOS and restarts the device. During the next boot the device clears what its owner, its apps and the enrollment left, and starts as a freshly written device; with -c it enrolls as the device of a new .flock file.

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

IronFlockOS 0.15.0 is the first release with the factory reset. On an older release the command refuses; os update installs a newer one.

The reset clears, on the data partition and in both root slots:

• the apps with their data, and Docker’s containers, images and volumes.
• the device’s identity at IronFlock: the device agent with its copy of the .flock file, its database and its service. The host name goes back to ironflockos, and the machine ID is made anew.
• the SSH user and every other user account, with their home folders and sudo rules.
• the logs, the SSH host keys, the downloaded updates and the real-time tuning.
• without --keep-network: the network profiles (the WiFi among them), the proxy setting (proxy.conf) and the PTP setting (ptp.conf).

It keeps the IronFlockOS systems in the root slots, the running one and the other one when it holds a system, and RAUC’s record of them, so updates and rollbacks work as before. With --keep-network it also keeps the network settings above. It does not undo what was changed by hand in the system itself, such as a package or a file in /etc; writing IronFlockOS to the disk anew with os flash does.

What it does, in this order:

1. Refuses what the device would not do as asked (below), and checks the .flock file of -c: 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.
2. Says on stderr what goes, what stays, how the device comes back and what its last reset did, then asks you to type the device’s name: its name in the agent’s .flock file, as ironflock status shows it, or the host name of a device that is not enrolled. Anything else, Enter alone too, answers no.
3. Writes the request onto the IRONFLOCKOS partition, after the device’s own check has accepted it. A request that is there already is replaced; this one is a new request with three attempts of its own.
4. With -c, removes every other .flock file from the partition, because the device enrolls with the newest, and writes the new .flock file there. When this fails, the request is removed again.
5. Restarts the device. During the next start the device resets itself, in seconds (minutes on a slow SD card), restarts once more and starts as a freshly written device, with new SSH host keys.

After the reset, with -c, the device enrolls as the device of that .flock file and can be reached over SSH as its SSH user. Without -c, it waits for a .flock file on its IRONFLOCKOS partition and can be reached on its console only: it has no SSH user and no connection to IronFlock. An SSH connection to the device, also that of --host, ends with the restart; without -c none comes back.

Note: If you reach the device only over the network, give the new .flock file with -c. Without it, somebody has to be at the device to bring it back online.

An attempt that fails does not restart the device: it comes up as it is, and its next start, by a person or by an update, tries again. After three failed attempts the reset gives up, and the device starts with what is there. With its old data it stays the device it was, online with its old identity, and the .flock file and the proxy setting that came with the request are removed. A request that ended, done or given up, never fires again, in any slot and after any update. A disk that does not answer can hold an attempt up to 25 minutes. ironflock status shows a failed or given-up reset in its line Last reset:.

Before it asks, the command shows the last reset the device recorded:

# Reset the device; it then waits for a .flock file
sudo ironflock os reset
# Reset it and make it the device of new-device.flock
sudo ironflock os reset -c new-device.flock
# Keep the network settings, without a question
sudo ironflock os reset --keep-network --yes
# From another computer, on IronFlockOS 0.15.0
ironflock --host operator@edge-01 os reset -c new-device.flock

What os reset -c kitchen-pi.flock prints on the device edge-01, whose last reset gave up, with the name typed at the question:

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

The result of os reset --keep-network --yes --json:

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

Refuses when, with exit code 3, and says why and what to do:

• it does not run as root, on a machine that does not run IronFlockOS, on the installer stick, and while RAUC installs a bundle.
• the IronFlockOS has no factory reset: a newer release brings it, which os update installs.
• /boot/efi is not the mounted IRONFLOCKOS partition: nothing is mounted there, or a file system other than FAT.
• a reset has begun: it goes on at the next start, and nothing is to be changed until then. The message gives the last attempt.
• without -c, a .flock file lies on the IRONFLOCKOS partition: after the reset the device would enroll with it instead of waiting for one.
• the next start would not be the running system marked good. An update or a rollback waits for its restart: sudo reboot starts it, sudo rauc status mark-bad other drops it. Or the running system was not marked good yet: sudo rauc status mark-good keeps it, os rollback goes back.
• the device’s own check does not take the request: nothing is requested, and the message gives the device’s reason.

Fails when, with exit code 1:

• the mount table cannot be read, so the command cannot tell whether /boot/efi is the IRONFLOCKOS partition. Nothing is written.
• the .flock file of -c is not a valid one.
• the request or the .flock file cannot be written, or another .flock file cannot be removed. The request is taken back, and the error says what is gone.
• the restart fails. The device then resets itself at its next start; removing /boot/efi/factory-reset.conf and the .flock file from the IRONFLOCKOS partition cancels the reset.

Ctrl-C, SIGTERM or a lost SSH session while the command writes its request make it take the request back: it ends with exit code 130, and the device does not restart. A name typed wrong at the question ends with exit code 4.

The exit codes of all commands are explained on the conventions page. Over --host, exit code 255 means that the SSH connection failed.