Commandes de l’agent de l’appareil

Les commandes ironflock agent connectent une machine Linux à IronFlock en tant qu’appareil et s’occupent ensuite de l’agent de l’appareil. Elles vous servent à installer l’agent, à lui donner une autre configuration d’appareil ou un autre proxy, à le mettre à jour, à l’arrêter et à le démarrer, à lire son journal et à le supprimer.

L’agent de l’appareil

L’agent de l’appareil est le programme qui connecte une machine à IronFlock en tant qu’appareil et exécute dans Docker les apps du projet de l’appareil. L’appareil que devient une machine est déterminé par le fichier de configuration de l’appareil (.flock) qu’IronFlock Studio fournit pour chaque appareil (Connecter des appareils).

Chaque commande de l’agent nécessite root et s’exécute sous Linux. Sans root, elle se termine avec le code de sortie 3 et n’appelle pas sudo elle-même (Privilèges root). Sous macOS, les commandes de l’agent se terminent avec le code de sortie 3 avant d’examiner quoi que ce soit ; exécutez-les sur la machine Linux, ou depuis le Mac avec --host. Sur un appareil IronFlockOS, l’image apporte l’agent avec son système : agent install et agent remove y refusent de s’exécuter, et agent configure -c enrôle l’appareil avec un autre .flock.

Chaque commande accepte aussi les options globales --yes, --json, --download-base, --host, --hosts et --parallel (Options globales). Une question nécessite un terminal ; sans terminal, donnez --yes (Questions et confirmation).

Avec --host, une commande s’exécute sur une autre machine via SSH (Machines distantes via SSH). Sur plusieurs machines à la fois (--host donné plusieurs fois, ou --hosts), agent restart, agent start et agent logs s’exécutent telles quelles, mais agent logs --follow pas avec --json. agent stop, agent update, agent configure et agent remove y nécessitent --yes, car personne n’est interrogé, et agent configure n’y accepte pas -c, car un .flock désigne un seul appareil. agent install s’exécute sur une seule machine à la fois.

À quoi ressemble un agent installé

L’agent écrit aussi lui-même quelques paramètres de l’hôte, à chaque démarrage : la slice ironflock.slice dans laquelle il tourne, qui lui réserve de la mémoire, le watchdog de systemd, les paramètres de plantage du noyau et une limite de taille du journal de systemd.

Une machine qu’un installateur IronFlock antérieur a configurée peut encore avoir l’agent dans l’ancienne disposition /opt/reagent (service reagent.service, journal /var/log/reagent.log), que l’agent déplace lui-même vers /opt/ironflock/device-agent ; ironflock status indique la disposition d’une machine, et les cas de refus ci-dessous nomment ceux où elle compte.

ironflock agent install

Installe l’agent de l’appareil dans /opt/ironflock/device-agent, Docker lorsqu’il manque, et les réglages d’hôte d’un appareil, puis connecte la machine à IronFlock en tant qu’appareil du .flock. L’agent démarre immédiatement et se met ensuite à jour lui-même.

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

S’exécute sous : Linux basé sur Debian ou Ubuntu, avec systemd ; pas sur IronFlockOS. Root : requis. Questions : avant d’installer les paquets et Docker, et pour chaque réglage d’hôte ; --yes répond à chaque question par sa valeur par défaut.

La machine a besoin d’un accès à internet, ou au serveur de téléchargement indiqué avec --download-base (Base de téléchargement), ou au miroir de téléchargement de l’appliance que nomme le .flock (D’où vient l’agent). Les hôtes qu’un appareil doit joindre sont listés dans Exigences réseau.

D’où vient l’agent

L’agent, c’est sa table des canaux, son binaire, ainsi que le .sha256 et le .sig du binaire. La commande les prend :

1. de --download-base, sinon de IRONFLOCK_DL_BASE : ce serveur seul ;
2. sinon du miroir de téléchargement de l’IronFlock Appliance que le .flock désigne comme serveur de mise à jour (update_url), lorsque son hôte n’est pas un hôte du cloud IronFlock. Une machine qui joint l’appliance mais pas ironflock.com s’installe de cette façon. Un .flock du cloud IronFlock prend le cloud ;
3. sinon du cloud IronFlock, https://instance-registry.ironflock.com/dl.

La commande nomme la base sur stderr : Download base: ... (from the device's .flock), sinon (from --download-base), (from IRONFLOCK_DL_BASE) ou (from default).

Avec le miroir de l’appliance, les fichiers proviennent d’abord du miroir, et, là où le miroir ne les fournit pas, du même chemin sous la base de téléchargement du cloud IronFlock :

• La table des canaux — lorsque le miroir n’en fournit pas pour l’instant (pas de réponse, aucune table, un statut d’erreur), tout provient du cloud, et la version est celle que nomme la table du cloud. Une table que fournit le miroir et qui est refusée (sa signature, pas de version) fait échouer l’installation, comme avec n’importe quel serveur.
• Le binaire, son .sha256 et son .sig — chacun de ceux que le miroir ne fournit pas provient du cloud. Lorsque les fichiers du miroir ne passent pas les vérifications (somme de contrôle, signature), les trois proviennent du cloud.

Chaque repli est une ligne Warning: ... sur stderr, avec le miroir, le fichier et la raison, et avec --json une entrée de warnings dans le résultat. Lorsque ni le miroir ni le cloud ne fournissent un fichier, l’installation échoue avec une seule erreur qui nomme les deux sources et les deux raisons (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

Le miroir est le serveur de mise à jour du .flock, qui contourne le proxy (Proxy). 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. Les paquets de la distribution et Docker proviennent toujours de leurs propres serveurs, et install.sh et ironflock d’ironflock.com ; avec --host, ironflock va de votre ordinateur à la machine.

Vérifications avant l’installation

Avant de modifier quoi que ce soit, la commande exécute les vérifications de ironflock doctor qui indiquent si elle peut réussir : system, systemd, disk_space, clock, dns, proxy, download_tree, device_endpoint, docker_registry et update_server. Elles portent sur le .flock de -c, avec la base de téléchargement et les options de proxy de l’installation.

Quatre d’entre elles arrêtent l’installation lorsqu’elles échouent, car l’installation échouerait alors à coup sûr, ou à mi-chemin :

Le message nomme la vérification, son constat et son conseil. Tout autre constat est un avertissement sur stderr, et l’installation continue : l’agent se connecte, se met à jour et récupère ses apps dès que le réseau le permet. Un résultat warning ou skipped n’arrête jamais l’installation. Exécutez ironflock doctor -c device.flock pour voir chaque vérification avant d’installer.

Étapes

1. Elle nomme les paquets qu’elle installe et pose la question. Elle les installe avec apt.
2. Elle installe Docker lorsque la machine n’en a pas, et pose d’abord la question.
3. Elle télécharge l’agent du canal de production et le vérifie par rapport à sa somme de contrôle et à sa signature. Une installation qui ne peut pas obtenir d’agent vérifié s’arrête ici, avant toutes les étapes suivantes.
4. Elle configure Docker : le proxy, lorsqu’il y en a un, et, pour un Docker que cette installation a apporté ou qui ne contient encore rien, le data-root dans le dossier de l’agent. Un Docker qui contient des images ou des conteneurs garde sa configuration et ses données.
5. Elle met en place les réglages d’hôte (tableau ci-dessous). Chacun est un choix dans le terminal ; --yes prend la valeur par défaut.
6. Elle installe l’agent dans /opt/ironflock/device-agent et le démarre.

L’installation ajoute aussi une bannière de connexion. Tout ce que l’installation modifie est écrit dans /opt/ironflock/device-init/installed.json. Lorsqu’une étape échoue à partir de l’étape 4, l’erreur indique que la tentative est enregistrée et que la même commande, exécutée à nouveau, l’annule d’abord. Lorsque la commande trouve une telle tentative antérieure, elle l’annule une fois les vérifications passées : elle liste ce qu’elle annule, pose la question, puis installe à nouveau.

Proxy

Les options de proxy définissent le proxy d’entreprise pour les téléchargements de l’installation, pour Docker et pour l’agent. Chaque paramètre provient de son option, sinon des variables d’environnement HTTP_PROXY, HTTPS_PROXY et NO_PROXY (ou de leurs formes en minuscules).

Une URL de proxy ressemble à http://proxy.example.com:3128 ; https:// et socks5:// fonctionnent aussi, et une URL sans schéma est en http://. Lorsque le proxy exige une authentification, l’URL indique l’utilisateur sans le mot de passe, http://[email protected]:3128, et --proxy-password-file fournit le mot de passe. La commande insère le mot de passe dans les URL des options qui nomment un utilisateur.

Avertissement : N’écrivez jamais le mot de passe du proxy dans l’URL. Les lignes de commande apparaissent dans ps et dans l’historique du shell : une URL avec mot de passe est donc refusée comme ligne de commande erronée, et l’erreur ne la répète pas. Mettez le mot de passe sur une ligne d’un fichier, ou transmettez-le via un pipe avec --proxy-password-file /dev/stdin (Secrets).

Outre les hôtes de --no-proxy, ceux-ci contournent le proxy (NO_PROXY) : localhost, 127.0.0.1 et ::1, ainsi que le serveur de téléchargement et le serveur de mise à jour du .flock (son update_url) lorsqu’ils ne sont pas des hôtes du cloud IronFlock, comme une appliance ou un miroir sur le LAN. Les hôtes du cloud IronFlock (ironflock.com, ironflock.dev et les hôtes sous ces domaines, ainsi que storage.googleapis.com) sont sur internet et passent par le proxy.

L’installation écrit le proxy de Docker et de l’agent dans /etc/ironflock/proxy.env, que seul root lit (mode 0600), et Docker redémarre pour l’utiliser. Les drop-ins systemd ironflock-proxy.conf de docker.service et de ironflock-device-agent.service nomment ce fichier et ne contiennent eux-mêmes aucun paramètre : systemctl show révèle donc à chaque utilisateur le nom du fichier, et rien de son contenu. Un drop-in Docker propre à l’hôte (docker.service.d/http-proxy.conf) reste en place ; les paramètres d’IronFlock l’emportent sur ses lignes Environment=, et un avertissement le nomme. Un daemon.json avec proxies conserve ces derniers, car Docker les fait passer avant tous les autres.

Pour modifier les paramètres plus tard, utilisez agent configure. Pour le proxy du site entier, voir Derrière un proxy d’entreprise.

Exemples

# Installer l'agent ; la commande pose une question avant chaque étape
sudo ironflock agent install -c device.flock
# Installer sans questions, et empêcher l'appareil de se mettre en veille
sudo ironflock agent install -c device.flock --yes --disable-suspend
# Installer derrière un proxy qui n'exige pas d'authentification
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# Installer derrière un proxy avec authentification ; le mot de passe provient d'un fichier
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

Résultat

$ 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 ne figure dans le résultat que lorsqu’un fichier provient du cloud IronFlock au lieu du miroir de l’appliance : une entrée pour chacun, comme le disent les lignes Warning:.

Cas de refus

Une ligne de commande erronée se termine avec le code de sortie 2 avant toute exécution : une URL de proxy avec mot de passe ; une URL de proxy qui nomme un utilisateur, sans --proxy-password-file ; --proxy-password-file sans URL de proxy qui nomme un utilisateur ; une valeur qui n’est pas une URL de proxy. Une variable de proxy de l’environnement qui n’est pas une URL de proxy compte aussi ; l’erreur nomme la variable, pas sa valeur.

La commande refuse avec le code de sortie 3, et ne modifie rien, lorsque :

• elle ne s’exécute pas en tant que root, ou la machine n’est pas sous Linux ;
• la machine tourne sous IronFlockOS, avant toute autre chose, root ou non. L’image apporte l’agent et ironflock avec son système, et chaque mise à jour de l’OS remplace le système dans son ensemble. Le message indique que l’appareil s’enrôle avec un .flock sur sa partition IRONFLOCKOS à son prochain démarrage, et que agent configure -c l’enrôle tout de suite. Sur la clé d’installation d’IronFlockOS, il indique que la clé n’est pas un appareil ;
• un agent est déjà installé, y compris dans l’ancienne disposition /opt/reagent. Le message nomme agent configure et agent remove ;
• l’agent fait passer la machine de l’ancienne disposition à la disposition actuelle ;
• une installation antérieure s’est arrêtée avant la mise en place de l’agent, avait déplacé le data-root de Docker, et Docker contient depuis des images ou des conteneurs : annuler cette tentative les supprimerait ;
• l’une des vérifications system, systemd, disk_space ou download_tree échoue. --yes n’y change rien.

Une question qui reçoit la réponse non, ou une question sans terminal et sans --yes, met fin à la commande avec le code de sortie 4. Une étape qui échoue y met fin avec le code de sortie 1.

ironflock agent configure

Modifie ce que l’installation a mis en place : le .flock de l’appareil, le proxy d’entreprise de Docker et de l’agent, ou les deux. Redémarre ce qui doit tenir compte de la modification.

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

S’exécute sous : Linux avec un agent installé ; sur IronFlockOS uniquement avec -c. Root : requis. Questions : avant que Docker ne redémarre pour de nouveaux paramètres de proxy ; --yes répond.

Donnez -c, une option de proxy, ou les deux. Sans aucune des deux, il n’y a rien à modifier : c’est une ligne de commande erronée (code de sortie 2).

Un autre .flock

Avec -c, l’agent reçoit le .flock donné et redémarre : la machine devient l’appareil de ce .flock. Les apps et leurs données restent. Lorsque l’installation a mis en place un utilisateur SSH, l’utilisateur SSH suit le .flock :

• Même propriétaire de projet, autre clé d’appareil — l’ancienne clé n’est plus acceptée, la nouvelle l’est.
• Autre propriétaire de projet — le nouveau propriétaire reçoit son utilisateur SSH, et l’utilisateur SSH du premier propriétaire disparaît comme agent remove le supprime : la règle sudo, la clé, et le compte avec son répertoire personnel lorsque l’installation l’a créé.
• Un .flock sans clé d’appareil — l’utilisateur SSH disparaît, et aucun ne le remplace.

Lorsque l’appareil change de propriétaire, le premier propriétaire peut être celui qui exécute la commande, via SSH, avec le compte même qui disparaît, et la suppression d’un compte met fin à ses sessions. La commande procède donc dans cet ordre : elle met en place le compte du nouveau propriétaire (utilisateur, clé, règle sudo), redémarre l’agent avec le nouveau .flock, et ne retire qu’ensuite la règle sudo, les sessions et le compte du premier propriétaire (ou seulement l’ancienne clé, pour un même propriétaire). L’appareil dispose d’un nouvel accès, et il est en ligne, avant que l’ancien accès ne disparaisse. Avant que les sessions ne prennent fin, une ligne sur stderr l’annonce, par exemple Removing the account anna, ...: a session of anna ends here.

• Lorsque l’agent ne redémarre pas avec le nouveau .flock, le premier propriétaire garde l’accès : quelqu’un doit pouvoir se connecter.
• Lorsque seul l’utilisateur SSH du nouveau propriétaire a échoué, l’accès du premier propriétaire disparaît malgré tout : l’appareil a changé de propriétaire et il est en ligne.
• Les accès qui restent à supprimer sont enregistrés dans /opt/ironflock/device-init/installed.json (users_to_remove). Chaque agent configure -c et chaque agent remove ultérieurs font une nouvelle tentative.
• Un compte que le nouveau .flock met de nouveau en place n’est jamais supprimé (propriétaire A, puis B, puis A).
• À partir de sa première modification, un terminal ou une session SSH perdus n’arrêtent plus la commande.

Via --host, la copie du .flock sur la machine est supprimée dès que la commande l’a lue. Lorsque le compte de connexion de --host est un compte qui disparaît, la session SSH prend fin avec le compte : votre exécution se termine alors avec le code de sortie 255, comme après une connexion perdue, et la commande sur la machine va jusqu’au bout. Le dossier de l’exécution ironflock.XXXXXXXXXX et son binaire restent alors sur la machine ; dans un dossier temporaire, il y reste jusqu’au nettoyage de celui-ci, et dans le répertoire personnel du compte, il disparaît avec le compte.

Sur IronFlockOS

Avec -c, la commande enrôle l’appareil comme IronFlockOS l’enrôle au premier démarrage de chaque nouveau slot racine, sur un appareil qui s’est déjà enrôlé comme sur un appareil qui ne s’est pas encore enrôlé. Le .flock donné devient la copie de l’agent, /opt/ironflock/device-agent/device-config.flock sur /data, et l’appareil est configuré à partir de celle-ci dans cet ordre : l’utilisateur SSH du propriétaire du projet, le WiFi, le nom d’hôte tiré du nom de l’appareil (sauf si /etc/ironflockos/enroll.conf indique hostname-from-flock=no), l’agent, redémarré avec le nouveau .flock, puis la suppression de l’accès du propriétaire précédent.

La prochaine mise à jour de l’OS enrôle son nouveau slot racine à partir de la même copie. Le fichier que vous avez donné reste où il est. Une étape qui échoue n’empêche pas l’agent de redémarrer avec le nouveau .flock, mais l’accès du premier propriétaire ne disparaît qu’une fois l’agent redémarré. La commande se termine alors avec le code de sortie 1 et nomme chaque étape qui a échoué ; exécutez à nouveau la même commande pour les répéter.

Les options de proxy sont refusées sur IronFlockOS. IronFlockOS conserve le proxy de Docker, de l’agent et de son horloge dans /etc/ironflockos/proxy.conf sur /data, et un proxy.conf sur sa partition IRONFLOCKOS le remplace au prochain démarrage.

Paramètres de proxy

• Chaque option de proxy donnée remplace son paramètre, et les autres restent. --https-proxy seul modifie le proxy HTTPS et conserve le proxy HTTP et les hôtes qui les contournent.
• Le mot de passe de --proxy-password-file va dans les URL données qui nomment un utilisateur. Sans URL donnée, il va dans les URL des paramètres de l’appareil qui en nomment un : un nouveau mot de passe se définit donc avec le fichier seul.
• --no-proxy, ainsi que le premier proxy d’un appareil qui n’en avait pas, ajoutent aussi localhost, 127.0.0.1, ::1 et le serveur de mise à jour du .flock de l’agent lorsqu’il n’est pas un hôte du cloud IronFlock (celui d’une appliance).
• --remove-proxy supprime les paramètres. Il n’accepte aucune autre option de proxy.
• Les variables de proxy de votre environnement ne changent rien ici : seules les options comptent.

La liste des hôtes qui contournent le proxy reste telle que la commande la trouve, sauf si --no-proxy en donne une autre. Lorsque cette liste nomme un hôte du cloud IronFlock, un avertissement le nomme, avec la commande agent configure --no-proxy qui donne la liste sans lui. Un appareil qui n’accède à internet que par le proxy ne peut pas mettre à jour son agent tant que le serveur de téléchargement du cloud, instance-registry.ironflock.com, figure sur cette liste.

Les paramètres sont conservés dans /etc/ironflock/proxy.env, que seul root lit, et nommés par les drop-ins ironflock-proxy.conf de docker.service et de ironflock-device-agent.service. Lorsque les paramètres changent, la commande les affiche avant et après, sans le mot de passe. Docker et l’agent redémarrent ensuite. Le redémarrage de Docker arrête un instant les apps de l’appareil : la commande le dit et pose la question ; --yes répond. Avec le mot de passe sur stdin, il n’y a pas de terminal pour poser la question : donnez --yes.

• Docker ne redémarre pas, et aucune question n’est posée, lorsque le daemon.json de Docker définit proxies (Docker les fait passer avant ces paramètres), et lorsque rien ne change.
• Une unité à laquelle il ne manque que son drop-in le reçoit, et seule cette unité redémarre.
• Un drop-in Docker propre à l’hôte reste tel quel. Un autre drop-in de l’agent, ou de Docker, qui définit une variable de proxy est nommé dans un avertissement ; les paramètres d’IronFlock l’emportent sur lui pour chaque variable qu’ils définissent. Un drop-in ou un daemon.json qui contient un mot de passe de proxy lisible par chaque utilisateur est aussi nommé dans un avertissement.
• Lorsque le redémarrage de Docker échoue, l’agent redémarre malgré tout, et inversement. L’erreur (code de sortie 1) nomme les unités qui tournent encore avec les anciens paramètres et la commande systemctl restart qui les applique ; une seconde exécution trouve les paramètres en place et ne redémarre rien.
• Lorsque les paramètres ne peuvent pas être écrits, rien ne redémarre, et l’erreur indique d’exécuter à nouveau la commande.

Les paramètres de proxy qu’une installation plus ancienne a écrits dans les lignes Environment= de drop-ins http-proxy.conf, où chaque utilisateur peut les lire avec systemctl show, mot de passe compris, passent dans /etc/ironflock/proxy.env à chaque exécution de agent configure, y compris avec -c seul. Aucune copie des anciens fichiers n’est conservée. En règle générale, ce déplacement conserve les valeurs : il ne redémarre donc rien et ne pose aucune question ; là où il modifie le proxy qu’utilise une unité, la commande dit pourquoi, affiche le proxy de cette unité avant et après, et pose la question. Une valeur que le fichier de paramètres ne peut pas contenir (un guillemet simple dans l’hôte ou dans la liste de contournement, un caractère de contrôle) n’est pas déplacée : une exécution sans options de proxy la laisse en place, émet un avertissement et nomme l’option qui redonne la valeur.

Exemples

# Faire de cette machine l'appareil d'un autre .flock
sudo ironflock agent configure -c new-device.flock
# Définir un proxy HTTPS avec authentification ; le mot de passe provient d'un fichier
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# Définir seulement un nouveau mot de passe de proxy, lu sur stdin, sans question
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# Supprimer les paramètres de proxy : Docker et l'agent se connectent directement
sudo ironflock agent configure --remove-proxy

Résultat

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

Sur IronFlockOS, -c rend compte de l’enrôlement :

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"]}

Cas de refus

Une ligne de commande erronée se termine avec le code de sortie 2 : rien à modifier ; --remove-proxy avec une autre option de proxy ; une URL de proxy avec mot de passe ; une URL de proxy qui nomme un utilisateur, sans --proxy-password-file ; --proxy-password-file avec des URL dont aucune ne nomme d’utilisateur ; une valeur qui n’est ni une URL de proxy ni une liste d’hôtes.

La commande refuse avec le code de sortie 3, et ne modifie rien, lorsque :

• aucun agent n’est installé (le message nomme agent install), sauf sur IronFlockOS, où -c enrôle un appareil qui ne s’est pas encore enrôlé ;
• l’agent fait passer la machine de l’ancienne disposition à la disposition actuelle ;
• des options de proxy sont données et l’agent tourne encore dans l’ancienne disposition /opt/reagent. Une fois que l’agent a fait passer la machine à la disposition actuelle (ironflock status indique la disposition), la même commande fonctionne ;
• des options de proxy sont données sur IronFlockOS, avec ou sans -c ;
• --no-proxy ou --proxy-password-file est donné seul sur un appareil sans proxy, ou le fichier de mot de passe seul lorsqu’aucune URL de proxy de l’appareil ne nomme d’utilisateur ;
• des options de proxy conservent une valeur de l’ancienne forme que /etc/ironflock/proxy.env ne peut pas contenir ; le message nomme l’option qui la redonne.

Sur IronFlockOS, -c est refusé avec le code de sortie 3 lorsque l’enrôlement ne conserverait pas le .flock :

• une réinitialisation d’usine est demandée et n’a pas encore commencé (/boot/efi/factory-reset.conf, qu’écrit os reset), ou elle a commencé (/boot/efi/factory-reset.keep) : le prochain démarrage effacerait ce que la commande met en place ;
• une réinitialisation d’usine est en cours ou a abandonné, et retient les fichiers venus avec elle (/run/ironflockos/factory-reset-hold ; ironflock status en dit plus) ;
• /data n’a pas pu être monté : la copie de l’agent atterrirait dans le slot racine. Un .flock sur la partition IRONFLOCKOS est alors la solution ;
• un .flock se trouve sur la partition IRONFLOCKOS ; l’appareil s’enrôle avec lui à son prochain démarrage, et le message le nomme ;
• la commande s’exécute sur la clé d’installation d’IronFlockOS, qui n’est pas un appareil ;
• le système n’a pas de /usr/lib/ironflock/image.json, ou a un agent dans l’ancienne disposition.

ironflock agent update

Laisse l’agent se mettre à jour vers la version de son canal, et suit ce qu’il fait. L’agent cherche une version plus récente à chaque démarrage : la commande le redémarre et indique l’issue. L’appareil est hors ligne dans IronFlock pendant un instant ; ses apps continuent de tourner.

ironflock agent update [flags]

S’exécute sous : Linux, avec un agent installé. Root : requis. Questions : oui, après avoir dit ce que fait le redémarrage ; --yes répond.

La commande n’a pas d’options propres et n’accepte pas de version. L’agent suit son canal (production, ou test sur la plateforme de test d’IronFlock), depuis son serveur de mise à jour : l’update_url de son .flock (le miroir d’une appliance), sinon le cloud IronFlock. --download-base n’y change rien.

Ce que fait l’agent, dans cet ordre :

1. Il lit la version de son canal. Une version qui a échoué deux fois sur cet appareil n’est plus téléchargée tant qu’une version plus récente n’est pas sortie.
2. Il télécharge une version plus récente dans son dossier et vérifie sa signature.
3. Il met la nouvelle version en place et redémarre sur celle-ci, 10 secondes après le téléchargement. Il retient la mise à jour lorsque sa dernière connexion à IronFlock date de 12 minutes à un jour : une mise à jour est activée à partir d’une version dont on sait qu’elle se connecte.
4. La nouvelle version est en période d’essai : elle doit se connecter à IronFlock dans les 10 minutes qui suivent son démarrage et rester active pendant 2 minutes. Si elle n’y parvient pas, ou si elle s’arrête trois fois avant, l’agent revient à la version précédente.
5. Après un retour arrière, la version précédente doit se connecter. La nouvelle version était alors en cause : elle est retentée une fois à la prochaine mise à jour et, après son second échec, elle est bloquée jusqu’à une version plus récente. Lorsque la version précédente ne parvient pas non plus à se connecter dans les 10 minutes, l’agent met en cause le réseau, et la nouvelle version est retentée à la prochaine mise à jour.

La commande suit cela dans update-state.json, dans le dossier de l’agent, et dans le journal de l’agent ; elle n’y lit rien de ce qui précède le redémarrage. Sa progression va sur stderr sous forme de lignes de texte, y compris avec --json. Un téléchargement indique une fois par minute combien il a déjà reçu.

Avec le code de sortie 1, le résultat est tout de même écrit, et stderr reçoit la ligne Error:. Avec --json, aucun objet d’erreur ne suit : stdout contient le résultat.

Exemples

# Mettre à jour l'agent ; la commande pose une question avant le redémarrage
sudo ironflock agent update
# Mettre à jour sans question et lire l'issue en JSON
sudo ironflock agent update --yes --json

Résultat

$ 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 agent à jour, et un agent dont la nouvelle version a fait l’objet d’un retour arrière :

{"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"}

Cas de refus

La commande refuse avec le code de sortie 3 lorsqu’aucun agent n’est installé (le message nomme agent install), pendant que l’agent fait passer la machine de l’ancienne disposition à la disposition actuelle, lorsque l’agent tourne dans l’ancienne disposition (ses mises à jour n’y conservent aucun état que la commande puisse suivre), et avec un agent antérieur à 1.3.0, la première version qui se met à jour elle-même sous son unité.

Elle échoue avec le code de sortie 1, et une erreur qui indique où regarder, lorsque le redémarrage échoue, et lorsque la mise à jour n’avance pas dans les délais de l’agent : la vérification de l’agent dans les 3 minutes qui suivent le redémarrage, le téléchargement dans les 30 minutes, l’activation dans les 3 minutes, chaque démarrage de la nouvelle version en période d’essai dans les 12 minutes, le verdict de l’agent après un retour arrière dans les 12 minutes, et le tout dans les 84 minutes. L’agent continue de lui-même ; ironflock status indique où il en est.

Ctrl-C arrête le suivi, pas la mise à jour, et met fin à la commande avec le code de sortie 130.

ironflock agent remove

Supprime l’agent de l’appareil et annule ce que son installation a enregistré. Docker lui-même et les paquets restent installés.

ironflock agent remove [flags]

S’exécute sous : Linux, avec un agent installé ; pas sur IronFlockOS. Root : requis. Questions : oui, après avoir listé ce qu’elle supprime. La question présélectionne « No » : Entrée seule ne supprime rien.

La commande n’a pas d’options propres. Elle supprime :

• L’agent — l’agent, sa base de données et /opt/ironflock/device-agent. Les apps de l’appareil et leurs données disparaissent avec lui lorsque Docker les conserve dans le dossier de l’agent.
• L’utilisateur SSH — le compte, uniquement lorsque l’installation l’a créé. D’un compte qui existait avant, seule la clé de l’appareil est retirée de son authorized_keys, qui reste celui de l’utilisateur. L’accès d’un ancien propriétaire de projet dont la suppression par agent configure -c avait échoué disparaît aussi ; il est listé avec « (a removal that had failed) ».
• Les réglages d’hôte — le profil WiFi, la bannière de connexion et les cibles de veille masquées.
• Les fichiers que l’installation a écrits ou remplacés — les originaux reviennent, avec leur mode, leur propriétaire et leur groupe.
• Les paramètres de proxy — /etc/ironflock/proxy.env avec les drop-ins qui le nomment, et les paramètres de proxy qu’une installation plus ancienne a laissés dans des drop-ins http-proxy.conf. Rien ne les remplace : ensuite, Docker n’a plus de proxy venu d’IronFlock, et la commande n’a écrit le mot de passe du proxy nulle part. Lorsque Docker avait un proxy venu d’IronFlock, la liste affichée avant la question le dit.
• Les paramètres que l’agent a écrits lui-même sur l’hôte — la slice ironflock.slice avec le drop-in 10-ironflock-resources.conf de son unité, le watchdog de systemd (/etc/systemd/system.conf.d/10-ironflock-watchdog.conf), les paramètres de plantage du noyau (/etc/sysctl.d/60-ironflock-crash-recovery.conf, que le noyau conserve jusqu’au prochain démarrage) et la limite du journal de systemd (/etc/systemd/journald.conf.d/10-ironflock.conf).
• Les connexions de l’agent aux registres — une fois l’agent arrêté, la commande exécute docker logout pour le registre que nomme le .flock (docker_registry_url) et, sur un appareil d’une appliance, pour registry.<appliance_domain>. Aucune autre connexion de /root/.docker/config.json n’est touchée. Un Docker absent ou en échec n’arrête pas la suppression ; une ligne indique quelle connexion n’a pas été supprimée.

Un drop-in Docker propre à l’hôte reste tel quel. Un Docker qui ne redémarre pas pour la suppression (ses données n’étaient pas dans le dossier de l’agent) utilise le proxy avec lequel il a démarré jusqu’à son prochain redémarrage.

La commande liste sur stderr ce qu’elle supprime, puis pose la question. Avec --json, la liste est le champ removed du résultat. Une fois que la commande a commencé la suppression, un terminal ou une session SSH perdus ne l’arrêtent plus : l’utilisateur SSH qui disparaît emporte ses sessions, peut-être celle qui exécute la commande, et la suppression va jusqu’au bout.

Exemples

# Supprimer l'agent ; la commande liste ce qui disparaît et pose la question
sudo ironflock agent remove
# Supprimer l'agent sans question
sudo ironflock agent remove --yes

Résultat

$ 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"]}

Cas de refus

La commande refuse avec le code de sortie 3 lorsqu’aucun agent n’est installé, et pendant que l’agent fait passer la machine de l’ancienne disposition à la disposition actuelle. Sur IronFlockOS, elle refuse avant toute autre chose, root ou non : l’image apporte l’agent avec son système, et chaque mise à jour de l’OS ainsi que le prochain enrôlement le remettraient en place. Le message nomme ironflock os reset, qui ramène l’appareil à un IronFlockOS fraîchement écrit, sans son identité chez IronFlock. Sur la clé d’installation d’IronFlockOS, il indique que la clé n’est pas un appareil.

La réponse non, ou une question sans terminal et sans --yes, met fin à la commande avec le code de sortie 4.

ironflock agent restart

Redémarre le service de l’agent et vérifie que l’agent tourne de nouveau : son unité doit tourner pendant cinq secondes avec un seul processus. L’appareil est hors ligne dans IronFlock pendant ces secondes ; les apps continuent de tourner.

ironflock agent restart [flags]

S’exécute sous : Linux, avec un agent installé. Root : requis. Questions : aucune.

La commande n’a pas d’options propres. Le service est ironflock-device-agent.service. Lorsque vous l’exécutez dans un terminal qui passe par l’agent (le terminal de l’appareil dans IronFlock Studio, ou SSH via IronFlock), le redémarrage met fin à cette session ; l’appareil revient en moins d’une minute.

# Redémarrer l'agent
sudo ironflock agent restart
# Le redémarrer et lire le nouveau processus en 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 est l’état de l’unité après coup, nommé comme dans ironflock status. main_pid est le processus de l’agent, un nouveau après chaque redémarrage.

Refuse avec le code de sortie 3 lorsqu’aucun agent n’est installé (le message nomme agent install -c <file>), pendant que l’agent fait passer la machine de l’ancienne disposition à la disposition actuelle, et lorsque systemd ne connaît pas l’unité de l’agent (le message nomme agent remove).

Échoue avec le code de sortie 1 lorsque l’agent ne démarre pas : systemd ne peut pas démarrer l’unité, ou son processus se termine au cours des cinq secondes. L’erreur nomme l’unité et l’endroit où se trouvent ses dernières lignes de journal : le journal de l’agent (agent logs) et le journal de systemd (journalctl -u <unit>).

ironflock agent stop

Arrête le service de l’agent. L’appareil passe hors ligne dans IronFlock, et l’accès à distance via IronFlock disparaît avec l’agent : une session arrivée par ce chemin (le terminal de l’appareil dans IronFlock Studio, SSH via IronFlock) prend fin, et IronFlock ne peut plus joindre l’appareil tant que l’agent ne tourne pas de nouveau. Les apps continuent de tourner, car c’est Docker qui les exécute, pas l’agent.

ironflock agent stop [flags]

S’exécute sous : Linux, avec un agent installé. Root : requis. Questions : oui, après avoir dit ce à quoi l’arrêt de l’agent met fin ; --yes répond.

La commande n’a pas d’options propres. agent start démarre de nouveau l’agent, tout comme le prochain démarrage du système. Un agent arrêté ne peut pas être redémarré via IronFlock. Un agent qui ne tourne pas n’a rien à arrêter ; la commande ne pose alors aucune question, et le résultat n’a pas d’action.

# Arrêter l'agent ; la commande dit ce à quoi cela met fin et pose la question
sudo ironflock agent stop
# L'arrêter sans question
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"}

Refuse avec le code de sortie 3 comme le fait agent restart. La réponse non, ou une question sans terminal et sans --yes, y met fin avec le code de sortie 4.

ironflock agent start

Démarre le service de l’agent lorsqu’il ne tourne pas, et vérifie que l’agent démarre, comme le fait agent restart : son unité doit tourner pendant cinq secondes avec un seul processus. Un agent qui tourne déjà est laissé tel quel, et le résultat n’a alors pas d’action.

ironflock agent start [flags]

S’exécute sous : Linux, avec un agent installé. Root : requis. Questions : aucune. La commande n’a pas d’options propres.

# Démarrer l'agent
sudo ironflock agent start
# Le démarrer et lire son processus en 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.

Avec --json, pour un agent qui tourne déjà :

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

Refuse et échoue comme le fait agent restart : code de sortie 3 lorsqu’aucun agent n’est installé, pendant que l’agent fait passer la machine de l’ancienne disposition à la disposition actuelle, et lorsque systemd ne connaît pas l’unité de l’agent ; code de sortie 1 lorsque l’agent ne démarre pas.

ironflock agent logs

Affiche le journal de l’agent, /var/log/ironflock/device-agent.log, ainsi que les fichiers vers lesquels l’agent l’a archivé par rotation. Ne modifie rien.

ironflock agent logs [flags]

S’exécute sous : Linux, avec un agent installé ; la commande lit les fichiers et n’a pas besoin de systemd. Root : requis, car l’agent écrit son journal pour root seul (mode 0600). Questions : aucune.

À 100 Mo, l’agent renomme son journal en device-agent-<time>.log dans le même dossier et en commence un nouveau ; il en conserve deux. La commande lit le journal et ces fichiers.

L’agent écrit un objet JSON par ligne : l’heure de l’entrée (à la seconde près), son niveau, son message et d’autres champs. La forme texte affiche une entrée comme IronFlock Studio affiche le journal de l’agent : l’heure en UTC, le niveau, le message et son erreur. Une ligne qui n’est pas une entrée, comme la trace de pile d’un plantage, est affichée telle quelle. Les caractères de contrôle sont échappés (\n, \x1b) : une entrée tient donc sur une ligne du terminal et ne peut pas le piloter. Avec --json, chaque ligne est un objet JSON sur stdout : l’entrée telle que l’agent l’a écrite, avec tous ses champs, ou {"message":...} pour une ligne qui n’est pas une entrée.

• --since commence par la première entrée de ce moment ou d’après. Les lignes restent dans l’ordre où l’agent les a écrites. Une ligne sans heure appartient à l’entrée qui la précède.
• Avec --follow, une ligne est affichée une fois complète. Lorsque l’agent commence un nouveau fichier, le reste de l’ancien vient d’abord, puis le nouveau depuis son début. Un journal qui n’existe pas encore est attendu. Ctrl-C met fin à la commande avec le code de sortie 0 ; via --host, Ctrl-C met fin à l’exécution avec le code de sortie 130.
• Lorsque l’agent n’a encore écrit aucun journal, stderr le dit, stdout reste vide, et le code de sortie est 0.

Exemples

# Les 100 dernières lignes
sudo ironflock agent logs
# Tout ce qui date de la dernière heure
sudo ironflock agent logs --since 1h
# Les 20 dernières lignes, puis chaque nouvelle ligne jusqu'à Ctrl-C
sudo ironflock agent logs --follow --lines 20
# Les dix dernières minutes en JSON, un objet par ligne
sudo ironflock agent logs --since 10m --json

Résultat

$ 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"}

Cas de refus

Un --since qui n’est ni une durée ni un horodatage, une durée négative, et un --lines qui n’est ni un nombre ni all sont des lignes de commande erronées (code de sortie 2). La commande refuse avec le code de sortie 3 lorsqu’elle ne s’exécute pas en tant que root, et lorsqu’aucun agent n’est installé (le message nomme agent install -c <file>).