Instalación

Una sola línea instala ironflock en Linux o macOS. Necesita root, porque escribe en /usr/local/bin. Más adelante, ironflock self-update lo lleva al release más reciente, e ironflock version --check te dice si ha salido uno más reciente.

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash

Qué hace la línea de instalación

1. Detecta el sistema (Linux o macOS) y la arquitectura de la máquina: amd64, arm64 o ARM de 32 bits (v5 a v7) en Linux, Apple silicon o Intel en macOS. En Apple silicon, un shell que se ejecuta bajo Rosetta 2 también recibe la compilación para Apple silicon.
2. Descarga version.txt y el ironflock de esa versión para esta máquina desde https://instance-registry.ironflock.com/dl/cli/.
3. Comprueba ambos con la clave de release de IronFlock que lleva el script. En Linux comprueba la firma OpenPGP (.asc) con sqv o gpgv. En macOS comprueba la firma RSA simple de la misma clave (.sig) con el /usr/bin/openssl del sistema, para que no haya que instalar nada antes.
4. Instala el binario como /usr/local/bin/ironflock, en lugar del que hubiera. El archivo nuevo se copia junto al antiguo y se renombra sobre él, de modo que un ironflock que se esté ejecutando en ese momento conserva el binario con el que arrancó. En un Mac sin /usr/local/bin, el script crea la carpeta.
5. Ejecuta ironflock con los argumentos indicados después de bash -s --. Sin argumentos, solo instala e indica el siguiente paso.

En una máquina Linux con CPU amd64, la salida tiene este aspecto:

Download base: https://instance-registry.ironflock.com/dl
Downloading ironflock 2.0.2 (linux/amd64)...
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788).
Installed ironflock 2.0.2 as /usr/local/bin/ironflock.

Connect this machine to IronFlock with:
  sudo ironflock agent install -c /path/to/device.flock
All commands: ironflock --help
Tab completion in your shell: ironflock completion --help

En un Mac, el siguiente paso que indica es ironflock os flash, que escribe IronFlockOS para un dispositivo en una memoria USB o una tarjeta SD. Cuando reemplaza un ironflock que ya estaba instalado, la línea Installed termina con , in place of the one that was there.

Requisitos

• Root — el script escribe en /usr/local/bin. Ejecútalo con sudo bash.
• curl o wget — para las descargas.
• En Linux, base64 y sqv o gpgv — para comprobar la firma. apt depende de sqv o de gpgv, así que todo Debian y todo Ubuntu tiene uno de los dos. Si no hay ninguno, el script se detiene e indica apt install gpgv.
• En macOS, nada que no venga con el sistema.

El script lo ejecuta un shell POSIX: bash, sh, dash o BusyBox ash.

Una firma ausente o incorrecta

Una firma ausente o incorrecta detiene el script antes de que instale nada, y un ironflock instalado antes queda como estaba. El script termina con el código de salida 1 y una línea en stderr, por ejemplo:

install.sh: https://instance-registry.ironflock.com/dl/cli/linux/amd64/2.0.2/ironflock is not signed by IronFlock: not installing it

Una descarga que falla detiene el script de la misma forma: no se instala nada.

Instalar y ejecutar un comando en una sola línea

Los argumentos después de bash -s -- van a ironflock una vez instalado. Esta línea instala ironflock y conecta la máquina a IronFlock como el dispositivo del archivo de configuración del dispositivo (.flock) device.flock:

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c device.flock

Con curl ... | bash, la entrada estándar del script es el propio script. Por eso el script deja que ironflock lea de tu terminal, de modo que las preguntas del comando te siguen llegando y las respondes como siempre. Sin terminal (un script de cloud-init, CI), ironflock no recibe entrada: un comando que pregunta termina con el código de salida 4, salvo que añadas --yes. El script termina con el código de salida de ironflock. ironflock agent install describe el comando.

Actualizar

sudo ironflock self-update reemplaza ironflock por el release más reciente, tras las mismas comprobaciones con la clave de release de IronFlock (ironflock self-update). ironflock version --check muestra la versión que tienes y si ha salido un release más reciente (ironflock version).

La línea de instalación del principio de esta página también actualiza: vuelve a ejecutarla y reemplaza /usr/local/bin/ironflock por el release actual.

En un dispositivo IronFlockOS, ironflock viene con el sistema, e ironflock os update lo actualiza junto con el sistema.

Verificar antes el script de instalación

Para comprobar el propio install.sh antes de que se ejecute como root, descárgalo con su firma, importa la clave de release y verifica la firma con gpg:

curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/cli/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.sh

gpg tiene que informar de una firma válida de la clave con la huella F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. Compárala con la clave IronFlock Bootstrap en Claves de firma. Después ejecuta el script verificado, sin argumentos o con los argumentos para ironflock:

sudo bash install.sh
sudo bash install.sh agent install -c device.flock

Base de descarga

ironflock y el script de instalación descargan desde la nube de IronFlock, https://instance-registry.ironflock.com/dl. Una base de descarga distinta, como una réplica en tu red, se indica de una de estas dos formas. Para un dispositivo de un appliance de IronFlock, algunos comandos encuentran por sí mismos la réplica de descargas del appliance:

Bajo la base de descarga, el script de instalación lee cli/version.txt y cli/<system>/<arch>/<version>/ironflock, cada uno con su firma .asc y .sig. Los comprueba con la clave de release que lleva, sea cual sea la base de descarga, de modo que una réplica sirve sin cambios los archivos firmados de IronFlock. ironflock lee el catálogo y las imágenes de IronFlockOS bajo ironflockos/, el agente del dispositivo bajo device-agent/ y, bajo cli/, el release más reciente (version.txt, para self-update y version --check) y los binarios ironflock (para self-update y, con --host, los de otras plataformas).

Por defecto, sudo no transmite las variables de tu shell. Define la variable después de sudo, o usa el flag:

# Instalar ironflock desde una réplica
curl -fsSL https://mirror.example.com/dl/cli/install.sh | sudo IRONFLOCK_DL_BASE=https://mirror.example.com/dl bash
 
# Conectar esta máquina con el agente de la réplica
sudo ironflock agent install -c device.flock --download-base https://mirror.example.com/dl

Dos comandos usan la base de descarga de otra forma. agent update hace que el agente se actualice desde su propio servidor de actualizaciones, el update_url de su archivo .flock, y la base de descarga no lo cambia. os update toma el flag, después la variable y después el update_url del archivo .flock del agente. Con --host, la base de descarga se transmite a la otra máquina; una base de descarga con credenciales (https://user:[email protected]/dl) termina con el código de salida 2 antes de llegar a ninguna máquina.

Dispositivos de un appliance de IronFlock

El archivo .flock que emite un appliance de IronFlock indica la réplica de descargas del appliance como servidor de actualizaciones del agente (update_url), por ejemplo http://10.0.0.5:15002/dl, o https://registry.<domain>/dl cuando el appliance funciona con un dominio. Cuando no están definidos ni --download-base ni IRONFLOCK_DL_BASE, agent install, doctor y os install toman sus archivos de esa réplica, de modo que una máquina que alcanza el appliance pero no ironflock.com se puede conectar o convertir. Un archivo .flock de la nube de IronFlock indica un host de la nube y usa la nube.

• Lo que la réplica no ofrece viene de la misma ruta bajo la base de descarga de la nube de IronFlock, con una advertencia: para agent install, una línea Warning: en stderr y una entrada de warnings en el resultado de --json; para os install, una advertencia en el plan; para doctor, un warning de la comprobación download_tree. agent install y os install solo fallan cuando ni la réplica ni la nube ofrecen un archivo, y entonces su error indica ambas.
• agent install y os install llegan a la réplica directamente, y a la nube a través del proxy, si lo hay.
• 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.

Algunas descargas siguen viniendo de otro sitio:

• install.sh y el binario ironflock vienen de ironflock.com. Con --host, el binario va de tu computadora a la máquina (Máquinas remotas por SSH).
• agent install toma los paquetes de la distribución y Docker de sus propios servidores.
• self-update y version --check leen el flag, después la variable y, si no hay ninguno, la nube de IronFlock, no la réplica del appliance.

Después de la instalación, el agente recibe sus actualizaciones del appliance. Consulta Dispositivos de borde.

Autocompletado con Tab

ironflock completion imprime el script que permite a tu shell completar líneas de comandos de ironflock al pulsar Tab.

ironflock completion <shell>

El shell es bash, zsh o fish. Se ejecuta en Linux y macOS. Sin root. No pregunta nada. El comando no tiene flags propios; se aplican los flags globales.

Ejecuta la línea de tu shell para tener autocompletado en el shell en el que escribes. Añade la línea al archivo de la tercera columna para tenerlo en cada shell nuevo:

El script completa:

• los comandos y sus flags;
• los valores de los flags que admiten uno entre unos pocos: --channel, --variant y --kernel de os images, --channel de os update, y --installer-confirm, --installer-after y --installer-allow-usb de os flash;
• un archivo .flock para -c;
• los nombres de archivo del shell para --hosts, --proxy-password-file, --wifi-password-file, --image-file, --output, --drive y --disk.

Los demás flags y los argumentos de otros comandos no completan nada. Para completar, el script pregunta a ironflock qué palabras encajan, y ironflock responde a partir de su propia lista de comandos: completar no ejecuta ningún comando, no lista ninguna unidad, no descarga nada y no llega a ninguna otra máquina, también cuando la línea contiene --host. Con --host o --hosts, ironflock completion se responde en esta máquina, igual que --help.

# Autocompletar en el bash en el que escribes
eval "$(ironflock completion bash)"
 
# Autocompletar en cada bash nuevo
echo 'eval "$(ironflock completion bash)"' >> ~/.bashrc

$ eval "$(ironflock completion bash)"
$ ironflock os images --kernel <Tab>
rt   std

Con --json, el resultado es el script dentro de un objeto JSON:

{"shell":"bash","script":"..."}

Un shell ausente o desconocido, o más de uno, es una línea de comandos incorrecta: código de salida 2, y el error indica los shells que acepta.

ironflock version

Imprime la versión del binario ironflock y la plataforma para la que se compiló. Con --check, pregunta además al servidor de descargas si ha salido un release más reciente.

ironflock version [flags]

Se ejecuta en Linux y macOS. Sin root. No pregunta nada. Se aplican los flags globales.

# La versión de ironflock en esta máquina
ironflock version
 
# Lo mismo en JSON
ironflock version --json
 
# El binario que se ejecuta en otra máquina por SSH: misma versión, plataforma de esa máquina
ironflock --host pi@device-17 version
 
# ¿Ha salido un release más reciente?
ironflock version --check

ironflock 2.0.2 linux/amd64

{"version":"2.0.2","os":"linux","arch":"amd64"}

Con --host, la plataforma es la de la otra máquina, por ejemplo ironflock 2.0.2 linux/arm64: la otra máquina ejecuta un binario de la misma versión para su propia plataforma.

Una compilación de desarrollo indica su commit: 2.0.0-23-g5b38681 es la compilación del commit 5b38681, 23 commits después del release 2.0.0.

¿Ha salido un release más reciente?

--check lee cli/version.txt de la base de descarga (--download-base; si no, IRONFLOCK_DL_BASE; si no, la nube de IronFlock) y lo comprueba con su firma (.asc) mediante la clave de release de IronFlock que lleva el binario. Pregunta a través del proxy que definió agent configure (/etc/ironflock/proxy.env) o, si no lo hay, a través del proxy del entorno. Solo root lee ese archivo, así que sin root usa el del entorno. version --check y self-update son los únicos comandos que preguntan por el release más reciente; ningún comando lo hace por sí solo.

Una segunda línea en stdout dice lo que encontró y qué instala un release más reciente: self-update o, en IronFlockOS, os update.

$ ironflock version --check
ironflock 2.0.3 linux/amd64
ironflock 2.1.0 is out at https://instance-registry.ironflock.com/dl. 'sudo ironflock self-update' installs it.

Cuando version.txt indica la versión de este binario, la segunda línea es This is the newest release. Cuando este binario es más reciente, una compilación de desarrollo posterior al release, la línea lo dice. Una compilación de desarrollo x.y.z-N-g<commit> cuenta como más reciente que el release x.y.z y más antigua que el siguiente; con N = 0 equivale a x.y.z, y la línea dice que no ha salido ningún release más reciente.

Con --json, el objeto tiene dos campos más: latest_version, lo que indica version.txt, y newer, si es más reciente que este binario.

{"version":"2.0.3","os":"linux","arch":"amd64","latest_version":"2.1.0","newer":true}

El código de salida es 0 tanto si ha salido un release más reciente como si no. Es 1 cuando el servidor no responde, no tiene version.txt o tiene uno que no está firmado con la clave. Con --host, la primera línea indica el binario de esta compilación, como hace version, y la otra máquina pregunta al servidor.

ironflock self-update

Reemplaza el binario ironflock que se ejecuta por el release más reciente, o por el release que indica --version, también uno más antiguo. El release se comprueba con la clave de release de IronFlock antes de que cambie nada en el disco.

ironflock self-update [flags]

Se ejecuta en: Linux y macOS; no en IronFlockOS. Root: necesario para /usr/local/bin/ironflock (Quién puede reemplazar el binario). Pregunta: sí, después de decir qué release reemplaza a cuál; --yes responde.

# Actualizar ironflock al release más reciente; el comando pregunta antes
sudo ironflock self-update
 
# Actualizar sin pregunta y leer el resultado como JSON
sudo ironflock self-update --yes --json
 
# Volver a un release más antiguo
sudo ironflock self-update --version 2.0.3
 
# Actualizar el ironflock instalado en otra máquina
ironflock --host pi@device-17 self-update --yes

Qué reemplaza y con qué

• El archivo. El binario que se ejecuta, con todos los enlaces simbólicos resueltos: se reemplaza el archivo al que lleva un enlace, y el enlace se queda. El comando indica el archivo antes que nada. La carpeta /opt/ironflock/device-init de una instalación del agente guarda el registro de esa instalación, ningún ironflock, y el comando no la toca.
• El release. Sin --version, el más reciente: el que indica cli/version.txt de la base de descarga (--download-base; si no, IRONFLOCK_DL_BASE; si no, la nube de IronFlock), el archivo que lee la línea de instalación. El binario de un release es cli/<system>/<arch>/<version>/ironflock. No hay canales: otro árbol es otra base de descarga, como una réplica.
• El proxy. Las descargas pasan por el proxy que definió agent configure (/etc/ironflock/proxy.env) o, si no lo hay, por HTTP_PROXY, HTTPS_PROXY y NO_PROXY del entorno. sudo y un comando con --host no tienen proxy en su entorno. El archivo es de root, así que una ejecución sin root usa el proxy del entorno y lo indica. El comando indica cuándo usa el del archivo.
• Nada que hacer. Cuando el binario ya es ese release, o más reciente (una compilación de desarrollo posterior), el comando lo indica y termina con el código de salida 0, sin pregunta y sin descarga; el outcome del resultado es current. Sin --version nunca vuelve a un release más antiguo.

Las comprobaciones

Antes de que se reemplace el binario:

1. version.txt se comprueba con su firma mediante la clave de release de IronFlock que lleva el binario en ejecución.
2. El binario nuevo se comprueba con su firma mediante la misma clave, y con su información de compilación: el programa ironflock, para esta plataforma, de un árbol de código fuente sin modificar.
3. Se escribe junto al antiguo, en la misma carpeta, con el modo, el propietario y el grupo del antiguo, y se ejecuta una vez (version --json). Tiene que decir que es el release pedido, en esta plataforma. Una firma no vincula ninguna versión, así que aquí se rechaza un binario firmado más antiguo servido en lugar del más reciente.
4. Solo entonces se renombra sobre el antiguo, en un único paso.

No hace falta sqv ni gpgv: ironflock comprueba las firmas por sí mismo.

Un archivo que no supera una comprobación nunca reemplaza el binario, y el archivo nuevo que está a su lado se vuelve a eliminar. Una ejecución que falla, se rechaza o se interrumpe deja el binario antiguo como estaba. Un comando de ironflock que se está ejecutando mientras se reemplaza el archivo sigue con el archivo con el que arrancó. Un segundo Ctrl-C, o un corte de corriente, entre la escritura y el renombrado puede dejar atrás el archivo nuevo (.ironflock.new-* junto al binario); elimínalo a mano.

Quién puede reemplazar el binario

El comando necesita permiso de escritura en la carpeta del binario, y tiene que ejecutarse como el propietario del binario y miembro de su grupo, o como root, para que el archivo nuevo conserve el propietario y el grupo. Para /usr/local/bin/ironflock, donde lo pone la línea de instalación, eso es root. Si no, el comando termina con el código de salida 3 antes de descargar nada, indica el propietario o el grupo, e indica la línea de comandos con sudo.

IronFlockOS y otras máquinas

• IronFlockOS trae ironflock con su sistema, y cada actualización del SO reemplaza el sistema entero. Allí el comando termina con el código de salida 3 antes de examinar nada, e indica os update. En la memoria del instalador de IronFlockOS se niega como lo hacen los comandos agent.
• Con --host, el binario que se ejecuta es la copia de la ejecución, que se elimina cuando termina el comando. Por eso el comando actualiza en su lugar /usr/local/bin/ironflock de la máquina. Sin ese archivo termina con el código de salida 3 e indica la línea de instalación. Un ironflock instalado que no se ejecuta, o que no dice su versión, también lo termina con el código de salida 3, antes de descargar nada: la línea de instalación instala ironflock de nuevo.
• En varias máquinas (--host más de una vez, --hosts), con --yes, cada máquina actualiza su /usr/local/bin/ironflock.

Resultado

$ sudo ironflock self-update
This ironflock is 2.0.3, at /usr/local/bin/ironflock.
Download base: https://instance-registry.ironflock.com/dl (from default)
The downloads go through the proxy of the install's record (/etc/ironflock/proxy.env).
The newest release at https://instance-registry.ironflock.com/dl is ironflock 2.1.0 (its version.txt is signed by key F6C94D96CE315377ACA7C8EA4990543373212788).
ironflock 2.1.0 replaces 2.0.3 at /usr/local/bin/ironflock.
A command of ironflock that runs now goes on with 2.0.3; the next one runs 2.1.0.
? Install ironflock 2.1.0? Yes
Downloading ironflock 2.1.0 for linux/amd64 from https://instance-registry.ironflock.com/dl.
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788): the program ironflock for linux/amd64.
The new file says it is ironflock 2.1.0 linux/amd64; it is in place.
ironflock at /usr/local/bin/ironflock is updated from 2.0.3 to 2.1.0.

El binario se descarga después de la respuesta. Sin terminal, o con --json, el comando necesita --yes. Con --json, para un binario que ya es el release más reciente:

{"outcome":"current","path":"/usr/local/bin/ironflock","version":"2.1.0","latest_version":"2.1.0"}

Códigos de salida