Actualizar, revertir y restablecer

Estos comandos se ocupan de un dispositivo que ejecuta IronFlockOS. os update instala un release, os rollback vuelve al release que se ejecutaba antes, y os reset convierte el dispositivo de nuevo en uno recién escrito.

Slots raíz y la partición de datos

El disco de un dispositivo IronFlockOS contiene:

• Dos slots raíz, A y B — cada uno contiene un sistema IronFlockOS completo. Uno se ejecuta. El otro contiene el sistema que se ejecutaba antes, o todavía nada en un dispositivo recién escrito. RAUC, la herramienta de actualización que usa IronFlockOS, escribe un release en el slot que no se ejecuta y registra qué slot arranca a continuación.
• La partición de datos (/data) — las apps y sus datos, y el agente del dispositivo con su copia del archivo de configuración del dispositivo (.flock). Ambos sistemas la usan, así que una actualización o una reversión deja las apps y sus datos como están.
• La partición IRONFLOCKOS (montada en /boot/efi) — una pequeña partición FAT. El dispositivo se inscribe con un archivo .flock que encuentra allí al arrancar, y os reset escribe allí su solicitud.

Un sistema nuevo tiene que demostrar que funciona: el dispositivo lo conserva una vez que el agente del dispositivo ha alcanzado IronFlock desde él y lo ha marcado como bueno. Un sistema que no arranca, o que no llega a ese punto, se abandona en el siguiente reinicio en favor del que se ejecutaba antes. ironflock status muestra los 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

Dónde se ejecutan los comandos

Los tres comandos se ejecutan en un dispositivo que ejecuta IronFlockOS, necesitan root y preguntan antes de actuar. En otro sistema (macOS, un Linux que no es IronFlockOS, la memoria USB de instalación de IronFlockOS) terminan con el código de salida 3.

• En el dispositivo — los releases de IronFlockOS posteriores a 0.15.0 llevan ironflock. Inicia sesión en el dispositivo y ejecuta el comando con sudo.
• Desde otra computadora — los releases de IronFlockOS hasta 0.15.0 no llevan ironflock. Ejecuta el comando desde una computadora Linux o macOS con --host, como el usuario SSH del dispositivo: la cuenta que el archivo .flock configura para el propietario del proyecto, operator en los ejemplos. --host copia ironflock al dispositivo para la ejecución y ejecuta allí el comando mediante sudo.

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

os update y os rollback se ejecutan en varios dispositivos a la vez (--host más de una vez, o --hosts) cuando se indica --yes. os reset se ejecuta en un solo dispositivo a la vez; en varios termina con el código de salida 2. Los flags globales están en Flags, salida y códigos de salida.

ironflock os update

Instala en el slot raíz que no se ejecuta el release de IronFlockOS que ofrece el canal del dispositivo. El sistema nuevo arranca con el siguiente reinicio, o de inmediato con --reboot.

ironflock os update [flags]

El canal del dispositivo es el que sigue su agente del dispositivo, según el environment del archivo .flock del agente: test en la plataforma de pruebas de IronFlock y, si no, production. Cuando el catálogo no tiene el canal del dispositivo, es production. La base de descarga se toma de --download-base, después de IRONFLOCK_DL_BASE, después del servidor de actualizaciones (update_url) del archivo .flock del agente (en un dispositivo de un IronFlock appliance, la réplica de descargas del appliance, que es lo único que puede alcanzar un dispositivo así) y, si no, es la nube de IronFlock.

Lo que hace, en este orden:

1. Lee el catálogo firmado de IronFlockOS y toma el paquete de actualización de la imagen del dispositivo en el release del canal (o de --version).
2. Dice qué release se ejecuta en qué slot, qué release instala, en qué slot, qué contiene ahora ese slot y el tamaño de la descarga. Después pregunta.
3. Descarga el paquete en /var/cache/ironflockos, en la partición de datos. Una descarga interrumpida se reanuda. El archivo solo se usa cuando su tamaño y su SHA-256 son los del catálogo.
4. Hace que RAUC instale el paquete en el slot que no se ejecuta. RAUC comprueba la firma del paquete, escribe el slot y lo convierte en el que arranca a continuación. Lo que contenía antes el slot se sobrescribe. El paquete se elimina una vez instalado.
5. Con --reboot, reinicia el dispositivo con el sistema nuevo.

El sistema en ejecución se queda como está hasta el reinicio. Las apps y sus datos se mantienen. El slot que se ejecuta ahora conserva su release, y el dispositivo vuelve a él cuando el nuevo release no arranca o no alcanza IronFlock.

No se instala nada, y el código de salida es 0, cuando el dispositivo ya ejecuta el release, y cuando el release ya está instalado en el otro slot y espera al reinicio. En el segundo caso, --reboot pregunta y reinicia el dispositivo.

# Instalar el release del canal del dispositivo; arranca con el siguiente reinicio
sudo ironflock os update
# Instalarlo y reiniciar con él, sin pregunta
sudo ironflock os update --reboot --yes
# Instalar un release más antiguo del catálogo
sudo ironflock os update --version 0.13.0

El progreso va a stderr: la descarga y su comprobación, y después cada paso que nombra RAUC. Lo que imprime os update --yes en un dispositivo que ejecuta 0.13.0 en el 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').

Con --json, la instalación es la fase de progreso installing, en porcentaje. El resultado de 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}

Se niega, con el código de salida 3, cuando:

• no se ejecuta como root, se ejecuta en una máquina que no ejecuta IronFlockOS o en la memoria USB de instalación.
• RAUC ya está instalando un paquete, uno que IronFlock Studio inició a través del agente o con otra llamada. RAUC instala uno cada vez.
• el release no tiene paquete para la imagen del dispositivo.
• el release es más antiguo que el que se ejecuta, salvo que --version lo indique. Cuando el otro slot contiene ese release, el mensaje nombra os rollback.
• /var/cache/ironflockos no tiene espacio para lo que queda por descargar. El mensaje enumera los paquetes de actualizaciones anteriores que hay en la carpeta, que puedes borrar.

Líneas de comandos incorrectas, código de salida 2: --channel y --version juntos, una versión que no tiene forma de versión, un canal o un release que el catálogo no tiene.

Falla, con el código de salida 1, cuando: el catálogo no se verifica o no se puede leer; la descarga se interrumpe (lo que llegó se queda en /var/cache/ironflockos, y el mismo comando la reanuda); la descarga no es el archivo del catálogo; RAUC rechaza el paquete o no consigue instalarlo. El error da el motivo de RAUC. Cuando RAUC había empezado a escribir, el slot se marca como defectuoso y no contiene ningún sistema utilizable, y el dispositivo sigue arrancando el sistema que se ejecuta. El paquete se queda en la caché para el siguiente intento.

Ctrl-C durante la descarga, o justo después, termina el comando con el código de salida 130 antes de que se instale o se reinicie nada; el mismo comando reanuda la descarga. Una pregunta respondida con no termina con el código de salida 4.

ironflock os rollback

Convierte el otro slot raíz en el que arranca y reinicia el dispositivo con él: vuelve al sistema que se ejecutaba antes de la última actualización. Úsalo para un sistema que arranca pero no funciona bien. Un sistema que no arranca, o que no alcanza IronFlock, lo abandona el propio IronFlockOS en el siguiente reinicio.

ironflock os rollback [flags]

El comando no tiene flags propios. Siempre reinicia el dispositivo: una reversión sin reinicio no cambiaría nada hasta el siguiente.

Solo es válido un slot cuyo sistema arrancó en este dispositivo:

• un slot cuyo sistema se marcó como bueno mientras se ejecutaba, y que no se ha vuelto a probar desde entonces. Un slot que se probó y nunca se marcó como bueno no es válido.
• el slot con el que se escribió el dispositivo (A), mientras no se haya instalado nada en él y no se haya marcado como defectuoso.

Las apps y sus datos se mantienen, ya que ambos sistemas usan la misma partición de datos. El slot que se ejecutaba conserva su release. Después del reinicio, el sistema más antiguo tiene que volver a demostrar que funciona: el dispositivo lo conserva una vez que el agente del dispositivo ha alcanzado IronFlock desde él. En una máquina UEFI, un slot que ya lo consiguió antes se conserva también una vez que lleva dos minutos en marcha. Hasta entonces, un reinicio puede traer de vuelta el sistema más reciente. IronFlock Studio vuelve a ofrecer el release del canal, y os update lo instala.

# Volver al sistema del otro slot, tras una pregunta
sudo ironflock os rollback
# Sin pregunta
sudo ironflock os rollback --yes

Lo que imprime os rollback --yes en un dispositivo que ejecuta 0.14.0 en el 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.

Con --json, slot y version son el slot que arranca y su release (vacío cuando no se puede leer), y from_slot y from_version, el sistema que se ejecutaba:

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

Se niega, con el código de salida 3, y dice por qué, cuando:

• no se ejecuta como root, se ejecuta en una máquina que no ejecuta IronFlockOS o en la memoria USB de instalación, o RAUC está instalando un paquete.
• el dispositivo tiene un gestor de arranque que el comando no conoce: conoce GRUB (máquinas UEFI) y el de la Raspberry Pi.
• el otro slot aún no contiene nada (un dispositivo recién escrito), contiene un sistema que se probó y no se marcó como bueno, no contiene ningún sistema utilizable porque su instalación no terminó, o está marcado como defectuoso.
• el otro slot espera al siguiente reinicio, tras una actualización que se instaló o una reversión que no reinició. sudo reboot lo arranca, y sudo rauc status mark-bad other lo descarta.

Falla, con el código de salida 1, cuando: RAUC no puede convertir el slot en el que arranca (no se cambió nada); el reinicio falla (el slot arranca entonces con el siguiente reinicio). Una pregunta respondida con no termina con el código de salida 4.

ironflock os reset

Solicita el restablecimiento de fábrica de IronFlockOS y reinicia el dispositivo. Durante el siguiente arranque, el dispositivo borra lo que dejaron su propietario, sus apps y la inscripción, y arranca como un dispositivo recién escrito; con -c se inscribe como el dispositivo de un nuevo archivo .flock.

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

IronFlockOS 0.15.0 es el primer release con el restablecimiento de fábrica. En un release anterior, el comando se niega a ejecutarse; os update instala uno más reciente.

El restablecimiento borra, en la partición de datos y en ambos slots raíz:

• las apps con sus datos, y los contenedores, las imágenes y los volúmenes de Docker.
• la identidad del dispositivo en IronFlock: el agente del dispositivo con su copia del archivo .flock, su base de datos y su servicio. El nombre de host vuelve a ser ironflockos, y el machine ID se genera de nuevo.
• el usuario SSH y todas las demás cuentas de usuario, con sus directorios personales y sus reglas de sudo.
• los registros, las claves de host SSH, las actualizaciones descargadas y la optimización de tiempo real.
• sin --keep-network: los perfiles de red (entre ellos el WiFi), el ajuste de proxy (proxy.conf) y el ajuste de PTP (ptp.conf).

Conserva los sistemas IronFlockOS de los slots raíz, el que se ejecuta y el otro cuando contiene un sistema, y el registro que tiene RAUC de ellos, así que las actualizaciones y las reversiones funcionan como antes. Con --keep-network conserva además los ajustes de red de arriba. No deshace lo que se cambió a mano en el propio sistema, como un paquete o un archivo de /etc; eso lo consigue volver a escribir IronFlockOS en el disco con os flash.

Lo que hace, en este orden:

1. Rechaza lo que el dispositivo no haría tal como se pide (abajo), y comprueba el archivo .flock de -c: un archivo con nombre *.flock de 5 MiB como máximo, un objeto JSON con un secret y una device_key, cuyos name y serial_number sean nombres simples.
2. Dice en stderr qué desaparece, qué se queda, cómo vuelve el dispositivo y qué hizo su último restablecimiento, y después te pide que escribas el nombre del dispositivo: su nombre en el archivo .flock del agente, como lo muestra ironflock status, o el nombre de host de un dispositivo que no está inscrito. Cualquier otra cosa, también Enter solo, responde no.
3. Escribe la solicitud en la partición IRONFLOCKOS, después de que la comprobación propia del dispositivo la haya aceptado. Una solicitud que ya está allí se reemplaza; esta es una solicitud nueva con sus propios tres intentos.
4. Con -c, elimina de la partición todos los demás archivos .flock, porque el dispositivo se inscribe con el más reciente, y escribe allí el nuevo archivo .flock. Si esto falla, la solicitud se vuelve a eliminar.
5. Reinicia el dispositivo. Durante el siguiente inicio, el dispositivo se restablece a sí mismo en segundos (minutos en una tarjeta SD lenta), se reinicia una vez más y arranca como un dispositivo recién escrito, con claves de host SSH nuevas.

Tras el restablecimiento, con -c, el dispositivo se inscribe como el dispositivo de ese archivo .flock y se puede alcanzar por SSH como su usuario SSH. Sin -c, espera un archivo .flock en su partición IRONFLOCKOS y solo se puede alcanzar desde su consola: no tiene usuario SSH ni conexión con IronFlock. Una conexión SSH al dispositivo, también la de --host, termina con el reinicio; sin -c no vuelve ninguna.

Nota: Si solo alcanzas el dispositivo por la red, indica el nuevo archivo .flock con -c. Sin él, alguien tiene que estar junto al dispositivo para volver a ponerlo en línea.

Un intento que falla no reinicia el dispositivo: arranca tal como está, y su siguiente inicio, por una persona o por una actualización, lo vuelve a intentar. Tras tres intentos fallidos, el restablecimiento desiste, y el dispositivo arranca con lo que hay. Con sus datos antiguos sigue siendo el dispositivo que era, en línea con su identidad antigua, y el archivo .flock y el ajuste de proxy que llegaron con la solicitud se eliminan. Una solicitud que terminó, completada o abandonada, nunca vuelve a activarse, en ningún slot ni tras ninguna actualización. Un disco que no responde puede retener un intento hasta 25 minutos. ironflock status muestra un restablecimiento que falló o desistió en su línea Last reset:.

Antes de preguntar, el comando muestra el último restablecimiento que registró el dispositivo:

# Restablecer el dispositivo; después espera un archivo .flock
sudo ironflock os reset
# Restablecerlo y convertirlo en el dispositivo de new-device.flock
sudo ironflock os reset -c new-device.flock
# Conservar los ajustes de red, sin pregunta
sudo ironflock os reset --keep-network --yes
# Desde otra computadora, en IronFlockOS 0.15.0
ironflock --host operator@edge-01 os reset -c new-device.flock

Lo que imprime os reset -c kitchen-pi.flock en el dispositivo edge-01, cuyo último restablecimiento desistió, con el nombre escrito en la pregunta:

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.

El resultado de os reset --keep-network --yes --json:

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

Se niega, con el código de salida 3, y dice por qué y qué hacer, cuando:

• no se ejecuta como root, se ejecuta en una máquina que no ejecuta IronFlockOS o en la memoria USB de instalación, o RAUC está instalando un paquete.
• el IronFlockOS no tiene restablecimiento de fábrica: lo trae un release más reciente, que instala os update.
• /boot/efi no es la partición IRONFLOCKOS montada: no hay nada montado allí, o hay un sistema de archivos que no es FAT.
• ya ha empezado un restablecimiento: continúa en el siguiente inicio, y hasta entonces no hay que cambiar nada. El mensaje indica el último intento.
• sin -c, hay un archivo .flock en la partición IRONFLOCKOS: tras el restablecimiento, el dispositivo se inscribiría con él en lugar de esperar uno.
• el siguiente inicio no sería el sistema en ejecución marcado como bueno. Una actualización o una reversión espera a su reinicio: sudo reboot la arranca, sudo rauc status mark-bad other la descarta. O el sistema en ejecución aún no se ha marcado como bueno: sudo rauc status mark-good lo conserva, os rollback vuelve atrás.
• la comprobación propia del dispositivo no acepta la solicitud: no se solicita nada, y el mensaje da el motivo del dispositivo.

Falla, con el código de salida 1, cuando:

• no se puede leer la tabla de montajes, así que el comando no puede saber si /boot/efi es la partición IRONFLOCKOS. No se escribe nada.
• el archivo .flock de -c no es válido.
• no se puede escribir la solicitud o el archivo .flock, o no se puede eliminar otro archivo .flock. La solicitud se retira, y el error dice qué ha desaparecido.
• el reinicio falla. El dispositivo se restablece entonces en su siguiente inicio; eliminar /boot/efi/factory-reset.conf y el archivo .flock de la partición IRONFLOCKOS cancela el restablecimiento.

Ctrl-C, SIGTERM o una sesión SSH perdida mientras el comando escribe su solicitud hacen que la retire: termina con el código de salida 130, y el dispositivo no se reinicia. Un nombre mal escrito en la pregunta termina con el código de salida 4.

Los códigos de salida de todos los comandos se explican en Flags, salida y códigos de salida. Con --host, el código de salida 255 significa que falló la conexión SSH.