Status y Doctor
ironflock status muestra qué hay de IronFlock en una máquina y si se ejecuta. ironflock doctor comprueba si una máquina puede ejecutar el agente del dispositivo y si alcanza los hosts con los que habla el agente. Úsalos antes de conectar una máquina y cuando un dispositivo no aparece en línea.
Ninguno de los dos comandos cambia nada ni pregunta nada. Se ejecutan en Linux y macOS, sin root, y leen más como root. Con --host se ejecutan en otra máquina, también en varias a la vez (Máquinas remotas por SSH). Allí se ejecutan como root cuando la cuenta de acceso es root o puede usar sudo sin contraseña y sin terminal; si no, se ejecutan como la cuenta de acceso, sin preguntar, y su sugerencia indica el comando con --host root@machine.
ironflock status
Muestra el agente del dispositivo, el appliance y el sistema operativo de esta máquina: qué está instalado, su versión, si su servicio se ejecuta, el dispositivo y su proyecto, y la última autoactualización del agente. El appliance es el sistema IronFlock completo en una máquina en tus instalaciones (IronFlock Appliance); para un appliance, el comando muestra además la dirección de su UI, su licencia, la salud de sus servicios y una actualización pendiente (Comandos del appliance). En IronFlockOS, el comando muestra además los slots raíz y lo que requiere atención.
ironflock status [flags]Se ejecuta en: Linux; en macOS muestra el sistema e indica que no hay nada instalado. Root: no es necesario; algunos datos lo necesitan. Pregunta: nada.
El comando no tiene flags propios. Acepta los flags globales (Flags globales).
Sin root, algunos datos no se pueden leer: el dispositivo y su proyecto, ya que el .flock del agente es exclusivo de root, y en un appliance, cuya carpeta /opt/ironflock pertenece a root, también las versiones, la URL del appliance, su licencia y su actualización, y la actualización del agente. La salud de los servicios del appliance necesita root o el grupo docker. Aparecen como unknown (needs root), el campo JSON needs_root los enumera, y sudo ironflock status los lee.
# Qué hay en esta máquina, leído con tu usuario
ironflock status
# Todo, en JSON
sudo ironflock status --json
# El estado de otra máquina por SSH
ironflock --host pi@device-17 statusSalida de texto
$ ironflock status
Agent: installed in /opt/ironflock/device-agent
Version: 1.6.9
Service: running (ironflock-device-agent.service)
Connection: unknown (this agent does not report it)
Device: unknown (needs root)
Swarm: unknown (needs root)
Update: none pending
Appliance: not installed
System: Debian GNU/Linux 12 (bookworm)
Run 'sudo ironflock status' to read what needs root.Swarm es el proyecto del dispositivo. Connection es unknown para un agente en ejecución: los agentes publicados hasta ahora no informan de su conexión en la máquina.
En IronFlockOS
La línea del sistema muestra la imagen y sus dos slots raíz (Slots raíz y la partición de datos):
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 BEl agente de un dispositivo IronFlockOS es el que instaló la imagen cuando el dispositivo se inscribió, en /opt/ironflock/device-agent en /data, y se muestra como en cualquier otro sistema. Un dispositivo que aún no se ha inscrito no tiene agente; la imagen lleva uno, y la línea indica cómo se inscribe el dispositivo (primera línea de abajo). Cuando /data no se pudo montar en este arranque, tampoco se ve la carpeta del agente, inscrito o no, y la línea lo indica en su lugar (segunda línea):
Agent: not enrolled yet: the device enrolls with a .flock on its IRONFLOCKOS partition at its next start, or now with 'sudo ironflock agent configure -c <file>'
Agent: not to be seen: /data, which holds the agent and its .flock, could not be mounted (below); a .flock on the IRONFLOCKOS partition enrolls the device at its next start for as long as /data is missingDebajo del sistema aparece una línea para cada uno de estos casos, solo cuando IronFlockOS tiene algo que decir:
| Línea | Se muestra cuando |
|---|---|
Last reset: | el último restablecimiento de fábrica falló o desistió. os reset explica qué significa un registro |
Reset hold: | hay un restablecimiento abierto (wait: no se toma un .flock ni un proxy.conf de la partición IRONFLOCKOS mientras los datos del propietario anterior puedan estar en /data; copy: el restablecimiento ha empezado a borrar), o desistió y no pudo eliminar el .flock y el proxy.conf que llegaron con él, que quedan sin usar (gave-up) |
/data: | no se pudo montar /data: el dispositivo funciona con las carpetas propias del slot raíz, sin Docker ni las apps |
/apps: | /apps no es la carpeta de la partición de datos: las apps se ejecutan, pero pierden sus datos en la siguiente actualización del sistema operativo |
Last reset: 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
Reset hold: wait: a reset is open; a .flock or proxy.conf on the IRONFLOCKOS partition is not taken while the old owner's data may be on /data
/data: NOT MOUNTED: the device runs on the root slot's own folders; Docker and the apps do not run, and what is written now is lost with the next update
/apps: not the data partition's folder: the apps run, but lose their data at the next OS updateUn intento fallido de un restablecimiento dice attempt 1 of 3 failed at <time>: <reason>; /data holds the old data; the next start tries again mientras la retención es wait o copy, y no request is open now sin retención. Sin root, el registro de restablecimiento que se muestra es su copia en el slot en ejecución, ya que la partición IRONFLOCKOS pertenece a root.
El último os install
En cualquier Linux con variables EFI, una línea OS install: muestra lo que registró el último ironflock os install en la variable EFI de IronFlock IronFlockInstall, cuando existe. Cualquier usuario puede leer la variable. Donde no se puede leer, o la máquina no tiene variables EFI, no hay línea ni advertencia; un valor que no se puede analizar es una advertencia.
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| Etapa | La línea dice |
|---|---|
stopped | que se detuvo antes de escribir el disco, el motivo, y que no se cambió nada |
handed-over | en el sistema anterior: el instalador no se ejecutó en el reinicio, y no se cambió nada. En IronFlockOS: escribió este sistema, pero no pudo registrar cómo terminó la instalación |
writing | empezó a escribir el disco y no registró que terminara |
done | en IronFlockOS: este sistema lo instaló os install. En otros sistemas: escribió IronFlockOS en un disco de la máquina, y el sistema en ejecución es otro |
failed | escribió el disco, y la relectura de lo escrito falló, con el motivo |
El registro nunca se borra. La línea se mantiene hasta que el siguiente os install lo reemplaza y, en un dispositivo convertido, se mantiene como constancia de que el sistema se instaló así.
Resultado JSON
--json escribe lo mismo como un objeto JSON, mostrado aquí en varias líneas; el comando lo escribe en una sola línea.
{
"agent": {
"installed": true,
"layout": "current",
"dir": "/opt/ironflock/device-agent",
"version": "1.6.9",
"service": {"unit": "ironflock-device-agent.service", "state": "running"},
"connection": "unknown",
"device": "demo-device",
"swarm": "demo_swarm",
"update": {"state": "none"}
},
"appliance": {"installed": false},
"os": {"name": "Debian GNU/Linux 12 (bookworm)", "id": "debian", "version": "12", "ironflockos": false},
"needs_root": []
}Un dato que no se puede leer es unknown; cuando el motivo no es root, una advertencia en stderr dice por qué.
| Campo | Valores |
|---|---|
agent.installed | true cuando hay un agente instalado. Los campos de layout a update existen entonces, y solo entonces. En IronFlockOS, false significa que el dispositivo aún no se ha inscrito |
agent.unfinished_install | true: no hay agente, pero una instalación anterior se detuvo antes de llegar al agente; agent install la deshace primero. Ausente en otro caso |
agent.layout | current (/opt/ironflock/device-agent), legacy (/opt/reagent, de un instalador anterior), migrating (el agente está pasando ahora mismo de la estructura antigua a la actual) |
agent.dir | la carpeta del agente |
agent.version | lo que dice el binario del agente con -version |
agent.service | unit y state: running, starting, stopping, stopped, failed, not_found (systemd no conoce la unidad), unknown |
agent.connection | disconnected cuando el agente no se ejecuta. La conexión de un agente en ejecución es unknown; connected viene de los agentes que la informan |
agent.device, agent.swarm | el nombre del dispositivo y su proyecto, del .flock. No se lee nada más del .flock |
agent.update | la última autoactualización. state: none (nada en curso, nada fallido), activating, probation (la nueva versión se ejecuta y tiene que conectarse para demostrar que funciona), rolled_back (falló, vuelve a ejecutarse la versión anterior, y la nueva se vuelve a intentar más tarde), blocked (falló definitivamente; el agente espera un release más reciente), unknown. Con version, previous_version, reason y updated_at |
appliance.installed | true cuando el IronFlock appliance está instalado (existe su unidad ironflock.service); entonces existen dir, version, channel, url, license, service, health y update |
appliance.data_left | solo cuando el appliance no está instalado y /opt/ironflock aún contiene sus datos, que dejó appliance remove sin --purge o una instalación que se detuvo: esa carpeta |
appliance.version, appliance.channel | los archivos VERSION y CHANNEL de su carpeta |
appliance.url | la dirección de su UI: HOME_URL de su .env. No se lee nada más de .env, que contiene sus secretos |
appliance.license | present cuando su license.env contiene una clave de licencia, missing cuando no, invalid cuando su LICENSE_KEY no es una clave de licencia (un UUID): todos los comandos del appliance ignoran esa clave, y el texto lo dice. La clave nunca se muestra |
appliance.service | ironflock.service, con los mismos estados que el del agente. running significa que la unidad inició los contenedores, no que cada uno de ellos esté sano |
appliance.health | el estado de sus servicios, según docker ps: state healthy (cada uno se ejecuta y supera su comprobación de salud, o no tiene ninguna, o se ejecutó una vez y terminó con 0), starting (hay una comprobación de salud pendiente), unhealthy, down (ningún contenedor), unknown; services, cuántos contenedores; problems, cada servicio que no está sano con su state (unhealthy, starting, restarting, exited con exit_code, …) |
appliance.update | una actualización pendiente, según el archivo de estado que escriben su UI y su temporizador de reintento: state none (no se pidió ninguna, o la última terminó), running, failed (el temporizador de reintento la vuelve a intentar), unknown; con version, since y message. cut_short (solo root) indica el release cuyos archivos conservó una actualización que quedó a medias: la siguiente actualización los restaura primero. No se consulta ningún release |
appliance.ironflock | solo cuando el ironflock que ejecutan las unidades del appliance en cada inicio (path, /usr/local/bin/ironflock) falta (missing) o es más antiguo (older) (state; version, lo que dice) que el que instaló o actualizó el appliance por última vez (installed). Solo root, y solo para un appliance que instaló ironflock. El texto tiene entonces una línea ironflock: que dice qué instalar |
os.name, os.id, os.version | PRETTY_NAME, ID y VERSION_ID de /etc/os-release; en un Mac, macOS 15.5, macos, 15.5 |
os.ironflockos | true en IronFlockOS. Entonces os.version es su IMAGE_VERSION, y siguen los campos de abajo |
os.image, os.build | IMAGE_ID y BUILD_ID de la imagen |
os.booted_slot, os.primary_slot | el slot desde el que se ejecuta el sistema y el que inicia el siguiente arranque: A o B |
os.slots | los slots raíz: name (A), rauc_slot (rootfs.0), state (booted, active, inactive), boot_status (good, bad), y version y installed_at del release que instaló allí una actualización (ausentes en un slot escrito con la imagen). Ausente cuando no se pueden leer los slots |
os.last_reset | el registro del último restablecimiento de fábrica, solo cuando es failed o gave-up: result, time, version, attempt, attempts_max, reason, data (old, new, none: lo que contiene ahora /data) y, para gave-up, left (de data, booted-slot, other-slot: lo que puede quedar aún del propietario anterior) |
os.reset_hold | wait, copy o gave-up, solo mientras existe una retención de restablecimiento (consulta la tabla de arriba) |
os.data_missing | true, solo cuando no se pudo montar /data |
os.install | lo que registró el último os install, en cualquier Linux con variables EFI, solo cuando existe y se puede leer: stage, time (RFC 3339, UTC) y reason (con stopped y failed) |
os.apps_not_persistent | true, solo cuando /apps no es la carpeta de la partición de datos |
needs_root | los campos que dicen unknown porque el comando no se ejecutó como root, como agent.device y agent.swarm. Vacío cuando no se omitió nada |
Código de salida
El código de salida es 0 siempre que se escribe la vista general, también cuando muestra un agente detenido, una actualización revertida o un slot defectuoso: status informa y no juzga, y un script lee los campos. Es 1 cuando no se puede escribir la vista general. Para los demás códigos de salida, consulta Códigos de salida.
ironflock doctor
Comprueba si esta máquina puede ejecutar el agente del dispositivo y si alcanza los hosts con los que habla el agente: el sistema, systemd, Docker, el espacio libre en disco, el reloj, DNS, el proxy, el servidor de descargas y los hosts que indica el .flock del dispositivo.
ironflock doctor [flags]Se ejecuta en: Linux y macOS. Root: no es necesario; una comprobación que no puede mirar sin root es skipped y lo indica. Pregunta: nada.
| Flag | Significado |
|---|---|
-c, --config <file> | el archivo .flock del dispositivo cuyos hosts se comprueban (por defecto: el del agente instalado) |
agent install ejecuta estas comprobaciones, todas salvo privileges y docker, antes de cambiar nada, y se detiene cuando falla system, systemd, disk_space o download_tree.
# Comprobar esta máquina, con tu usuario
ironflock doctor
# Comprobar todo como root, en JSON
sudo ironflock doctor --json
# Comprobar los hosts de un .flock antes de instalarlo
ironflock doctor -c device.flockResultados
Cada comprobación tiene un id, un resultado y un hallazgo de una línea. Un resultado distinto de ok viene con una sugerencia que dice qué hacer.
| Resultado | Significado |
|---|---|
ok | nada que hacer |
warning | puede funcionar, pero no bien |
failed | el agente no se puede instalar, o no funciona, tal como está la máquina |
skipped | la comprobación no pudo mirar; el hallazgo dice por qué |
Comprobaciones
Las comprobaciones, en el orden en que se muestran. Una comprobación conserva su id; una comprobación nueva recibe uno nuevo.
| Id | Qué mira | Cuando no es ok |
|---|---|---|
privileges | si el comando se ejecuta como root | warning sin root cuando una comprobación no pudo mirar; el hallazgo indica esas comprobaciones. Ejecuta sudo ironflock doctor |
system | Linux basado en Debian o Ubuntu (la instalación toma sus paquetes de apt) o IronFlockOS, y la arquitectura para la que se descarga el agente | failed en otro sistema, warning en otro Linux con apt. agent install se detiene con failed |
systemd | systemd gestiona el sistema (existe /run/systemd/system) | failed cuando systemd no gestiona el sistema; agent install se detiene entonces. warning mientras el sistema está degraded: falló una unidad |
docker | Docker se ejecuta (docker info) | ok sin Docker, ya que agent install lo instala, pero failed con un agente instalado. skipped sin root cuando el usuario no está en el grupo docker |
disk_space | el espacio libre para /opt/ironflock y para /var (Docker, apt, los registros) | failed por debajo de 128 MiB en /opt: una instalación o una actualización del agente guarda allí su binario dos veces. warning por debajo de 2 GiB en cualquiera de los dos |
clock | el reloj de esta máquina frente al Date de la respuesta del servidor de descargas, y su Age cuando la guardó una caché | ok dentro de 10 s, warning hasta 5 minutos, failed por encima: se rechazan las solicitudes firmadas y los tokens de corta duración, y los datos de las apps llevan la hora equivocada. Un reloj muy desfasado rompe el propio TLS: failed, con la hora que tiene la máquina. Consulta Sincronización horaria (NTP) |
dns | los nombres que esta máquina resuelve por sí misma: los hosts a los que llega directamente, y el proxy | un nombre no se resuelve. Un host al que se llega a través del proxy lo resuelve el proxy |
proxy | el proxy por el que pasan las comprobaciones de red, y de dónde viene el ajuste: el registro de la instalación (/etc/ironflock/proxy.env) o, si no, el entorno | failed cuando no es la URL de un proxy. skipped sin root cuando el registro está en el archivo, que solo root lee |
download_tree | el agente en el servidor de descargas que usa agent install: su mapa de canales, tal como lo lee agent install (device-agent/manifest-v2.json o, si no, manifest.json), y el agente del canal de producción para esta arquitectura. Con la réplica de un appliance, lo que la réplica no ofrece se busca en la nube de IronFlock, como lo toma agent install: el agente entero cuando la réplica no ofrece mapa de canales, el archivo del agente cuando ofrece el mapa sin el archivo | failed cuando no hay agente que descargar, con la réplica del appliance cuando ni la réplica ni la nube lo tienen; agent install se detiene entonces. Un error del servidor (5xx) es un warning, y también lo es un agente que ofrece la nube donde la réplica no lo ofrece |
device_endpoint | el device_endpoint_url del .flock responde | sin respuesta: el agente se conecta a IronFlock ahí |
docker_registry | el docker_registry_url del .flock responde (https://<host>/v2/; con un puerto, HTTP simple, como el registro de un appliance en la LAN) | sin respuesta: el dispositivo descarga de ahí las imágenes de sus apps |
update_server | el servidor de actualizaciones del agente tiene su mapa de canales: el update_url del .flock (la réplica de un appliance) o, si no, la nube de IronFlock | sin respuesta o sin mapa de canales: el agente busca ahí sus actualizaciones |
El servidor de descargas es el que usa agent install: --download-base; si no, la variable de entorno IRONFLOCK_DL_BASE; si no, la réplica de descargas del appliance que indica el .flock (su update_url, cuando no es un host de la nube de IronFlock), con la nube para lo que la réplica no ofrece; si no, la nube de IronFlock (De dónde viene el agente). Los hosts que debe alcanzar un dispositivo se enumeran en Requisitos de red.
Con y sin -c y root
Las tres últimas comprobaciones necesitan un .flock: el de -c o, si no, el del agente instalado.
| Como root | Sin root | |
|---|---|---|
Sin -c | los hosts del .flock del agente instalado | las tres últimas comprobaciones son skipped: el .flock del agente instalado es exclusivo de root |
Con -c | los hosts del .flock indicado | los hosts del .flock indicado |
Sin root, también docker es skipped fuera del grupo docker, y proxy es skipped cuando la instalación registró el proxy. Una comprobación de red cuyo host no da respuesta es entonces también skipped (para dns, un nombre que no se resuelve), ya que podría obtenerla a través del proxy registrado. privileges indica cada comprobación que no pudo mirar, y sudo ironflock doctor las ejecuta.
Cómo deciden las comprobaciones de red
- Un host responde cuando llega una respuesta HTTP, sea cual sea su estado. Un 502, 503 o 504 a una solicitud HTTP simple a través del proxy no es una respuesta: el proxy lo devuelve cuando no puede alcanzar el host.
- Un certificado que TLS rechaza no es una respuesta. La única excepción es el certificado de la CA propia de un appliance, cuando el
.flockindica unappliance_domain: el agente confía en él. - Las comprobaciones pasan por el proxy de la comprobación
proxy, según las reglas deHTTPS_PROXY,HTTP_PROXYyNO_PROXYque siguen las descargas, también en cada solicitud de una redirección, y esperan 20 s una respuesta. - Un host que una entrada de
NO_PROXYmantiene fuera del proxy va directo. Cuando así no da respuesta, el hallazgo indica la entrada, por ejemplo(directly: instance-registry.ironflock.com is in NO_PROXY), y la sugerencia dice que quites la entrada, con elagent configure --no-proxyque lo hace cuando el ajuste es el registro de la instalación.
Salida
$ sudo ironflock doctor
Download base: https://instance-registry.ironflock.com/dl
Device file: /opt/ironflock/device-agent/device-config.flock
CHECK RESULT FINDING
privileges ok runs as root
system ok Debian GNU/Linux 12 (bookworm), amd64
systemd ok systemd runs this system
docker ok Docker 27.3.1 runs
disk_space ok 50.0 GB free for /opt and /var
clock ok within 10 s of the download server's clock
dns ok resolves instance-registry.ironflock.com, cbw.ironflock.com, europe-docker.pkg.dev
proxy ok none: the connections go direct
download_tree ok https://instance-registry.ironflock.com/dl has the agent 1.6.9 for amd64
device_endpoint ok cbw.ironflock.com answers
docker_registry failed europe-docker.pkg.dev cannot be reached: no answer within 20 s
update_server ok https://instance-registry.ironflock.com/dl has the agent's updates
What to do:
docker_registry: the device pulls its apps' images from there: let this machine reach europe-docker.pkg.dev on port 443, directly or through the proxy
Failed: docker_registry.Con la réplica del appliance del .flock, la primera línea lo indica:
Download base: http://10.0.0.5:15002/dl (the appliance's mirror of the .flock; the IronFlock cloud for what it does not give)Con --json, abreviado aquí y mostrado en varias líneas; el comando escribe una sola línea.
{
"result": "failed",
"checks": [
{"id": "privileges", "result": "ok", "finding": "runs as root"},
{"id": "docker_registry", "result": "failed", "finding": "europe-docker.pkg.dev cannot be reached: no answer within 20 s", "hint": "the device pulls its apps' images from there: let this machine reach europe-docker.pkg.dev on port 443, directly or through the proxy"}
],
"download_base": "https://instance-registry.ironflock.com/dl",
"flock": "/opt/ironflock/device-agent/device-config.flock"
}| Campo | Valores |
|---|---|
result | failed cuando falló una comprobación, warning cuando una advirtió y, si no, ok. Una comprobación omitida no hace fallar nada |
checks | las comprobaciones, en el orden de arriba: id, result, finding y hint con todos los resultados salvo ok |
download_base | el servidor de descargas comprobado. Con la réplica del appliance, solo la réplica; los hallazgos nombran la nube cuando buscan allí |
flock | el .flock cuyos hosts se comprobaron; null si no hay ninguno |
Ninguna salida muestra un secreto: de un .flock, las comprobaciones solo leen los hosts, y la contraseña de un proxy aparece como xxxxx.
Código de salida
El código de salida es 0 cuando ninguna comprobación falló; una advertencia no hace fallar. Es 1 cuando falló una comprobación: el resultado dice cuál, no le sigue ninguna línea de error y, con --json, stdout tiene el resultado, no un objeto de error. Es 1 con un error cuando no se puede leer el .flock de -c. Para los demás códigos de salida, consulta Códigos de salida.