Replace Linux with IronFlockOS

ironflock os install replaces the Linux that a running machine started from with IronFlockOS, on the same disk, and makes the machine the IronFlock device of a device configuration file (.flock). You run it on the machine itself, or from another computer over SSH.

Warning: Everything on the disk the machine started from is lost: the running system, its packages and settings, its user accounts and all data. There is no way back. Run the command with --dry-run first and read the plan.

When to Use It

Use os install for a machine that already runs Debian, Ubuntu or another Linux with systemd, and that you cannot or do not want to start from a USB stick: a PC in a control cabinet, a virtual machine in a cloud, a machine you reach only over SSH. With --host you run the command from your own computer, also from a Mac, and it waits until the machine is online as an IronFlock device.

Use another command when:

• You can start the machine from a drive — ironflock os flash writes IronFlockOS to a USB stick, an SD card or an external disk. With --installer it writes an installer stick, which installs IronFlockOS on the internal disk of the PC that starts from it. The installer stick is also the way out for most machines that os install refuses.
• The machine is a Raspberry Pi — os install installs only the images for UEFI machines (targets amd64-efi and arm64-efi). Write the Raspberry Pi’s SD card with os flash.
• The machine runs IronFlockOS already — os install refuses it. ironflock os update installs another release there.
• You want to keep the machine’s Linux — ironflock agent install connects the machine to IronFlock as it is.

ironflock os install

Checks the machine, shows the plan of the replacement and asks. Then it stages IronFlockOS in memory and restarts the machine, which writes IronFlockOS onto the disk at the end of its shutdown and starts it.

ironflock os install [-c <device.flock>] [--disk <disk>] [--dry-run] [flags]

On macOS the command ends with exit code 3 before it looks at anything; run it with --host there. It runs on one machine at a time: --host given more than once and --hosts end with exit code 2. The global flags are on the conventions page.

Flags

The proxy flags work as for agent install. Without them the command takes HTTP_PROXY, HTTPS_PROXY and NO_PROXY from the environment. A proxy URL with a password in it is a wrong command line (exit code 2); see Secrets.

What the Machine Needs

• The system — Linux with systemd as PID 1, such as Debian or Ubuntu, not in a container. IronFlockOS and ReswarmOS are refused.
• The firmware — 64-bit UEFI on amd64 or arm64. Its EFI variables are mounted (efivarfs) and writable. BIOS and 32-bit UEFI are refused. Secure Boot may be on, see Secure Boot.
• The disk — the disk the firmware started the system from: a whole disk of its own with a GPT (GUID partition table) and 512-byte logical sectors. The root file system is on this disk and on no other, directly or through LVM or LUKS. The disk holds at least the image’s smallest disk: the size the catalog names, else 10 GiB, or 18 GiB for an nvidia image.
• Memory — available memory (MemAvailable) for the compressed image, the ironflock binary and 512 MiB more: a machine of about 2 GiB for the base image.
• Tools — lsblk and ip of iproute2.
• The network — the download server reachable, directly or through a proxy, over a network the new system can use (What the New System Gets). For a device of an IronFlock appliance, that can be the appliance’s download mirror (Where the Files Come From).
• The .flock file — of -c, or of the device agent installed on the machine.

Where the Files Come From

The command needs the signed IronFlockOS catalog, the image, and the image’s hardware list. It takes them from:

1. --download-base, else IRONFLOCK_DL_BASE: that server alone.
2. Else the download mirror of the IronFlock appliance that the .flock file names as its update server: its update_url, when that is an absolute http or https URL whose host is not one of the IronFlock cloud, such as https://registry.<domain>/dl or http://<host>:<port>/dl. Stderr says Download base: ... (from the device's .flock). A machine that reaches the appliance but not ironflock.com is converted this way. A .flock file of the IronFlock cloud takes the cloud.
3. Else the IronFlock cloud, https://instance-registry.ironflock.com/dl.

With the appliance’s mirror, the files come from the mirror first, and from the IronFlock cloud where the mirror does not give them:

• The catalog, <mirror>/ironflockos/manifest.json — when the mirror gives none now (it cannot be reached, it answers with an error, or only the copy kept of its last catalog would stand in for it), everything comes from the cloud, as without an appliance. A catalog that the mirror gives and that is refused (its signature, older than the copy kept, too large) fails the command, as from any server.
• The image, <mirror>/ironflockos/<version>/<file> — when the mirror does not give it (it cannot be reached, answers with anything but the file, or what it sends is not the image’s beginning), it comes from the URL the signed catalog names. A file of os flash’s cache asks neither.
• The hardware list, <mirror>/ironflockos/<version>/<image>-<version>.modules.alias.gz — the same rule, on its own.

Each fallback is a warning in the plan, with the mirror, the file and the reason; with --json in warnings. The plan decides the source of each file once: the staging downloads the image from the plan’s image.url and does not fall back again. When neither the mirror nor the cloud gives a file, the command fails with one error that names both sources and both reasons (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

The mirror is reached directly, the cloud through the proxy, as for agent install. An HTTPS mirror with a certificate of the appliance’s own CA works only where the machine’s system trusts that CA. When the appliance answers, the new system keeps the network card that reached it (What the New System Gets).

Before Anything Changes

The command checks the machine in this order. The first check that fails refuses, with exit code 3 and one sentence that names the cause and, where there is one, the way out. Nothing is changed by then.

1. The system — systemd is PID 1, the system is not a container, and it is not IronFlockOS or ReswarmOS.
2. The firmware — 64-bit UEFI, writable EFI variables, and with Secure Boot on, a boot chain of the image that the firmware will start (Secure Boot).
3. The image — from the signed IronFlockOS catalog, as os images lists it: the image of --image, else the base image of the machine’s target. The command reads the first few MiB of the image file: from the cache of os flash when the file is there, else from the download server (the appliance’s mirror first, see Where the Files Come From). A .flock file for other hardware only warns.
4. The disk — the one with the partition that the firmware’s current boot option names; else the one with the EFI system partition mounted at /boot/efi or /efi; else the one --disk names. A --disk that names another disk than the one the system started from is refused. So is a disk that is not a whole disk of its own: an MD RAID array (also one that Intel RST makes), a device-mapper, loop or network block device, a disk in memory.
5. What is built on the disk — partitions, LVM with linear volumes, and what cryptsetup sets up for encryption (LUKS, plain dm-crypt, BitLocker, FileVault, TrueCrypt). Everything else is refused: MD RAID, bcache, multipath, a ZFS pool, LVM thin pools, snapshots, caches, RAID and mirrors, dm-verity, dm-integrity. Other disks stay as they are, so a btrfs file system or an LVM volume group with members on this disk and on another is refused: replacing the disk would destroy it on both. A machine with another disk that has a partition named IRONFLOCKOS, rootfs-a, rootfs-b or data is refused too, as IronFlockOS finds its partitions by these names.
6. Memory — as above.
7. The .flock file, the network, the proxy, the drivers — the .flock file is read as os flash reads it, and its SSH key must be a valid one. The network and the proxy are checked as described in What the New System Gets. For the drivers, the command takes the devices on the way to the disk and to the network card (the disk, the card, their controllers and buses) and looks them up in the image’s hardware list. It refuses only when the list shows that the image has no driver for one of them. A device it cannot decide is named in the warning drivers not checked; for a release without a hardware list (up to 0.14.0) the warning names every device.
8. The plan and the question — see below.

Ctrl-C while the command reads the beginning of the image ends it with exit code 130, and so does a lost terminal while the plan is shown or the question waits. Nothing was changed then.

The Plan and --dry-run

The plan goes to stderr. It names the machine and its firmware, the disk and how it was found, the image and where its file comes from, and the memory. It says that everything on the disk is lost, what the new system gets and what it does not get, and the warnings. --dry-run shows the plan, changes nothing and ends with exit code 0. With --dry-run, --yes needs no --disk.

On a Compute Engine VM the plan warns that Google’s guest environment goes: gcloud compute ssh, OS Login and metadata SSH keys stop working, and the serial console stays.

What the New System Gets

The new system gets:

• The device’s identity — of the .flock file, which goes onto the IRONFLOCKOS partition. The device enrolls with it at its first start.
• The network — of the network card the download of the image went through, to the download server or to the proxy. When the download base is the appliance’s mirror of the .flock file and the mirror answered the request for the catalog at all (a 404 too), it is the card of the connection to the mirror instead, wherever the files came from: the appliance is where the new device connects. A cable with DHCP needs nothing. A static address (addresses without a lifetime, gateways and routes set by hand, the DNS servers of systemd-resolved or /etc/resolv.conf) becomes a NetworkManager profile that matches the card by its permanent MAC address. A static address beside DHCP or SLAAC keeps DHCP and adds the static one. On WiFi, the network of the .flock file needs nothing; another network with a WPA-PSK or WPA3-SAE profile of NetworkManager, hidden or not, gets that profile. Addresses of other cards are not carried over, and the plan warns.
• The proxy — the proxy of the download becomes the proxy setting of IronFlockOS (proxy.conf on the IRONFLOCKOS partition), with the user and the password, and no_proxy. A proxy on the machine itself (127.0.0.1) is refused, as the new system does not have it. So is a mirror that answers on the machine’s loopback: a .flock file whose update_url names localhost, as the agent on the appliance’s own host has it. A proxy URL with characters that proxy.conf does not take is refused, and the refusal names the part.
• SSH — the project owner’s account with the key of the .flock file, as every IronFlockOS device has it.

IronFlockOS 0.15.0 and later take network profiles and the proxy setting from the IRONFLOCKOS partition. With an image of an older release, a machine whose network needs a profile, or whose download goes through a proxy, is refused; the refusal names the card, its static address or its WiFi, and what to do instead.

The new system does not get the user accounts of the old system with their passwords and SSH keys, the SSH host keys (SSH clients see a new host key), or the packages, settings and data. The device’s apps come back from IronFlock; their data on this machine does not.

The Question

The command asks you to type the machine’s short host name, which the question shows. On a machine whose kernel has the full name (Ubuntu’s images of Compute Engine), the full name is taken as well. Anything else, Enter alone too, answers no: exit code 4. See Questions and Confirmation.

--yes answers the question only when --disk names the disk. On an encrypted system --yes needs --allow-unencrypted as well, else the command ends with exit code 4. Without a terminal, and with --json, the question cannot be asked: without --yes the command ends with exit code 4.

After the Question: Staging and Hand-Over

Nothing on the disk is written before the restart. The command stages the replacement in memory:

1. A file system in memory takes the image: the file of the os flash cache when the plan read it there, else a download (shown as Downloading), checked against the signed catalog (Checking). The image is unpacked once (Preparing) and compared with what the plan read. The files for the IRONFLOCKOS partition are prepared.
2. A boot option for IronFlockOS goes to the end of the firmware’s boot order, behind the running system’s. Until the disk is written, the running system still starts first.
3. Staged: on stderr names the new boot option and the old system’s boot options, which are deleted after the write.
4. The command hands over: the machine restarts at once, or, when the command runs in an SSH session (also through sudo and --host), ten seconds after the command has ended, so that the result reaches the session first. Stdout says Handed over: ..., and the command ends with exit code 0.

Ctrl-C or SIGTERM from the question until the hand-over takes the staging back: the command ends with exit code 130, and the machine is as it was. After the question a lost terminal or SSH session no longer stops the command: the staging goes on, and the hand-over and the restart happen. Once the restart is handed over, Ctrl-C ends the command, and the restart goes on.

The Restart and the Write

At the end of the shutdown, ironflock writes the image from memory onto the disk. The machine’s console shows its lines, which start with ironflock-install:. Then the machine starts IronFlockOS, and the device appears in IronFlock within about ten minutes. The log of the write is ironflock-install.log on the IRONFLOCKOS partition of the new system.

When the Old System Starts Again

Before it writes, ironflock checks the disk once more. When something does not hold, the old system starts again, unchanged: the disk is busy or read-only, it is not the disk of the plan, the staged image is damaged, or the steps before the write take more than two minutes. The reason is in the EFI variable IronFlockInstall. ironflock status shows it in its line OS install:, without root:

System:        Debian GNU/Linux 13 (trixie)
  OS install:  'ironflock os install' stopped at 2026-11-11T10:00:00Z before it wrote the disk: the disk /dev/sda is not the plan's: its size changed from 64.0 GB to 32.0 GB; nothing was changed, and this system runs as before

# On the machine
ironflock status
# From another computer
ironflock --host admin@machine status
# Without ironflock: prints the stage, the time and the reason
tail -c +5 /sys/firmware/efi/efivars/IronFlockInstall-7b2f7cb6-eb8f-4acd-b7fd-e92df1a035a0

Over --host

ironflock --host admin@machine os install -c device.flock --disk /dev/sda --yes runs the command on that machine as every command runs over --host: the binary and the .flock file go there, the checks, the plan and the question run there, and their output comes back. The folder with the binary and the copy of the .flock file is removed when the command there ends, also after a refusal or an interrupt. --dry-run changes nothing on the machine beyond that folder.

The restart comes ten seconds after the command has ended, so its result reaches your side first. After the question a lost connection no longer stops the command there: when the connection breaks, the command on your side ends with exit code 255 and says that the machine goes on by itself.

After the hand-over the command waits, up to 15 minutes, for the machine to come back as IronFlockOS:

• Every 15 seconds it logs in at the same address as the SSH user of the .flock file, with the key of the .flock file. The key goes into a file of a new folder that only you can read, and the folder is removed when the wait ends. The key does not go into the SSH agent.
• It takes the new system’s host key without writing it anywhere: known_hosts stays as it is.
• It reads what the system runs and whether the device agent has connected to IronFlock since the start.
• Meanwhile it asks the old system, only with a host key that known_hosts has, for the EFI variable IronFlockInstall: a machine that comes back with its old system ends the wait at once.

The wait ends with exit code 0 when the machine runs IronFlockOS and the device agent is connected. It ends with 1 when the machine runs IronFlockOS without a connected agent, came back with its old system, or did not answer as IronFlockOS within 15 minutes. An address that DHCP changed defeats the check; the message then points to the device in IronFlock and to the machine’s console. Ctrl-C ends the wait with 130, and the machine goes on by itself.

The wait cannot tell which machine answers at the address, because the new system’s host key is new to your side. The proof is the device shown as connected in IronFlock.

The wait needs the .flock file on your side. Without -c, or with a .flock file that sets up no SSH user, the command ends with exit code 2 before anything goes to the machine, unless you give --no-wait. --no-wait hands over and ends with the exit code of the command on the machine.

Secure Boot

With Secure Boot on, the command checks that the firmware will start the image’s boot chain, shim and then GRUB:

• a signature of the image’s shim chains, through the certificates that come with it, to a certificate in the firmware’s signature database (db), and the forbidden database (dbx) revokes none of them; or db lists shim’s hash.
• neither dbx nor shim’s forbidden list on this machine (MokListX) lists the image’s shim or GRUB, or a certificate GRUB is signed with.
• the machine’s SBAT level (SbatLevelRT) revokes neither shim nor GRUB.

When the firmware would not start the image, the command refuses. You can turn Secure Boot off in the firmware’s setup: IronFlockOS starts without it too. On a system that did not start through shim, the plan warns that the SBAT level and MokListX were not checked. The command does not verify shim’s signature value or look at the kernel; the signed catalog vouches for them. With --json, machine.secure_boot.ca names the certificate in db that shim’s signature chains to, such as Microsoft UEFI CA 2023.

Examples

# Show the plan for the device of the installed agent, change nothing
sudo ironflock os install --dry-run
# The plan for a new device, as JSON
sudo ironflock os install -c device.flock --dry-run --json
# Replace the system without a question
sudo ironflock os install -c device.flock --disk /dev/sda --yes
# From another computer, and wait until the device is online
ironflock --host admin@machine os install -c device.flock --disk /dev/sda --yes

Result

The plan of sudo ironflock os install -c device.flock --dry-run, on stderr:

IronFlockOS catalog of 2026-11-20T09:00:00Z, signed with key 036ef3bd.
Machine:      debian-vm, Debian GNU/Linux 13 (trixie), amd64, UEFI without Secure Boot
Disk:         /dev/sda: Google PersistentDisk, 21.5 GB, serial persistent-disk-0 (the EFI system partition at /boot/efi is on it); it holds plain partitions
Image:        ironflockos-amd64-efi-base 0.15.0, 4.6 GB unpacked
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.15.0/ironflockos-amd64-efi-base-0.15.0.img.gz (662.9 MB), downloaded into memory and checked against the catalog
Memory:       1.7 GB available, 1.2 GB needed
Everything on /dev/sda is lost: this system, its packages and settings, and all data. There is no way back.
The new system gets:
  - the identity of the device kitchen-pc, from device.flock
  - the network: ens4 by cable with DHCP, which needs nothing carried over
  - SSH: the account operator with the .flock's key, as every IronFlockOS device has it
It does not get:
  - the user accounts of this system, their passwords and SSH keys
  - the SSH host keys: clients see a new host key
  - the packages, settings and data of this system: the device's apps come back from IronFlock, their data on this machine does not
Then the machine restarts, writes IronFlockOS from memory at the end of its shutdown and starts it; the device appears in IronFlock within about ten minutes.
Warning: drivers not checked: whether IronFlockOS ironflockos-amd64-efi-base 0.15.0 drives virtio-pci of the disk (/sys/devices/pci0000:00/0000:00:03.0), virtio-pci of the network card (/sys/devices/pci0000:00/0000:00:04.0) is not known: the hardware list of this release does not name the drivers built into its kernel
Warning: this is a Compute Engine VM: it keeps its address, but loses Google's guest environment, so 'gcloud compute ssh', OS Login and metadata SSH keys stop working; the serial console stays. With Shielded VM's integrity monitoring on, the first boot of IronFlockOS fails its check until the baseline is learned again
Dry run: nothing was changed.

The run of sudo ironflock os install -c device.flock --disk /dev/sda --yes shows the same plan, then the staging and the hand-over:

Staging IronFlockOS in memory: nothing is written to /dev/sda before the restart, and Ctrl-C until then leaves the machine as it was.
Downloading: 100% (662.9 MB of 662.9 MB)
Checking: 100% (662.9 MB of 662.9 MB)
Preparing: 100% (662.9 MB of 662.9 MB)
Staged: the image is in memory and checked against the catalog and the plan; the boot option Boot0003 for IronFlockOS is at the end of the boot order, and goes first after the write.
The old system's boot option Boot0001 (debian) is deleted after the write.
Handed over: the machine restarts now, writes IronFlockOS onto /dev/sda at the end of its shutdown (the console shows it) and starts it; the device kitchen-pc appears in IronFlock within about ten minutes. If it does not, see the machine's console; a machine that comes back with its old system has the reason in its EFI variable IronFlockInstall.

With --json the result is the plan as one JSON object: with --dry-run at once, without it after the hand-over, with dry_run false and staging, and over --host after the wait, with wait as well. Stderr gets the progress as JSON lines and nothing else (Output and JSON). No field holds a secret: the files for the IRONFLOCKOS partition are named with their size, and proxy URLs are shown without the password. The result of the dry run above, with line breaks added (the command writes one line; ... marks what the example leaves out):

{"dry_run":true,
 "machine":{"hostname":"debian-vm","os":"Debian GNU/Linux 13 (trixie)","architecture":"amd64","secure_boot":{"enabled":false},"memory_available":1651179520,"memory_needed":1220587675},
 "disk":{"device":"/dev/sda","devnum":"8:0","size":21474836480,"model":"Google PersistentDisk","serial":"persistent-disk-0","sysfs":{"vpd83":"0:persistent-disk-0"},"guid":"a6c1e3f4-0b2d-4c8e-9f1a-2b3c4d5e6f70","found_by":"esp","esp":"/boot/efi","storage":["partitions"],"encrypted":false},
 "image":{"image_id":"ironflockos-amd64-efi-base","version":"0.15.0",...,"raw_size":4564471808,"min_disk_size":10737418240,"guid":"...","ironflockos":{"guid":"d53fd016-10da-40c6-8d85-a4eae33538af","start":1048576,"size":268435456},"shim_sha256":"...","head_size":269484032,"head_sha256":"..."},
 "device":"kitchen-pc","device_file":"device.flock","flock":"/home/admin/device.flock",
 "network":{"interface":"ens4","mac":"42:01:0a:84:00:02","kind":"wired","addressing":"dhcp","carried":"nothing","addresses":[],"gateways":[],"dns":[]},
 "proxy":null,"ssh_user":"operator","files":[{"path":"device.flock","size":1234}],
 "drivers":{"checked":false,"devices":[...]},"not_carried_over":[...],"delayed_reboot":false,"warnings":[...]}

Refuses When

The command refuses with exit code 3, and nothing is changed:

• a container, a system without systemd as PID 1, IronFlockOS (os update installs a release there), ReswarmOS.
• BIOS, 32-bit UEFI, an architecture without an image, EFI variables that are not mounted (the refusal names the mount command) or mounted read-only (it names mount -o remount,rw).
• Secure Boot that would not start the image’s shim or GRUB.
• a disk the command cannot tell (name it with --disk), a --disk that is not the disk the system started from, a partition, no disk; a disk that is not a whole disk of its own, or that lsblk does not list; a disk without a GPT.
• a root file system on another disk, across disks, on ZFS or on no disk (a live system).
• logical sectors other than 512 bytes, a disk that is too small, a storage stack the command does not take apart, a btrfs file system or LVM volume group across this disk and another, another disk with IronFlockOS’s partition names.
• too little memory.
• a network the command does not carry over, a proxy on the machine itself or the appliance’s mirror on the machine’s loopback, a proxy with an image that does not take proxy.conf or with characters proxy.conf does not take, an active NetworkManager profile that cannot be read.
• a hardware list of the release that shows that the image has no driver for a device of the disk or the network card.
• ip of iproute2 that does not run: the network cannot be read.
• after the question, before the staging changes anything: a disk that is no longer the one of the plan, /run/initramfs that is a mount point already, a plan that cannot be carried out as it is.

These are wrong command lines, exit code 2, checked before anything is changed:

• --yes without --disk, unless with --dry-run.
• no -c on a machine without an installed device agent; over --host without --no-wait, no -c or a .flock file that sets up no SSH user.
• an --image the catalog does not have, one for another target than the machine’s, or the installer stick (which os flash --installer writes).
• a proxy URL with a password, and the other proxy flags that agent install refuses.
• several machines (--host more than once, --hosts).

Fails When

The command fails with exit code 1, and nothing is changed:

• the .flock file is not a valid one, or its SSH key is not a valid one.
• the catalog does not verify or cannot be fetched, as for os images; with the appliance’s mirror, from neither the mirror nor the cloud.
• the beginning of the image file cannot be downloaded (getting the image ...), with the appliance’s mirror from neither the mirror nor the cloud, or it is not an IronFlockOS image as the command knows it. When the catalog came from the cloud because the mirror gave none, the error begins with the catalog’s warning, the appliance's mirror ... gives no IronFlockOS catalog now (...), and names both servers.
• the download’s local address belongs to no network card; the mount table, the block devices or the memory cannot be read; the EFI variables do not parse.
• after the question: the image file is not the catalog’s or not what the plan read (the message names both values), the download fails, the firmware does not take the boot option, or the restart cannot be started. The staging is taken back. When taking it back fails as well, the message asks for a restart, which removes what is left.

No URL is printed with a user and password it may contain.

Exit Codes

The meaning of each code for all commands is on the conventions page.