Comandos del agente del dispositivo

Los comandos ironflock agent conectan una máquina Linux a IronFlock como dispositivo y se ocupan del agente del dispositivo a partir de entonces. Con ellos instalas el agente, le das otra configuración de dispositivo u otro proxy, lo actualizas, lo detienes y lo inicias, lees su registro y lo vuelves a eliminar.

El agente del dispositivo

El agente del dispositivo es el programa que conecta una máquina a IronFlock como dispositivo y ejecuta en Docker las apps del proyecto del dispositivo. Qué dispositivo pasa a ser una máquina lo determina el archivo de configuración del dispositivo (.flock) que IronFlock Studio proporciona para cada dispositivo (Conectar dispositivos).

Todos los comandos del agente necesitan root y se ejecutan en Linux. Sin root terminan con el código de salida 3 y no llaman a sudo por sí mismos (Privilegios de root). En macOS, los comandos del agente terminan con el código de salida 3 antes de examinar nada; ejecútalos en la máquina Linux, o desde el Mac con --host. En un dispositivo IronFlockOS, la imagen trae el agente con su sistema: agent install y agent remove se niegan a ejecutarse allí, y agent configure -c inscribe el dispositivo con otro .flock.

Cada comando acepta también los flags globales --yes, --json, --download-base, --host, --hosts y --parallel (Flags globales). Una pregunta necesita una terminal; sin ella, indica --yes (Preguntas y confirmación).

Con --host, un comando se ejecuta en otra máquina por SSH (Máquinas remotas por SSH). En varias máquinas a la vez (--host más de una vez, o --hosts), agent restart, agent start y agent logs se ejecutan tal cual, pero agent logs --follow no con --json. agent stop, agent update, agent configure y agent remove necesitan allí --yes, ya que no se pregunta a nadie, y agent configure no acepta -c, ya que un .flock indica un único dispositivo. agent install se ejecuta en una sola máquina a la vez.

Cómo es un agente instalado

El agente también escribe por sí mismo algunos ajustes del host, en cada inicio: el slice ironflock.slice en el que se ejecuta, que le reserva memoria, el watchdog de systemd, los ajustes del kernel ante un fallo grave y un límite para el tamaño del journal.

Una máquina que configuró un instalador anterior de IronFlock puede tener aún el agente en la estructura antigua /opt/reagent (servicio reagent.service, registro /var/log/reagent.log), que el agente traslada por sí mismo a /opt/ironflock/device-agent; ironflock status muestra qué estructura tiene una máquina, y los rechazos de abajo indican los casos en los que importa.

ironflock agent install

Instala el agente del dispositivo en /opt/ironflock/device-agent, Docker cuando falta, y los ajustes del host de un dispositivo, y conecta la máquina a IronFlock como el dispositivo del .flock. El agente se inicia de inmediato y a partir de entonces se actualiza por sí mismo.

ironflock agent install -c <device.flock> [flags]

Se ejecuta en: Linux basado en Debian o Ubuntu, con systemd; no en IronFlockOS. Root: necesario. Pregunta: antes de instalar los paquetes y Docker, y por cada ajuste del host; --yes responde a cada pregunta con su valor por defecto.

La máquina necesita acceso a internet, o al servidor de descargas indicado con --download-base (Base de descarga), o a la réplica de descargas del appliance que indica el .flock (De dónde viene el agente). Los hosts que debe alcanzar un dispositivo se enumeran en Requisitos de red.

De dónde viene el agente

El agente consta de su mapa de canales, su binario y los archivos .sha256 y .sig del binario. El comando los toma de:

1. --download-base o, si no, IRONFLOCK_DL_BASE: solo de ese servidor.
2. Si no, de la réplica de descargas del appliance de IronFlock que el .flock indica como su servidor de actualizaciones (update_url), cuando su host no es de la nube de IronFlock. Así se instala una máquina que alcanza el appliance pero no ironflock.com. Un .flock de la nube de IronFlock usa la nube.
3. Si no, de la nube de IronFlock, https://instance-registry.ironflock.com/dl.

El comando indica la base en stderr: Download base: ... (from the device's .flock) o, si no, (from --download-base), (from IRONFLOCK_DL_BASE) o (from default).

Con la réplica del appliance, los archivos vienen primero de la réplica y, cuando la réplica no los ofrece, de la misma ruta bajo la base de descarga de la nube de IronFlock:

• El mapa de canales — cuando la réplica no ofrece ninguno en ese momento (sin respuesta, no está, un estado de error), todo viene de la nube, y la versión es la que indica el mapa de la nube. Un mapa que ofrece la réplica y que se rechaza (su firma, sin versión) hace fallar la instalación, como desde cualquier servidor.
• El binario, su .sha256 y su .sig — cada uno que la réplica no ofrece viene de la nube. Cuando los archivos de la réplica no superan las comprobaciones (suma de comprobación, firma), los tres vienen de la nube.

Cada recurso a la nube es una línea Warning: ... en stderr, con la réplica, el archivo y el motivo y, con --json, una entrada de warnings en el resultado. Cuando ni la réplica ni la nube ofrecen un archivo, la instalación falla con un único error que nombra ambas fuentes y ambos motivos (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

La réplica es el servidor de actualizaciones del .flock, que elude el proxy (Proxy). Una réplica HTTPS con un certificado de la CA propia del appliance solo funciona donde el sistema de la máquina confía en esa CA. Los paquetes de la distribución y Docker siguen viniendo de sus propios servidores, e install.sh e ironflock de ironflock.com; con --host, ironflock va de tu computadora a la máquina.

Comprobaciones antes de la instalación

Antes de cambiar nada, el comando ejecuta las comprobaciones de ironflock doctor que indican si puede salir bien: system, systemd, disk_space, clock, dns, proxy, download_tree, device_endpoint, docker_registry y update_server. Se ejecutan para el .flock de -c, con la base de descarga y los flags de proxy de la instalación.

Cuatro de ellas detienen la instalación cuando fallan, porque entonces la instalación fallaría con seguridad o a medias:

El mensaje indica la comprobación, su hallazgo y su sugerencia. Cualquier otro hallazgo es una advertencia en stderr, y la instalación continúa: el agente se conecta, se actualiza y descarga sus apps en cuanto la red lo permite. Un resultado warning o skipped nunca detiene la instalación. Ejecuta ironflock doctor -c device.flock para ver todas las comprobaciones antes de instalar.

Pasos

1. Indica los paquetes que instala y pregunta. Los instala con apt.
2. Instala Docker cuando la máquina no lo tiene, y pregunta antes.
3. Descarga el agente del canal de producción y lo verifica con su suma de comprobación y su firma. Una instalación que no puede obtener un agente verificado se detiene aquí, antes de cualquiera de los pasos siguientes.
4. Configura Docker: el proxy, cuando se indica uno y, para un Docker que trajo esta instalación o que aún no contiene nada, el data-root en la carpeta del agente. Un Docker que contiene imágenes o contenedores conserva su configuración y sus datos.
5. Configura los ajustes del host (tabla de abajo). Cada uno es una elección en la terminal; --yes toma el valor por defecto.
6. Instala el agente en /opt/ironflock/device-agent y lo inicia.

La instalación añade además un banner de inicio de sesión. Todo lo que cambia la instalación se escribe en /opt/ironflock/device-init/installed.json. Cuando falla un paso a partir del paso 4, el error indica que el intento está registrado y que el mismo comando, ejecutado de nuevo, lo deshace primero. Cuando el comando encuentra un intento anterior así, lo deshace una vez superadas las comprobaciones: enumera lo que deshace, pregunta y después vuelve a instalar.

Proxy

Los flags de proxy definen el proxy corporativo para las descargas de la instalación, para Docker y para el agente. Cada ajuste se toma de su flag y, si no, de las variables de entorno HTTP_PROXY, HTTPS_PROXY y NO_PROXY (o de sus formas en minúsculas).

Una URL de proxy tiene la forma http://proxy.example.com:3128; https:// y socks5:// también funcionan, y una URL sin esquema se toma como http://. Cuando el proxy pide inicio de sesión, la URL indica el usuario sin la contraseña, http://[email protected]:3128, y --proxy-password-file da la contraseña. El comando pone la contraseña en las URL de los flags que indican un usuario.

Advertencia: Nunca escribas la contraseña del proxy en la URL. Las líneas de comandos aparecen en ps y en el historial del shell, así que una URL con contraseña se rechaza como línea de comandos incorrecta, y el error no la repite. Pon la contraseña en una línea de un archivo, o pásala por una tubería con --proxy-password-file /dev/stdin (Secretos).

Además de los hosts de --no-proxy, eluden el proxy (NO_PROXY): localhost, 127.0.0.1 y ::1, y el servidor de descargas y el servidor de actualizaciones del .flock (su update_url) cuando no son hosts de la nube de IronFlock, como un appliance o una réplica en la LAN. Los hosts de la nube de IronFlock (ironflock.com, ironflock.dev y sus subdominios, y storage.googleapis.com) están en internet y pasan por el proxy.

La instalación escribe el proxy de Docker y del agente en /etc/ironflock/proxy.env, que solo root lee (modo 0600), y Docker se reinicia para usarlo. Los drop-ins de systemd ironflock-proxy.conf de docker.service y de ironflock-device-agent.service nombran ese archivo y no contienen ningún ajuste propio, así que systemctl show muestra a cualquier usuario el nombre del archivo y nada de su contenido. Un drop-in de Docker propio del host (docker.service.d/http-proxy.conf) se mantiene; los ajustes de IronFlock tienen prioridad sobre sus líneas Environment=, y una advertencia lo nombra. Un daemon.json con proxies los conserva, ya que Docker los toma antes que cualquier otro.

Para cambiar la configuración más adelante, usa agent configure. Para el proxy de todo el emplazamiento, consulta Detrás de un proxy corporativo.

Ejemplos

# Instalar el agente; el comando pregunta antes de cada paso
sudo ironflock agent install -c device.flock
# Instalar sin preguntas y evitar que el dispositivo se suspenda
sudo ironflock agent install -c device.flock --yes --disable-suspend
# Instalar detrás de un proxy que no pide inicio de sesión
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# Instalar detrás de un proxy que pide inicio de sesión; la contraseña viene de un archivo
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

Resultado

$ sudo ironflock agent install -c device.flock --yes
Done: the IronFlock device agent runs (systemctl status ironflock-device-agent).
The device appears online in IronFlock within a minute.

{"action":"installed","device":"demo-device","agent_version":"1.6.9"}

warnings solo está en el resultado cuando un archivo vino de la nube de IronFlock en lugar de la réplica del appliance: una entrada por cada uno, como lo dicen las líneas Warning:.

Cuándo se niega

Una línea de comandos incorrecta termina con el código de salida 2 antes de que se ejecute nada: una URL de proxy con contraseña; una URL de proxy que indica un usuario, sin --proxy-password-file; --proxy-password-file sin una URL de proxy que indique un usuario; un valor que no es una URL de proxy. También cuenta una variable de proxy del entorno que no es una URL de proxy; el error nombra la variable, no su valor.

El comando se niega con el código de salida 3, y no cambia nada, cuando:

• no se ejecuta como root, o la máquina no es Linux;
• la máquina ejecuta IronFlockOS, antes que nada, con root o sin él. La imagen trae el agente e ironflock con su sistema, y cada actualización del sistema operativo reemplaza el sistema en su conjunto. El mensaje dice que el dispositivo se inscribe con un .flock en su partición IRONFLOCKOS en su siguiente inicio, y que agent configure -c lo inscribe ahora. En la memoria USB de instalación de IronFlockOS dice que la memoria no es un dispositivo;
• ya hay un agente instalado, también en la estructura antigua /opt/reagent. El mensaje nombra agent configure y agent remove;
• el agente está sacando la máquina de la estructura antigua;
• una instalación anterior se detuvo antes de configurar el agente, había movido el data-root de Docker, y desde entonces Docker contiene imágenes o contenedores: deshacer ese intento los borraría;
• falla una de las comprobaciones system, systemd, disk_space o download_tree. --yes no cambia nada.

Una pregunta respondida con no, o una pregunta sin terminal y sin --yes, termina el comando con el código de salida 4. Un paso que falla lo termina con el código de salida 1.

ironflock agent configure

Cambia lo que configuró la instalación: el .flock del dispositivo, el proxy corporativo de Docker y del agente, o ambos. Reinicia lo que tiene que usar el cambio.

ironflock agent configure [-c <device.flock>] [flags]

Se ejecuta en: Linux con un agente instalado; en IronFlockOS solo con -c. Root: necesario. Pregunta: antes de que Docker se reinicie por una nueva configuración de proxy; --yes responde.

Indica -c, un flag de proxy o ambos. Sin ninguno de ellos no hay nada que cambiar: es una línea de comandos incorrecta (código de salida 2).

Otro .flock

Con -c, el agente recibe el .flock indicado y se reinicia: la máquina pasa a ser el dispositivo de ese .flock. Las apps y sus datos se mantienen. Cuando la instalación configuró un usuario SSH, el usuario SSH sigue al .flock:

• Mismo propietario del proyecto, otra clave del dispositivo — la clave antigua deja de aceptarse y se acepta la nueva.
• Otro propietario del proyecto — el nuevo propietario recibe su usuario SSH, y el usuario SSH del primer propietario desaparece igual que lo elimina agent remove: la regla de sudo, la clave y la cuenta con su directorio personal cuando la creó la instalación.
• Un .flock sin clave del dispositivo — el usuario SSH desaparece y no llega ninguno.

Cuando el dispositivo cambia de manos, quien ejecuta el comando puede ser el primer propietario, por SSH con la misma cuenta que desaparece, y eliminar una cuenta termina sus sesiones. Por eso el comando trabaja en este orden: configura la cuenta del nuevo propietario (usuario, clave, regla de sudo), reinicia el agente con el nuevo .flock y solo entonces retira la regla de sudo, las sesiones y la cuenta del primer propietario (o solo la clave antigua, para el mismo propietario). El dispositivo tiene una nueva vía de acceso, y está en línea, antes de que desaparezca la antigua. Antes de que terminen las sesiones, una línea en stderr lo indica, por ejemplo Removing the account anna, ...: a session of anna ends here.

• Cuando el agente no se reinicia con el nuevo .flock, el primer propietario conserva el acceso: alguien tiene que poder entrar.
• Cuando solo falló el usuario SSH del nuevo propietario, el acceso del primer propietario desaparece igualmente: el dispositivo ha cambiado de manos y está en línea.
• Qué accesos quedan por retirar se registra en /opt/ironflock/device-init/installed.json (users_to_remove). Cada agent configure -c y agent remove posterior lo vuelve a intentar.
• Una cuenta que el nuevo .flock vuelve a configurar nunca se elimina (propietario A, después B, después A).
• A partir de su primer cambio, una terminal o una sesión SSH perdida no detiene el comando.

Con --host, la copia del .flock en la máquina se elimina en cuanto el comando la ha leído. Cuando la cuenta de acceso de --host es una cuenta que desaparece, la sesión SSH termina con la cuenta: tu ejecución termina entonces con el código de salida 255, como tras una conexión perdida, y el comando en la máquina continúa hasta el final. La carpeta de la ejecución ironflock.XXXXXXXXXX con su binario queda entonces en la máquina; en una carpeta temporal se queda hasta que esta se limpia, y en el directorio personal de la cuenta desaparece con la cuenta.

En IronFlockOS

Con -c, el comando inscribe el dispositivo igual que IronFlockOS lo inscribe en el primer arranque de cada nuevo slot raíz, tanto en un dispositivo que ya se ha inscrito como en uno que no. El .flock indicado pasa a ser la copia del agente, /opt/ironflock/device-agent/device-config.flock en /data, y el dispositivo se configura a partir de él en este orden: el usuario SSH del propietario del proyecto, el WiFi, el nombre de host a partir del nombre del dispositivo (salvo que /etc/ironflockos/enroll.conf indique hostname-from-flock=no), el agente, reiniciado con el nuevo .flock, y después la retirada del acceso del propietario anterior.

La siguiente actualización del sistema operativo inscribe su nuevo slot raíz a partir de la misma copia. El archivo que indicaste se queda donde está. Un paso que falla no impide que el agente se reinicie con el nuevo .flock, pero el acceso del primer propietario solo desaparece una vez que el agente se ha reiniciado. El comando termina entonces con el código de salida 1 e indica cada paso que falló; ejecuta de nuevo el mismo comando para repetirlos.

Los flags de proxy se rechazan en IronFlockOS. IronFlockOS guarda el proxy de Docker, del agente y del reloj en /etc/ironflockos/proxy.conf en /data, y un proxy.conf en su partición IRONFLOCKOS lo reemplaza en el siguiente inicio.

Configuración del proxy

• Cada flag de proxy indicado reemplaza su ajuste, y los demás se mantienen. --https-proxy por sí solo cambia el proxy HTTPS y conserva el proxy HTTP y los hosts que eluden ambos.
• La contraseña de --proxy-password-file va a las URL indicadas que nombran un usuario. Sin ninguna URL indicada, va a las URL de la configuración del dispositivo que nombran uno, así que una contraseña nueva se define solo con el archivo.
• --no-proxy, y el primer proxy de un dispositivo que no tenía ninguno, añaden también localhost, 127.0.0.1, ::1 y el servidor de actualizaciones del .flock del agente cuando no es un host de la nube de IronFlock (el de un appliance).
• --remove-proxy elimina la configuración. No acepta ningún otro flag de proxy.
• Las variables de proxy de tu entorno no cambian nada aquí: solo cuentan los flags.

La lista de hosts que eluden el proxy se queda como la encuentra el comando, salvo que --no-proxy indique otra. Cuando esa lista nombra un host de la nube de IronFlock, una advertencia lo nombra, con el agent configure --no-proxy que da la lista sin él. Un dispositivo que solo alcanza internet a través del proxy no puede actualizar su agente mientras el servidor de descargas de la nube, instance-registry.ironflock.com, esté en esa lista.

La configuración se guarda en /etc/ironflock/proxy.env, que solo root lee, y la nombran los drop-ins ironflock-proxy.conf de docker.service y de ironflock-device-agent.service. Cuando la configuración cambia, el comando la muestra antes y después, sin la contraseña. Después se reinician Docker y el agente. Reiniciar Docker detiene las apps del dispositivo un momento, así que el comando lo dice y pregunta; --yes responde. Con la contraseña en stdin no hay terminal en la que preguntar: indica --yes.

• Docker no se reinicia, y no se pregunta nada, cuando el daemon.json de Docker define proxies (Docker los toma antes que esta configuración) y cuando no cambia nada.
• Una unidad a la que solo le falta su drop-in lo recibe, y solo esa unidad se reinicia.
• Un drop-in de Docker propio del host se queda como está. Otro drop-in del agente, o de Docker, que define una variable de proxy se nombra en una advertencia; los ajustes de IronFlock lo anulan para cada variable que definen. Un drop-in o un daemon.json que contiene una contraseña de proxy legible por cualquier usuario también se nombra en una advertencia.
• Cuando falla el reinicio de Docker, el agente se reinicia igualmente, y al revés. El error (código de salida 1) nombra las unidades que siguen funcionando con la configuración antigua y el systemctl restart que la aplica; una segunda ejecución encuentra la configuración en su sitio y no reinicia nada.
• Cuando no se puede escribir la configuración, no se reinicia nada, y el error dice que ejecutes el comando de nuevo.

La configuración de proxy que una instalación anterior escribió en líneas Environment= de drop-ins http-proxy.conf, donde cualquier usuario puede leerla con systemctl show, contraseña incluida, se traslada a /etc/ironflock/proxy.env con cualquier ejecución de agent configure, también con una que solo lleve -c. No se guarda ninguna copia de los archivos antiguos. Por lo general, el traslado conserva los valores, así que no reinicia nada ni pregunta nada; donde cambia el proxy que usa una unidad, el comando dice por qué, muestra el proxy de esa unidad antes y después, y pregunta. Un valor que el archivo de configuración no puede contener (una comilla simple en el host o en la lista de hosts que eluden el proxy, un carácter de control) no se traslada: una ejecución sin flags de proxy lo deja, advierte e indica el flag que vuelve a dar el valor.

Ejemplos

# Hacer que esta máquina sea el dispositivo de otro .flock
sudo ironflock agent configure -c new-device.flock
# Definir un proxy HTTPS que pide inicio de sesión; la contraseña viene de un archivo
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# Definir solo una contraseña de proxy nueva, leída de stdin, sin pregunta
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# Eliminar la configuración del proxy: Docker y el agente se conectan directamente
sudo ironflock agent configure --remove-proxy

Resultado

$ sudo ironflock agent configure -c new-device.flock
Device configuration updated; the agent restarted.
$ sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
The proxy settings of Docker and the agent change:
  HTTP proxy:   none (unchanged)
  HTTPS proxy:  none -> http://[email protected]:3128 (with a password)
  No proxy for: localhost,127.0.0.1,::1
Docker restarts for the new settings: the apps of the device stop for a moment and start again.
? Continue? Yes
Proxy settings updated: HTTPS through http://[email protected]:3128 (with a password); not for localhost,127.0.0.1,::1.
Restarted: docker.service, ironflock-device-agent.service.

En IronFlockOS, -c informa de la inscripción:

Device configuration updated: this device enrolled as new-device, as IronFlockOS enrolls it at every new root slot; the agent restarted.

{"action":"configured","device":"new-device","restarted":["ironflock-device-agent.service"]}

{"action":"configured","proxy":{"password":false,"changed":true,"moved":false},"restarted":["docker.service","ironflock-device-agent.service"]}

Cuándo se niega

Una línea de comandos incorrecta termina con el código de salida 2: nada que cambiar; --remove-proxy con otro flag de proxy; una URL de proxy con contraseña; una URL de proxy que indica un usuario, sin --proxy-password-file; --proxy-password-file con URL de las que ninguna indica un usuario; un valor que no es una URL de proxy ni una lista de hosts.

El comando se niega con el código de salida 3, y no cambia nada, cuando:

• no hay ningún agente instalado (el mensaje nombra agent install), salvo en IronFlockOS, donde -c inscribe un dispositivo que aún no se ha inscrito;
• el agente está sacando la máquina de la estructura antigua;
• se indican flags de proxy y el agente aún se ejecuta en la estructura antigua /opt/reagent. Una vez que el agente ha trasladado la máquina (ironflock status muestra la estructura), el mismo comando funciona;
• se indican flags de proxy en IronFlockOS, con -c o sin él;
• se indica solo --no-proxy o --proxy-password-file en un dispositivo sin proxy, o solo el archivo de contraseña cuando ninguna URL de proxy del dispositivo indica un usuario;
• los flags de proxy conservan un valor de la forma antigua que /etc/ironflock/proxy.env no puede contener; el mensaje nombra el flag que lo vuelve a dar.

En IronFlockOS, -c se rechaza con el código de salida 3 cuando la inscripción no conservaría el .flock:

• se ha solicitado un restablecimiento de fábrica que aún no ha empezado (/boot/efi/factory-reset.conf, que escribe os reset), o que ya ha empezado (/boot/efi/factory-reset.keep): el siguiente inicio borraría lo que configura el comando;
• un restablecimiento de fábrica está abierto o desistió y retiene los archivos que llegaron con él (/run/ironflockos/factory-reset-hold; ironflock status da más detalles);
• no se pudo montar /data, así que la copia del agente acabaría en el slot raíz. En ese caso, la vía es un .flock en la partición IRONFLOCKOS;
• hay un .flock en la partición IRONFLOCKOS; el dispositivo se inscribe con él en su siguiente inicio, y el mensaje lo nombra;
• el comando se ejecuta en la memoria USB de instalación de IronFlockOS, que no es un dispositivo;
• el sistema no tiene /usr/lib/ironflock/image.json, o tiene un agente en la estructura antigua.

ironflock agent update

Hace que el agente se actualice al release de su canal, y sigue lo que hace. El agente busca un release más reciente en cada inicio: el comando lo reinicia e informa del resultado. El dispositivo está un momento fuera de línea en IronFlock; sus apps siguen ejecutándose.

ironflock agent update [flags]

Se ejecuta en: Linux, con un agente instalado. Root: necesario. Pregunta: sí, después de decir lo que hace el reinicio; --yes responde.

El comando no tiene flags propios y no acepta ninguna versión. El agente sigue su canal (production, o test en la plataforma de pruebas de IronFlock), desde su servidor de actualizaciones: el update_url de su .flock (la réplica de un appliance) o, si no, la nube de IronFlock. --download-base no lo cambia.

Lo que hace el agente, en este orden:

1. Lee el release de su canal. Un release que falló dos veces en este dispositivo no se vuelve a descargar hasta que sale uno más reciente.
2. Descarga un release más reciente en su carpeta y comprueba su firma.
3. Pone la nueva versión en su sitio y se reinicia con ella, 10 segundos después de la descarga. Retiene la actualización cuando su última conexión a IronFlock fue hace entre 12 minutos y un día: una actualización se activa desde una versión de la que se sabe que se conecta.
4. La nueva versión está en periodo de prueba: tiene que conectarse a IronFlock en los 10 minutos siguientes a su inicio y mantenerse en marcha 2 minutos. Si no lo hace, o se detiene tres veces antes, el agente vuelve a la versión anterior.
5. Tras una reversión, la versión anterior tiene que conectarse. Entonces la culpa era de la nueva versión: se vuelve a intentar una vez en la siguiente actualización y, tras su segundo fallo, se bloquea hasta un release más reciente. Cuando tampoco la versión anterior puede conectarse en 10 minutos, el agente culpa a la red, y la nueva versión se vuelve a intentar en la siguiente actualización.

El comando sigue esto en update-state.json, en la carpeta del agente, y en el registro del agente; no lee de ninguno de los dos nada anterior al reinicio. Su progreso va a stderr como líneas de texto, también con --json. Una descarga muestra una vez por minuto cuánto lleva.

Con el código de salida 1, el resultado se escribe igualmente, y stderr recibe la línea Error:. Con --json no sigue ningún objeto de error: stdout tiene el resultado.

Ejemplos

# Actualizar el agente; el comando pregunta antes del reinicio
sudo ironflock agent update
# Actualizar sin pregunta y leer el resultado como JSON
sudo ironflock agent update --yes --json

Resultado

$ sudo ironflock agent update --yes
The agent 1.6.9 restarts now and looks for a newer release on its channel: the device is offline in IronFlock for a moment, its apps keep running.
A newer release is downloaded and started. It has to connect to IronFlock within 10 minutes and stay up for 2, or the agent goes back to 1.6.9.
The agent restarted; it looks for a newer release.
Its channel offers 1.7.0: the agent downloads it.
Activating 1.7.0: the agent restarts into it.
1.7.0 runs on probation: it has to connect to IronFlock within 10 minutes and stay up for 2.
The agent was updated from 1.6.9 to 1.7.0: 1.7.0 connected to IronFlock and passed its probation.

Un agente que está al día, y uno cuya nueva versión se revirtió:

{"outcome":"current","version":"1.7.0","channel_version":"1.7.0"}

{"outcome":"rolled_back","version":"1.6.9","channel_version":"1.7.0","failed_version":"1.7.0","reason":"did not connect within 10m0s","retry":"next_update"}

Cuándo se niega

El comando se niega con el código de salida 3 cuando no hay ningún agente instalado (el mensaje nombra agent install), mientras el agente saca la máquina de la estructura antigua, cuando el agente se ejecuta en la estructura antigua (sus actualizaciones no guardan ningún estado que el comando pueda seguir) y con un agente anterior a 1.3.0, el primero que se actualiza por sí mismo bajo su unidad.

Falla con el código de salida 1, y un error que dice dónde mirar, cuando falla el reinicio y cuando la actualización no avanza dentro de los plazos del agente: la comprobación del agente en los 3 minutos siguientes al reinicio, la descarga en 30 minutos, la activación en 3 minutos, cada inicio de la nueva versión en periodo de prueba en 12 minutos, la valoración del agente tras una reversión en 12 minutos, y todo ello en 84 minutos. El agente continúa por sí solo; ironflock status muestra en qué punto está.

Ctrl-C deja de seguir la actualización, pero no la detiene, y termina el comando con el código de salida 130.

ironflock agent remove

Elimina el agente del dispositivo y deshace lo que registró su instalación. Docker y los paquetes siguen instalados.

ironflock agent remove [flags]

Se ejecuta en: Linux, con un agente instalado; no en IronFlockOS. Root: necesario. Pregunta: sí, después de enumerar lo que elimina. La pregunta tiene preseleccionado «No»: Enter solo no elimina nada.

El comando no tiene flags propios. Elimina:

• El agente — el agente, su base de datos y /opt/ironflock/device-agent. Las apps del dispositivo y sus datos desaparecen con él cuando Docker los guarda en la carpeta del agente.
• El usuario SSH — la cuenta, solo cuando la creó la instalación. De una cuenta que ya existía, solo se quita la clave del dispositivo de su authorized_keys, que sigue siendo del usuario. También desaparece el acceso de un propietario anterior del proyecto cuya retirada por agent configure -c había fallado, que aparece en la lista con «(a removal that had failed)».
• Los ajustes del host — el perfil de WiFi, el banner de inicio de sesión y los targets de suspensión enmascarados.
• Los archivos que la instalación escribió o reemplazó — vuelven los originales, con su modo, propietario y grupo.
• La configuración del proxy — /etc/ironflock/proxy.env con los drop-ins que lo nombran, y la configuración de proxy que una instalación anterior dejó en drop-ins http-proxy.conf. No vuelve nada en su lugar: después, Docker no tiene ningún proxy de IronFlock, y el comando no ha escrito la contraseña del proxy en ninguna parte. Cuando Docker tenía un proxy de IronFlock, la lista anterior a la pregunta lo indica.
• Los ajustes que el agente escribió por sí mismo en el host — el slice ironflock.slice con el drop-in 10-ironflock-resources.conf de su unidad, el watchdog de systemd (/etc/systemd/system.conf.d/10-ironflock-watchdog.conf), los ajustes del kernel ante un fallo grave (/etc/sysctl.d/60-ironflock-crash-recovery.conf, que el kernel conserva hasta el siguiente arranque) y el límite del journal (/etc/systemd/journald.conf.d/10-ironflock.conf).
• Los inicios de sesión del agente en registros de Docker — una vez detenido el agente, el comando ejecuta docker logout para el registro que indica el .flock (docker_registry_url) y, en un dispositivo de un appliance, para registry.<appliance_domain>. No se toca ningún otro inicio de sesión de /root/.docker/config.json. Un Docker que falta o que falla no detiene la eliminación; una línea indica qué inicio de sesión no se eliminó.

Un drop-in de Docker propio del host se queda como está. Un Docker que no se reinicia con la eliminación (sus datos no estaban en la carpeta del agente) usa el proxy con el que se inició hasta su siguiente reinicio.

El comando enumera en stderr lo que elimina y después pregunta. Con --json, la lista es el campo removed del resultado. Una vez que el comando ha empezado a eliminar, una terminal o una sesión SSH perdida no lo detiene: el usuario SSH que desaparece se lleva sus sesiones, quizá la que ejecuta el comando, y la eliminación continúa hasta el final.

Ejemplos

# Eliminar el agente; el comando enumera lo que desaparece y pregunta
sudo ironflock agent remove
# Eliminar el agente sin pregunta
sudo ironflock agent remove --yes

Resultado

$ sudo ironflock agent remove --yes
This removes:
  - the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)
  - the user operator and its home directory
  - /etc/profile.d/ironflock-motd.sh
The IronFlock device agent was removed from this machine.

{"action":"removed","removed":["the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)","the user operator and its home directory","/etc/profile.d/ironflock-motd.sh"]}

Cuándo se niega

El comando se niega con el código de salida 3 cuando no hay ningún agente instalado, y mientras el agente saca la máquina de la estructura antigua. En IronFlockOS se niega antes que nada, con root o sin él: la imagen trae el agente con su sistema, y cada actualización del sistema operativo y la siguiente inscripción lo volverían a configurar. El mensaje nombra ironflock os reset, que devuelve el dispositivo a un IronFlockOS recién escrito sin su identidad en IronFlock. En la memoria USB de instalación de IronFlockOS dice que la memoria no es un dispositivo.

La respuesta no, o una pregunta sin terminal y sin --yes, termina el comando con el código de salida 4.

ironflock agent restart

Reinicia el servicio del agente y comprueba que el agente vuelve a ejecutarse: su unidad tiene que estar en ejecución cinco segundos con un proceso. El dispositivo está fuera de línea en IronFlock durante esos segundos; las apps siguen ejecutándose.

ironflock agent restart [flags]

Se ejecuta en: Linux, con un agente instalado. Root: necesario. Pregunta: nada.

El comando no tiene flags propios. El servicio es ironflock-device-agent.service. Si lo ejecutas en una terminal que pasa por el agente (la terminal del dispositivo en IronFlock Studio, o SSH a través de IronFlock), el reinicio termina esa sesión; el dispositivo vuelve en menos de un minuto.

# Reiniciar el agente
sudo ironflock agent restart
# Reiniciarlo y leer el nuevo proceso como JSON
sudo ironflock agent restart --json

$ sudo ironflock agent restart
The agent restarted: ironflock-device-agent.service runs, with process 4242.

{"action":"restarted","unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

state es el estado de la unidad después del reinicio, con los nombres de ironflock status. main_pid es el proceso del agente, uno nuevo tras cada reinicio.

Se niega con el código de salida 3 cuando no hay ningún agente instalado (el mensaje nombra agent install -c <file>), mientras el agente saca la máquina de la estructura antigua, y cuando systemd no conoce la unidad del agente (el mensaje nombra agent remove).

Falla con el código de salida 1 cuando el agente no arranca: systemd no puede iniciar la unidad, o su proceso termina dentro de los cinco segundos. El error nombra la unidad y dónde están sus últimas líneas de registro: el registro del agente (agent logs) y el journal (journalctl -u <unit>).

ironflock agent stop

Detiene el servicio del agente. El dispositivo pasa a estar fuera de línea en IronFlock, y el acceso remoto a través de IronFlock desaparece con el agente: una sesión que llegó por esa vía (la terminal del dispositivo en IronFlock Studio, SSH a través de IronFlock) termina, e IronFlock no puede alcanzar el dispositivo hasta que el agente vuelva a ejecutarse. Las apps siguen ejecutándose, ya que las ejecuta Docker, no el agente.

ironflock agent stop [flags]

Se ejecuta en: Linux, con un agente instalado. Root: necesario. Pregunta: sí, después de decir qué termina al detener el agente; --yes responde.

El comando no tiene flags propios. agent start vuelve a iniciar el agente, y también el siguiente arranque. Un agente detenido no se puede volver a iniciar a través de IronFlock. Un agente que no se ejecuta no tiene nada que detener; entonces el comando no pregunta nada, y el resultado no tiene action.

# Detener el agente; el comando dice qué termina con ello y pregunta
sudo ironflock agent stop
# Detenerlo sin pregunta
sudo ironflock agent stop --yes

$ sudo ironflock agent stop --yes
Stopping the agent (ironflock-device-agent.service) takes this device offline in IronFlock.
The remote access through IronFlock goes with it: a session that came that way (the device's terminal in Studio, SSH through IronFlock) ends.
The apps keep running. 'sudo ironflock agent start' starts the agent again, and so does the next boot.
The agent is stopped (ironflock-device-agent.service): the device is offline in IronFlock, and its apps keep running. 'sudo ironflock agent start' starts the agent again.

{"action":"stopped","unit":"ironflock-device-agent.service","state":"stopped"}

Se niega con el código de salida 3 en los mismos casos que agent restart. La respuesta no, o una pregunta sin terminal y sin --yes, lo termina con el código de salida 4.

ironflock agent start

Inicia el servicio del agente cuando no se ejecuta, y comprueba que el agente arranca, igual que agent restart: su unidad tiene que estar en ejecución cinco segundos con un proceso. Un agente que ya se ejecuta se deja como está, y el resultado no tiene entonces action.

ironflock agent start [flags]

Se ejecuta en: Linux, con un agente instalado. Root: necesario. Pregunta: nada. El comando no tiene flags propios.

# Iniciar el agente
sudo ironflock agent start
# Iniciarlo y leer su proceso como JSON
sudo ironflock agent start --json

$ sudo ironflock agent start
The agent started: ironflock-device-agent.service runs, with process 4242. The device appears online in IronFlock within a minute.

Con --json, para un agente que ya se ejecuta:

{"unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

Se niega y falla igual que agent restart: código de salida 3 cuando no hay ningún agente instalado, mientras el agente saca la máquina de la estructura antigua, y cuando systemd no conoce la unidad del agente; código de salida 1 cuando el agente no arranca.

ironflock agent logs

Muestra el registro del agente, /var/log/ironflock/device-agent.log, y los archivos a los que el agente lo ha rotado. No cambia nada.

ironflock agent logs [flags]

Se ejecuta en: Linux, con un agente instalado; lee los archivos y no necesita systemd. Root: necesario, ya que el agente escribe su registro solo para root (modo 0600). Pregunta: nada.

A los 100 MB, el agente renombra su registro a device-agent-<time>.log en la misma carpeta y empieza uno nuevo; conserva dos. El comando lee el registro y estos archivos.

El agente escribe un objeto JSON por línea: la hora de la entrada (al segundo), su nivel, su mensaje y más campos. La forma de texto muestra una entrada como IronFlock Studio muestra el registro del agente: la hora en UTC, el nivel, el mensaje y su error. Una línea que no es una entrada, como la traza de pila de un fallo, se muestra tal cual. Los caracteres de control se escapan (\n, \x1b), así que una entrada ocupa una línea en la terminal y no puede controlarla. Con --json, cada línea es un objeto JSON en stdout: la entrada tal como la escribió el agente, con todos sus campos, o {"message":...} para una línea que no es una entrada.

• --since empieza con la primera entrada de ese momento o posterior. Las líneas se mantienen en el orden en que las escribió el agente. Una línea sin hora pertenece a la entrada anterior.
• Con --follow, una línea se muestra en cuanto está completa. Cuando el agente empieza un archivo nuevo, primero viene el resto del antiguo y después el nuevo desde su inicio. Si el registro aún no existe, el comando espera a que aparezca. Ctrl-C termina el comando con el código de salida 0; con --host, Ctrl-C termina la ejecución con el código de salida 130.
• Cuando el agente aún no ha escrito ningún registro, stderr lo indica, stdout se queda vacío y el código de salida es 0.

Ejemplos

# Las últimas 100 líneas
sudo ironflock agent logs
# Todo lo de la última hora
sudo ironflock agent logs --since 1h
# Las últimas 20 líneas y después cada línea nueva hasta Ctrl-C
sudo ironflock agent logs --follow --lines 20
# Los últimos diez minutos como JSON, un objeto por línea
sudo ironflock agent logs --since 10m --json

Resultado

$ sudo ironflock agent logs --lines 3
2026-11-10T11:58:02Z INFO connected to IronFlock
2026-11-10T11:58:03Z INFO 3 apps running
2026-11-10T11:59:40Z ERROR pulling demo-app:1.2 failed: context deadline exceeded

{"level":"info","time":"2026-11-10T11:58:02Z","caller":"agent.go:212","message":"connected to IronFlock"}

Cuándo se niega

Un --since que no es ni una duración ni una hora, una duración negativa y un --lines que no es ni un número ni all son líneas de comandos incorrectas (código de salida 2). El comando se niega con el código de salida 3 cuando no se ejecuta como root y cuando no hay ningún agente instalado (el mensaje nombra agent install -c <file>).