Installation

Une ligne installe ironflock sous Linux ou macOS. Elle nécessite root, car elle écrit dans /usr/local/bin. Par la suite, ironflock self-update l’amène à la version la plus récente, et ironflock version --check vous indique si une version plus récente est sortie.

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

Ce que fait la ligne d’installation

1. Elle détermine le système (Linux ou macOS) et l’architecture de la machine : amd64, arm64 ou ARM 32 bits (v5 à v7) sous Linux, Apple silicon ou Intel sous macOS. Sur Apple silicon, un shell qui s’exécute sous Rosetta 2 reçoit lui aussi le binaire pour Apple silicon.
2. Elle télécharge version.txt et l’ironflock de cette version pour cette machine depuis https://instance-registry.ironflock.com/dl/cli/.
3. Elle vérifie les deux avec la clé de publication d’IronFlock que contient le script. Sous Linux, elle vérifie la signature OpenPGP (.asc) avec sqv ou gpgv. Sous macOS, elle vérifie la signature RSA simple de la même clé (.sig) avec le /usr/bin/openssl du système, si bien que rien ne doit être installé au préalable.
4. Elle installe le binaire sous /usr/local/bin/ironflock, à la place de celui qui s’y trouve. Le nouveau fichier est copié à côté de l’ancien, puis renommé par-dessus : un ironflock qui s’exécute à ce moment-là conserve ainsi le binaire à partir duquel il a démarré. Sur un Mac sans /usr/local/bin, le script crée le dossier.
5. Elle exécute ironflock avec les arguments donnés après bash -s --. Sans argument, elle se contente d’installer et indique l’étape suivante.

Sur une machine Linux avec un processeur amd64, la sortie ressemble à ceci :

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

Sur un Mac, l’étape suivante indiquée est ironflock os flash, qui écrit IronFlockOS pour un appareil sur une clé USB ou une carte SD. Lorsque le script remplace un ironflock déjà présent, la ligne Installed se termine par , in place of the one that was there.

Prérequis

• Root — le script écrit dans /usr/local/bin. Exécutez-le avec sudo bash.
• curl ou wget — pour les téléchargements.
• Sous Linux, base64 et sqv ou gpgv — pour la vérification de la signature. apt dépend de sqv ou de gpgv, si bien que chaque Debian et chaque Ubuntu dispose de l’un des deux. Si les deux manquent, le script s’arrête et indique apt install gpgv.
• Sous macOS, rien qui ne soit déjà fourni avec le système.

Le script s’exécute avec un shell POSIX : bash, sh, dash ou BusyBox ash.

Signature absente ou incorrecte

Une signature absente ou incorrecte arrête le script avant qu’il n’installe quoi que ce soit, et un ironflock installé auparavant reste tel quel. Le script se termine avec le code de sortie 1 et une ligne sur stderr, par exemple :

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

Un téléchargement qui échoue arrête le script de la même façon : rien n’est installé.

Installer et exécuter une commande en une ligne

Les arguments qui suivent bash -s -- sont transmis à ironflock une fois celui-ci installé. Cette ligne installe ironflock et connecte la machine à IronFlock comme l’appareil du fichier de configuration de l’appareil (.flock) device.flock :

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

Avec curl ... | bash, l’entrée standard du script est le script lui-même. Le script laisse donc ironflock lire depuis votre terminal : les questions de la commande vous parviennent quand même, et vous y répondez comme d’habitude. Sans terminal (un script cloud-init, la CI), ironflock ne reçoit aucune entrée : une commande qui pose une question se termine avec le code de sortie 4, sauf si vous ajoutez --yes. Le script se termine avec le code de sortie d’ironflock. ironflock agent install décrit la commande.

Mise à jour

sudo ironflock self-update remplace ironflock par la version la plus récente, après les mêmes vérifications avec la clé de publication d’IronFlock (ironflock self-update). ironflock version --check affiche la version que vous avez et indique si une version plus récente est sortie (ironflock version).

La ligne d’installation en haut de cette page fait aussi la mise à jour : exécutez-la à nouveau, et elle remplace /usr/local/bin/ironflock par la version actuelle.

Sur un appareil IronFlockOS, ironflock est fourni avec le système, et ironflock os update le met à jour avec le système.

Vérifier d’abord le script d’installation

Pour vérifier install.sh lui-même avant qu’il ne s’exécute en tant que root, téléchargez-le avec sa signature, importez la clé de publication et vérifiez la signature avec 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 doit signaler une signature valide de la clé dont l’empreinte est F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. Comparez-la avec la clé IronFlock Bootstrap sur la page Clés de signature. Exécutez ensuite le script vérifié, sans argument ou avec les arguments destinés à ironflock :

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

Base de téléchargement

ironflock et le script d’installation téléchargent depuis le cloud IronFlock, https://instance-registry.ironflock.com/dl. Une autre base de téléchargement, par exemple un miroir sur votre réseau, s’indique de l’une de ces deux façons. Pour un appareil d’une IronFlock Appliance, quelques commandes trouvent d’elles-mêmes le miroir de téléchargement de l’appliance :

Sous la base de téléchargement, le script d’installation lit cli/version.txt et cli/<system>/<arch>/<version>/ironflock, chacun avec ses signatures .asc et .sig. Il les vérifie avec la clé de publication qu’il contient, quelle que soit la base de téléchargement : un miroir sert donc les fichiers signés d’IronFlock sans les modifier. ironflock lit le catalogue et les images d’IronFlockOS sous ironflockos/, l’agent de l’appareil sous device-agent/ et, sous cli/, la version la plus récente (version.txt, pour self-update et version --check) et les binaires ironflock (pour self-update et, pour --host, ceux des autres plateformes).

Par défaut, sudo ne transmet pas les variables de votre shell. Définissez la variable après sudo, ou passez l’option :

# Installer ironflock depuis un miroir
curl -fsSL https://mirror.example.com/dl/cli/install.sh | sudo IRONFLOCK_DL_BASE=https://mirror.example.com/dl bash
 
# Connecter cette machine avec l'agent du miroir
sudo ironflock agent install -c device.flock --download-base https://mirror.example.com/dl

Deux commandes utilisent la base de téléchargement autrement. agent update laisse l’agent se mettre à jour depuis son propre serveur de mise à jour, l’update_url de son fichier .flock, et la base de téléchargement n’y change rien. os update prend l’option, puis la variable, puis l’update_url du fichier .flock de l’agent. Via --host, la base de téléchargement est transmise à l’autre machine ; avec une base qui contient des identifiants (https://user:[email protected]/dl), la commande se termine avec le code de sortie 2 avant qu’aucune machine ne soit jointe.

Appareils d’une IronFlock Appliance

Le fichier .flock qu’émet une IronFlock Appliance désigne le miroir de téléchargement de l’appliance comme serveur de mise à jour de l’agent (update_url), par exemple http://10.0.0.5:15002/dl, ou https://registry.<domain>/dl lorsque l’appliance fonctionne avec un domaine. Lorsque ni --download-base ni IRONFLOCK_DL_BASE ne sont définis, agent install, doctor et os install prennent leurs fichiers sur ce miroir : une machine qui joint l’appliance mais pas ironflock.com peut ainsi être connectée ou convertie. Un fichier .flock du cloud IronFlock nomme un hôte du cloud et prend le cloud.

• Ce que le miroir ne fournit pas provient du même chemin sous la base de téléchargement du cloud IronFlock, avec un avertissement : pour agent install, une ligne Warning: sur stderr et une entrée de warnings dans le résultat --json ; pour os install, un avertissement dans le plan ; pour doctor, un warning de la vérification download_tree. agent install et os install n’échouent que lorsque ni le miroir ni le cloud ne fournissent un fichier, et leur erreur nomme alors les deux.
• agent install et os install joignent le miroir directement, et le cloud via le proxy, s’il y en a un.
• Un miroir HTTPS dont le certificat provient de la propre CA de l’appliance ne fonctionne que là où le système de la machine fait confiance à cette CA.

Certains téléchargements proviennent toujours d’ailleurs :

• install.sh et le binaire ironflock proviennent d’ironflock.com. Avec --host, le binaire va de votre ordinateur à la machine (Machines distantes via SSH).
• agent install prend les paquets de la distribution et Docker sur leurs propres serveurs.
• self-update et version --check lisent l’option, puis la variable, sinon le cloud IronFlock, et non le miroir de l’appliance.

Après l’installation, l’agent reçoit ses mises à jour de l’appliance. Voir Appareils edge.

Complétion par tabulation

ironflock completion affiche le script qui permet à votre shell de compléter les lignes de commande ironflock lorsque vous appuyez sur Tab.

ironflock completion <shell>

Le shell est bash, zsh ou fish. S’exécute sous Linux et macOS. Sans root. Ne pose aucune question. La commande n’a pas d’options propres ; les options globales s’appliquent.

Exécutez la ligne de votre shell pour activer la complétion dans le shell où vous tapez. Ajoutez la ligne au fichier de la troisième colonne pour l’activer dans chaque nouveau shell :

Le script complète :

• les commandes et leurs options ;
• les valeurs des options qui n’en acceptent que quelques-unes : --channel, --variant et --kernel de os images, --channel de os update, et --installer-confirm, --installer-after et --installer-allow-usb de os flash ;
• un fichier .flock pour -c ;
• les noms de fichiers du shell pour --hosts, --proxy-password-file, --wifi-password-file, --image-file, --output, --drive et --disk.

Les autres options et les arguments des autres commandes ne se complètent pas. Pour compléter, le script demande à ironflock les mots qui conviennent, et ironflock répond à partir de sa propre liste de commandes : la complétion n’exécute aucune commande, ne liste aucun lecteur, ne télécharge rien et ne joint aucune autre machine, même lorsque la ligne contient --host. Avec --host ou --hosts, ironflock completion obtient sa réponse sur cette machine, comme --help.

# Compléter dans le bash où vous tapez
eval "$(ironflock completion bash)"
 
# Compléter dans chaque nouveau bash
echo 'eval "$(ironflock completion bash)"' >> ~/.bashrc

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

Avec --json, le résultat est le script dans un objet JSON :

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

Un shell absent ou inconnu, ou plusieurs shells, constituent une ligne de commande erronée : code de sortie 2, et l’erreur indique les shells acceptés.

ironflock version

Affiche la version du binaire ironflock et la plateforme pour laquelle il a été compilé. Avec --check, elle demande aussi au serveur de téléchargement si une version plus récente est sortie.

ironflock version [flags]

S’exécute sous Linux et macOS. Sans root. Ne pose aucune question. Les options globales s’appliquent.

# La version d'ironflock sur cette machine
ironflock version
 
# La même chose en JSON
ironflock version --json
 
# Le binaire qui s'exécute sur une autre machine via SSH : même version, plateforme de cette machine
ironflock --host pi@device-17 version
 
# Une version plus récente est-elle sortie ?
ironflock version --check

ironflock 2.0.2 linux/amd64

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

Via --host, la plateforme est celle de l’autre machine, par exemple ironflock 2.0.2 linux/arm64 : l’autre machine exécute un binaire de la même version pour sa propre plateforme.

Un build de développement nomme son commit : 2.0.0-23-g5b38681 est le build du commit 5b38681, 23 commits après la version 2.0.0.

Une version plus récente est-elle sortie ?

--check lit cli/version.txt de la base de téléchargement (--download-base, sinon IRONFLOCK_DL_BASE, sinon le cloud IronFlock) et le vérifie par rapport à sa signature (.asc) avec la clé de publication d’IronFlock que contient le binaire. La requête passe par le proxy qu’a défini agent configure (/etc/ironflock/proxy.env), sinon par le proxy de l’environnement. Seul root lit ce fichier : sans root, la commande prend donc celui de l’environnement. version --check et self-update sont les seules commandes qui demandent la version la plus récente ; aucune commande ne le fait d’elle-même.

Une seconde ligne sur stdout indique ce qu’elle a trouvé, et ce qui installe une version plus récente : self-update, ou sur 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.

Lorsque version.txt nomme la version de ce binaire, la seconde ligne est This is the newest release. Lorsque ce binaire est plus récent, un build de développement postérieur à la version, la ligne le dit. Un build de développement x.y.z-N-g<commit> compte comme plus récent que la version x.y.z et plus ancien que la suivante ; avec N = 0, il équivaut à x.y.z, et la ligne indique qu’aucune version plus récente n’est sortie.

Avec --json, l’objet a deux champs de plus : latest_version, ce que nomme version.txt, et newer, qui indique si cette version est plus récente que ce binaire.

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

Le code de sortie est 0, qu’une version plus récente soit sortie ou non. Il vaut 1 lorsque le serveur ne répond pas, n’a pas de version.txt, ou en a un qui n’est pas signé par la clé. Via --host, la première ligne nomme le binaire de ce build, comme le fait version, et c’est l’autre machine qui interroge le serveur.

ironflock self-update

Remplace le binaire ironflock en cours d’exécution par la version la plus récente, ou par celle que nomme --version, y compris une version plus ancienne. La version est vérifiée avec la clé de publication d’IronFlock avant que quoi que ce soit ne change sur le disque.

ironflock self-update [flags]

S’exécute sous : Linux et macOS ; pas sur IronFlockOS. Root : requis pour /usr/local/bin/ironflock (Qui peut remplacer le binaire). Questions : oui, après avoir indiqué quelle version remplace laquelle ; --yes répond.

# Mettre à jour ironflock vers la version la plus récente ; la commande pose d'abord la question
sudo ironflock self-update
 
# Mettre à jour sans question et lire le résultat en JSON
sudo ironflock self-update --yes --json
 
# Revenir à une version plus ancienne
sudo ironflock self-update --version 2.0.3
 
# Mettre à jour l'ironflock installé sur une autre machine
ironflock --host pi@device-17 self-update --yes

Ce qu’elle remplace, et par quoi

• Le fichier. Le binaire en cours d’exécution, une fois chaque lien symbolique résolu : le fichier vers lequel mène un lien est remplacé, et le lien reste. La commande nomme le fichier avant toute autre chose. Le dossier /opt/ironflock/device-init d’une installation de l’agent contient l’enregistrement de cette installation, et non ironflock, et la commande n’y touche pas.
• La version. Sans --version, la plus récente : celle que nomme cli/version.txt de la base de téléchargement (--download-base, sinon IRONFLOCK_DL_BASE, sinon le cloud IronFlock), le fichier que lit la ligne d’installation. Le binaire d’une version est cli/<system>/<arch>/<version>/ironflock. Il n’y a pas de canaux : une autre arborescence est une autre base de téléchargement, par exemple un miroir.
• Le proxy. Les téléchargements passent par le proxy qu’a défini agent configure (/etc/ironflock/proxy.env), sinon par HTTP_PROXY, HTTPS_PROXY et NO_PROXY de l’environnement. sudo et une commande via --host n’ont pas de proxy dans leur environnement. Le fichier appartient à root : une exécution sans root prend donc le proxy de l’environnement et le dit. La commande indique quand elle prend celui du fichier.
• Rien à faire. Lorsque le binaire est déjà cette version, ou plus récent (un build de développement postérieur), la commande le dit et se termine avec le code de sortie 0, sans question ni téléchargement ; l’outcome du résultat est current. Sans --version, elle ne revient jamais à une version plus ancienne.

Les vérifications

Avant que le binaire ne soit remplacé :

1. version.txt est vérifié par rapport à sa signature par la clé de publication d’IronFlock que contient le binaire en cours d’exécution.
2. Le nouveau binaire est vérifié par rapport à sa signature par la même clé, et par rapport à ses informations de build : le programme ironflock, pour cette plateforme, issu d’une arborescence de sources non modifiée.
3. Il est écrit à côté de l’ancien, dans le même dossier, avec le mode, le propriétaire et le groupe de l’ancien, puis exécuté une fois (version --json). Il doit indiquer qu’il est la version demandée, pour cette plateforme. Une signature ne lie aucune version : un binaire signé plus ancien, servi à la place du plus récent, est donc refusé ici.
4. Ce n’est qu’alors qu’il est renommé par-dessus l’ancien, en une seule étape.

Ni sqv ni gpgv ne sont nécessaires : ironflock vérifie lui-même les signatures.

Un fichier qui échoue à une vérification ne remplace jamais le binaire, et le nouveau fichier placé à côté est supprimé. Une exécution qui échoue, qui reçoit la réponse non ou qui est interrompue laisse l’ancien binaire tel quel. Une commande ironflock qui s’exécute pendant le remplacement du fichier continue avec le fichier à partir duquel elle a démarré. Un second Ctrl-C, ou une coupure de courant, entre l’écriture et le renommage peut laisser derrière lui le nouveau fichier (.ironflock.new-* à côté du binaire) ; supprimez-le à la main.

Qui peut remplacer le binaire

La commande a besoin d’un accès en écriture au dossier du binaire, et doit s’exécuter en tant que propriétaire du binaire et membre de son groupe, ou en tant que root, afin que le nouveau fichier garde le propriétaire et le groupe. Pour /usr/local/bin/ironflock, là où la ligne d’installation le place, c’est root. Sinon, la commande se termine avec le code de sortie 3 avant tout téléchargement, nomme le propriétaire ou le groupe, et indique la ligne de commande avec sudo.

IronFlockOS et autres machines

• IronFlockOS apporte ironflock avec son système, et chaque mise à jour de l’OS remplace le système dans son ensemble. La commande s’y termine avec le code de sortie 3 avant d’examiner quoi que ce soit, et nomme os update. Sur la clé d’installation d’IronFlockOS, elle refuse comme le font les commandes agent.
• Via --host, le binaire en cours d’exécution est la copie de l’exécution, supprimée à la fin de la commande. La commande met donc à jour à la place le /usr/local/bin/ironflock de la machine. Sans ce fichier, elle se termine avec le code de sortie 3 et nomme la ligne d’installation. Un ironflock installé qui ne s’exécute pas, ou n’indique pas sa version, la fait aussi se terminer avec le code de sortie 3, avant tout téléchargement : la ligne d’installation installe ironflock à nouveau.
• Sur plusieurs machines (--host plusieurs fois, --hosts), avec --yes, chaque machine met à jour son /usr/local/bin/ironflock.

Résultat

$ 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.

Le binaire est téléchargé après la réponse. Sans terminal, ou avec --json, la commande nécessite --yes. Avec --json, pour un binaire qui est déjà la version la plus récente :

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

Codes de sortie