Commandes de l’appliance

Les commandes ironflock appliance installent l’IronFlock Appliance sur un serveur Linux que vous exploitez vous-même, puis s’en occupent. Elles vous servent à installer l’appliance, à modifier ses paramètres, à la mettre à jour, à la démarrer, l’arrêter et la redémarrer, à lire ses journaux, à réinitialiser le mot de passe admin, à sauvegarder, restaurer et renouveler ses secrets, et à la supprimer.

L’appliance est le système IronFlock complet sur une machine sur site. Ce qu’elle est, ses modes HTTPS, son réseau et son exploitation sont décrits sous IronFlock Appliance. Les exigences envers la machine (CPU, mémoire, stockage, synchronisation horaire) figurent sur sa page Installation.

Note : Ces commandes sont nouvelles dans la version 2.1.0 d’ironflock. Elles ont passé un cycle de test, de appliance install à appliance remove --purge, sur une machine virtuelle Ubuntu 24.04 vierge (amd64). Ce qui n’est pas encore éprouvé : une mise à jour qui échoue, avec son retour à la version précédente.

L’appliance

Les commandes de l’appliance s’exécutent sous Linux. appliance install nécessite un système basé sur Debian ou Ubuntu avec systemd. Sous macOS, les commandes se terminent avec le code de sortie 3 avant d’examiner quoi que ce soit ; exécutez-les sur la machine de l’appliance, ou depuis le Mac avec --host.

Exécutez-les en tant que root, avec sudo. Sans root, une commande qui modifie le système se termine avec le code de sortie 3 et n’appelle pas sudo elle-même (Privilèges root).

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

ironflock status affiche l’appliance installée : sa version et son canal, l’adresse de son interface, la présence de sa licence, son service, la santé de ses services et une mise à jour en attente (ironflock status).

À quoi ressemble une appliance installée

Outre ironflock.service, l’installation met en place un watchdog, qui vérifie le routeur et le backend toutes les cinq minutes et redémarre ironflock.service lorsqu’ils ne vont pas bien, au plus une fois toutes les cinq minutes, ainsi qu’un timer qui retente toutes les heures une mise à jour de l’interface qui a échoué.

Laissez /usr/local/bin/ironflock en place : les unités de l’appliance l’exécutent à chaque démarrage. appliance install refuse de s’exécuter depuis un autre emplacement et indique comment l’installer à cet endroit. ironflock status, exécuté en tant que root, avertit lorsque ce binaire manque ou est plus ancien que celui qui a installé ou mis à jour l’appliance en dernier. sudo ironflock self-update le remplace par la version la plus récente (ironflock self-update).

L’appliance exécute aussi l’agent de l’appareil propre à l’hôte, qu’appliance install installe sauf si vous donnez --no-agent. Cet agent s’entretient avec les commandes agent.

Une modification à la fois

Une seule installation, mise à jour ou autre modification de l’appliance s’exécute à la fois. Une seconde attend la première et l’indique :

Another IronFlock install, update or other change of the appliance is running on this host (process <pid>); waiting up to <time> for it to finish

install, update, configure, rotate, revoke-direct-access, reset-admin-password et restore attendent jusqu’à une heure. start, stop, restart et remove attendent jusqu’à 30 secondes. Lorsque l’autre exécution se poursuit encore à ce moment-là, la commande ne modifie rien et se termine avec le code de sortie 3.

ironflock appliance install

Installe l’IronFlock Appliance dans /opt/ironflock et la démarre. Attend que chaque service soit en bonne santé et que le cloud IronFlock joigne l’appliance, puis affiche l’identifiant admin de l’interface web, une seule fois, dans un terminal.

ironflock appliance install --license-file <file> [flags]

S’exécute sous : Linux basé sur Debian ou Ubuntu, avec systemd. Root : requis.

L’installation met en place :

• la version du canal, ou celle que nomme --version, vérifiée avec la clé de publication de l’appliance ;
• la configuration et les secrets de l’appliance ;
• l’agent de l’appareil propre à l’hôte, et Docker lorsqu’il manque ;
• les réglages de l’hôte ;
• la connexion de Docker au registre avec la clé de licence ;
• les images de la version ;
• ironflock.service.

Lorsque Docker manque, l’installation exécute en tant que root le script d’installation de Docker depuis get.docker.com. Ce téléchargement n’est protégé que par TLS.

Les modes HTTPS et ce que chacun chiffre sont décrits dans HTTPS et certificats et Sécurité. Le mot de passe du proxy suit les règles de Secrets : une URL de proxy qui contient un mot de passe est une ligne de commande erronée.

La clé de licence

La clé de licence est l’Instance Key que vous créez sur ironflock.com sous Profil → Instances (Installation). Elle provient de --license-file ou de --license. Une appliance déjà installée garde sa clé sans l’une ni l’autre. Une clé de license.env qui n’est pas une clé de licence valide (une clé de licence est un UUID) est ignorée, avec un avertissement, par chaque commande de l’appliance ; l’exécution a alors besoin d’une clé, ou de --skip-login.

Variables d’environnement

Certaines options prennent leur valeur par défaut dans une variable d’environnement :

sudo écarte la plupart des variables de votre shell. Transmettez-les avec sudo env NAME=value ironflock appliance install ....

L’enregistrement des choix de l’installation

<install-dir>/install.json, lisible par root seul, conserve les choix que ni .env ni les unités ne conservent : le registre et son utilisateur, l’hôte de l’appliance (IRONFLOCK_APPLIANCE_HOST), --no-agent, la base de téléchargement de --bucket-url, et la version de l’ironflock qui a installé ou mis à jour l’appliance en dernier. Il ne contient ni mot de passe, ni jeton, ni clé.

Un appliance install ultérieur, un appliance update et appliance configure conservent ces choix, sauf si une option (ou sa variable) en décide autrement. Une option donnée l’emporte et est enregistrée. Pour revenir à une valeur par défaut, donnez --registry "", --no-agent=false ou une IRONFLOCK_APPLIANCE_HOST vide.

Un enregistrement illisible, ou d’un format plus récent, arrête install, update et configure avant toute modification, avec le code de sortie 3. Le message indique quoi faire : mettre l’enregistrement de côté et installer à nouveau avec les options, ou utiliser l’ironflock plus récent.

Exécuter à nouveau la commande

Exécutée sur une appliance installée, la commande l’amène à la version et aux options données, et conserve ses secrets et ses paramètres. Servez-vous-en pour changer de version délibérément : ironflock appliance install --version <version> récupère, redémarre et vérifie à nouveau cette version, même lorsqu’elle tourne déjà.

Une exécution qui s’est arrêtée reprend là où elle s’est arrêtée lorsque la même commande s’exécute à nouveau.

Une fois ses contrôles de santé passés, l’installation supprime la copie d’une version précédente qu’une mise à jour a conservée (/opt/ironflock/.update-previous) : la version qu’elle a installée est celle qui doit tourner.

À partir de sa première modification, un terminal ou une session SSH perdus (SIGHUP), ou une sortie que plus personne ne lit (un pipe fermé), n’arrêtent pas l’installation. Ctrl-C et SIGTERM l’arrêtent. L’installation continue d’écrire dans le terminal après une session SSH perdue, afin que le mot de passe admin ne soit pas perdu. Avec le réglage use_pty de sudo, un terminal qui reste ouvert mais n’est plus lu peut donc bloquer l’installation pendant qu’elle détient le verrou d’installation.

Exemples

# Installer l'appliance ; la clé de licence provient d'un fichier
sudo ironflock appliance install --license-file license.txt
# Installer avec HTTPS de la propre CA de l'appliance ; la clé provient de l'entrée standard
sudo ironflock appliance install --license-file - --tls < license.txt
# Installer derrière un proxy ; les hôtes sous .corp.example.com le contournent
sudo ironflock appliance install --https-proxy http://proxy.example.com:3128 --no-proxy .corp.example.com
# Demander l'adresse et le domaine de l'appliance, et installer avec HTTPS
sudo ironflock appliance install --license-file license.txt --interactive --tls

Cas de refus et d’échec

• Une base de téléchargement de --bucket-url que les unités ne peuvent pas nommer telle quelle (avec des identifiants, %, des espaces, $, \, un guillemet, un caractère de contrôle, des octets qui ne sont pas de l’UTF-8) est refusée avant toute écriture, avec le code de sortie 2.
• La commande refuse avec le code de sortie 3 lorsqu’elle ne s’exécute pas en tant que root, lorsque l’enregistrement des choix de l’installation ne peut pas être lu, et lorsqu’une autre exécution détient le verrou d’installation au-delà de l’attente d’une heure. Elle refuse aussi lorsque l’ironflock qui s’exécute n’est pas /usr/local/bin/ironflock, et indique comment l’installer à cet endroit.
• Une étape qui échoue met fin à la commande avec le code de sortie 1. Exécutez à nouveau la même commande pour continuer.

ironflock appliance configure

Modifie les paramètres d’une appliance installée : sa licence, le mode TLS (y compris avec votre propre certificat), le proxy, d’autres noms d’hôte pour l’interface, le tunnel et la politique de second facteur.

ironflock appliance configure [flags]

S’exécute sous : Linux, avec une appliance installée. Root : requis.

Les paramètres restent dans le .env et les fichiers de l’appliance : une mise à jour les conserve donc. Un paramètre non donné garde ce que l’appliance a. Seule une exécution qui a modifié quelque chose redémarre l’appliance : la même commande exécutée deux fois ne modifie donc rien la seconde fois.

• Une nouvelle licence (--license, --license-file, ou --license-file - pour l’entrée standard) doit ouvrir l’accès au registre avant d’être écrite. Sa connexion au registre va vers --registry en tant que --registry-user, sinon vers ceux que l’installation a choisis (l’enregistrement), sinon vers le registre depuis lequel se synchronise le miroir de l’appliance. Une connexion avec --registry ou --registry-user les conserve dans l’enregistrement pour les mises à jour.
• --tls-cert et --tls-key installent votre certificat et activent TLS, et les appareils passent au domaine de l’appliance.
• --http-proxy "" ou --https-proxy "", donné seul, efface le proxy.
• --no-agent de l’installation reste tel quel.
• Le Caddyfile dont TLS a besoin provient de --bucket-url, sinon de l’emplacement où l’installation a pris les versions.

Exemples

# Donner à l'appliance une nouvelle clé de licence depuis un fichier
sudo ironflock appliance configure --license-file license.txt
# Servir l'interface avec le certificat de votre organisation
sudo ironflock appliance configure --tls-cert wildcard.crt --tls-key wildcard.key
# Définir un proxy, puis l'effacer
sudo ironflock appliance configure --https-proxy http://proxy.example.com:3128 --no-proxy .corp.example.com
sudo ironflock appliance configure --https-proxy ""
# Exiger un second facteur de chaque utilisateur
sudo ironflock appliance configure --2fa required

Avant de définir --2fa required, assurez-vous que chaque compte a un second facteur : un utilisateur qui n’en a pas ne peut plus se connecter (Comptes et accès).

Cas de refus

La commande refuse avec le code de sortie 3, et ne modifie rien, lorsqu’elle ne s’exécute pas en tant que root, lorsque l’enregistrement des choix de l’installation ne peut pas être lu, lorsqu’une autre exécution détient le verrou d’installation au-delà de l’attente d’une heure, et tant qu’une mise à jour est restée inachevée (Mise à jour inachevée).

ironflock appliance update

Met l’appliance de cette machine à jour vers la version la plus récente de son canal, ou vers la version que nomme --version. La version est vérifiée avec la clé de publication de l’appliance, ses images sont récupérées, et l’appliance redémarre avec elle. La commande attend que chaque service soit en bonne santé et que le cloud IronFlock joigne l’appliance. L’appliance conserve ses secrets et ses paramètres. Les images des versions antérieures sont supprimées une fois la nouvelle en bonne santé.

ironflock appliance update [flags]

S’exécute sous : Linux, avec une appliance installée. Root : requis. Questions : aucune, sauf avec --discard-previous.

Les versions proviennent de --bucket-url, sinon de IRONFLOCK_BUCKET_URL, sinon de l’emplacement où l’installation les a prises (l’enregistrement de ses choix, /opt/ironflock/install.json, ou ses unités le nomment), sinon d’IronFlock. Le registre, son utilisateur, l’hôte de l’appliance et --no-agent restent tels que l’installation les a choisis.

Un nouveau canal reste en place lorsque la mise à jour réussit ; le canal précédent revient avec un retour arrière. Le bouton Appliquer la mise à jour de l’interface exécute la même mise à jour.

Une fois ses vérifications passées, une installation ou une mise à jour fait aussi passer l’appareil propre à l’appliance du secret que partageaient auparavant toutes les appliances à la valeur de APPLIANCE_DEVICE_SECRET. Son agent redémarre alors 35 secondes après l’exécution. Un passage qui ne peut pas se faire est un avertissement qui dit pourquoi ; l’installation ou la mise à jour suivante réessaie.

Déjà à jour

Une appliance qui exécute déjà la version la plus récente de son canal (ou la version que nomme --version), sur le même canal et la même base de téléchargement, est laissée telle quelle. La commande le dit et se termine avec le code de sortie 0 ; avec --json, le result est nothing-to-do. Pour récupérer, redémarrer et vérifier à nouveau cette version délibérément, exécutez ironflock appliance install --version <version>.

Cela ne vaut que pour une appliance que la dernière mise à jour a laissée propre. Avec une copie conservée d’une version précédente (une mise à jour restée inachevée), ou un fichier d’état qui indique failed ou running, la mise à jour exécute tout à nouveau.

Retour arrière

Avant que la mise à jour ne modifie quoi que ce soit, elle conserve les fichiers de la version qui tourne dans /opt/ironflock/.update-previous. Lorsque la mise à jour échoue après avoir modifié l’appliance, ces fichiers sont remis en place et la version précédente redémarre. Cela ne nécessite aucun réseau, car ses images se trouvent sur la machine. C’est tenté jusqu’à trois fois. Ensuite, la commande abandonne et laisse en place les fichiers de la version précédente, afin que le prochain démarrage de l’appliance soit cette version.

Une mise à jour qui échoue avant d’avoir modifié quoi que ce soit ne modifie rien de plus et le dit : par exemple, une version absente ou non signée, ou une base de téléchargement qui ne répond pas.

Une version peut nécessiter un ironflock plus récent que celui qui s’exécute. Rien n’est alors modifié, et la commande indique quel ironflock installer d’abord. appliance update ne met pas ironflock à jour de lui-même ; ironflock self-update installe la version la plus récente.

Fichier d’état et nouvelle tentative

La mise à jour écrit sa progression dans triggers/apply-update.status, comme le fait la mise à jour de l’interface : l’interface l’affiche donc. Sa sortie va aussi dans triggers/apply-update.log. Le timer qui retente une mise à jour de l’interface qui a échoué ne retente pas une mise à jour de cette commande qui a échoué, ou qui a été arrêtée avant d’avoir modifié quoi que ce soit.

Interruptions

• Ctrl-C ou SIGTERM avant que la mise à jour n’ait modifié quoi que ce soit l’arrête. Après cela, le premier ramène la version précédente (code de sortie 130), et un second arrête immédiatement.
• Un terminal ou une session SSH perdus (SIGHUP), ou une sortie que plus personne ne lit, n’arrêtent pas la mise à jour. La mise à jour, et un retour arrière, vont jusqu’à leur terme. Le fichier d’état et ironflock status indiquent comment elle s’est terminée.
• Via --host sans terminal, les deux premiers Ctrl-C parviennent à la machine. Après le premier, la commande attend jusqu’à 30 minutes que la mise à jour s’y termine ; après le second, 15 secondes ; un troisième met fin à la commande ici immédiatement. Une session perdue ici, ou SIGTERM, n’est pas un Ctrl-C : la commande se termine ici immédiatement. Chaque fois qu’elle se termine d’abord ici, la mise à jour se poursuit sur la machine, et ironflock --host <machine> status indique comment elle s’est terminée.

Mise à jour inachevée

Une mise à jour est restée inachevée lorsqu’elle a commencé à modifier l’appliance puis ne s’est pas terminée : elle a été arrêtée, la machine s’est éteinte, ou son retour arrière n’a pas remis la version précédente en marche. Le répertoire d’installation peut alors contenir des fichiers de deux versions. La copie conservée nomme la version dont on sait qu’elle tourne, et ironflock status la nomme aussi.

• La mise à jour suivante remet d’abord cette copie en place, puis met à jour. Une copie qui ne peut pas être lue ou remise en place arrête la mise à jour avec le code de sortie 3, et l’erreur nomme ironflock appliance install --version <version>.
• Le timer horaire de nouvelle tentative remet la copie en place de lui-même, redémarre cette version et la vérifie, même lorsqu’aucune version plus récente n’existe.
• configure, rotate, revoke-direct-access, restore et reset-admin-password refusent avant toute modification, avec le code de sortie 3. Ils nomment les trois issues : ironflock appliance update ; ironflock appliance install --version <version> ; et, sans le réseau, ironflock appliance update --discard-previous.
• backup ne fait que lire, et émet un avertissement. start, stop et restart ne touchent pas à la copie. remove supprime la copie avec le reste des fichiers de l’appliance.
• appliance install s’exécute comme toujours et, une fois ses contrôles de santé passés, supprime la copie.

Pour travailler à la main sur les fichiers d’une mise à jour restée inachevée, définissez d’abord IRONFLOCK_UPDATE_RETRY=off dans .env. Sinon, le timer de nouvelle tentative remet la version précédente en place dans l’heure environ. Ce réglage désactive le timer de nouvelle tentative dans son ensemble, retour arrière compris.

--discard-previous

ironflock appliance update --discard-previous [--yes]

Ne met rien à jour. Supprime la copie de la version précédente qu’une mise à jour a conservée (/opt/ironflock/.update-previous), dans n’importe quel état et même lorsqu’elle ne peut pas être lue, et ne modifie rien d’autre. Ne nécessite aucun réseau.

C’est l’issue sans réseau lorsqu’une mise à jour est restée inachevée et que sa version précédente ne redémarre pas. Les fichiers du répertoire d’installation restent tels qu’ils sont maintenant, cette version ne peut plus être remise en place, et les commandes qui refusaient s’exécutent à nouveau.

L’option indique ce qu’elle supprime et pose d’abord la question, avec « No » présélectionné ; --yes répond oui. Sans terminal, ou avec --json, elle nécessite --yes, sinon elle se termine avec le code de sortie 4. Sans copie, elle le dit et se termine avec le code de sortie 0. Elle ne se combine pas avec --version, --channel ou --bucket-url (code de sortie 2). Avec --json, le résultat comporte action (discarded, cleaned ou none), path, version, state et removed.

Exemples

# Mettre à jour vers la version la plus récente du canal
sudo ironflock appliance update
# Installer la version 1.6.41, y compris pour y revenir
sudo ironflock appliance update --version 1.6.41
# Passer au canal test et lire le résultat en JSON
sudo ironflock appliance update --channel test --json
# Supprimer la copie de la version précédente, sans le réseau
sudo ironflock appliance update --discard-previous

Résultat

{"from":"1.6.40","target":"1.6.41","version":"1.6.41","result":"updated"}

Une mise à jour qui a échoué est une erreur qui indique si l’appliance est revenue à la version précédente. Avec --json, son kind est l’un des suivants, y compris en cas d’interruption :

ironflock appliance start

Démarre l’appliance lorsqu’elle ne tourne pas : ironflock.service démarre ses conteneurs (docker compose up), et son watchdog ainsi que ses autres paths et timers redémarrent. Les services mettent une minute ou deux à démarrer ; ironflock status affiche leur santé.

ironflock appliance start [flags]

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

Lorsqu’une restauration a laissé des rôles de base de données sur leurs anciens mots de passe, parce que l’appliance ne tournait pas à ce moment-là, ils prennent les mots de passe du .env restauré dès que leurs bases de données tournent (jusqu’à une minute). Un rôle qui ne répond pas reste en attente du démarrage suivant, avec un avertissement, et le démarrage se poursuit.

sudo ironflock appliance start
sudo ironflock appliance start --json

Pendant qu’une autre exécution modifie l’appliance, la commande attend jusqu’à 30 secondes et l’indique ; lorsque cette exécution se poursuit, elle ne modifie rien et se termine avec le code de sortie 3.

ironflock appliance stop

Arrête l’appliance : son watchdog, ses autres paths et timers et ce qu’ils ont démarré, puis ironflock.service, qui arrête et supprime ses conteneurs (docker compose down). Ses données restent.

ironflock appliance stop [flags]

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

L’interface passe hors ligne, de même que chaque appareil qui se connecte à l’appliance, y compris l’agent de cette machine. ironflock appliance start redémarre l’appliance, de même que le prochain démarrage du système. La commande n’a pas d’options propres.

# Arrêter l'appliance ; la commande indique ce à quoi l'arrêt met fin et pose la question
sudo ironflock appliance stop
# L'arrêter sans question
sudo ironflock appliance stop --yes

La réponse non, ou une question sans terminal et sans --yes, met fin à la commande avec le code de sortie 4. Pendant qu’une autre exécution modifie l’appliance, la commande attend comme le fait start.

ironflock appliance restart

Redémarre l’appliance : ironflock.service arrête ses conteneurs et les démarre à nouveau (docker compose down, puis up), comme le fait son watchdog. Les paths et timers qu’a arrêtés appliance stop redémarrent.

ironflock appliance restart [flags]

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

L’interface et les appareils qui se connectent à l’appliance sont hors ligne pendant une minute ou deux ; ses données restent. ironflock status affiche la santé des services une fois qu’ils ont démarré. Les rôles de base de données qu’une restauration a laissés sur leurs anciens mots de passe prennent ceux de .env, comme avec start.

sudo ironflock appliance restart
sudo ironflock appliance restart --json

Pendant qu’une autre exécution modifie l’appliance, la commande attend comme le fait start.

ironflock appliance logs

Affiche ce qu’ont écrit les services de l’appliance, comme l’affiche docker compose logs : par défaut, les 100 dernières lignes de chaque service. Ne modifie rien.

ironflock appliance logs [<service>...] [flags]

S’exécute sous : Linux, avec une appliance installée. Root : requis. Questions : aucune.

Nommez des services pour ne voir que les leurs, par exemple router, backend, kratos ou caddy.

Avec --json, chaque ligne est un objet JSON, avec la ligne comme message.

# Les 100 dernières lignes de chaque service
sudo ironflock appliance logs
# Tout ce qu'a écrit le backend au cours de la dernière heure
sudo ironflock appliance logs backend --since 1h
# Les 20 dernières lignes du routeur et de Kratos, puis chaque nouvelle ligne jusqu'à Ctrl-C
sudo ironflock appliance logs router kratos --follow --lines 20

ironflock appliance reset-admin-password

Donne un nouveau mot de passe à l’utilisateur admin de l’interface, pour un opérateur qui l’a perdu. Le mot de passe est d’abord défini dans la base de données, ce qui met fin à chaque session active de l’admin, puis dans .env sous APPLIANCE_ADMIN_PASSWORD. L’appliance doit tourner.

ironflock appliance reset-admin-password [flags]

S’exécute sous : Linux, avec une appliance en cours d’exécution. Root : requis.

Le nouveau mot de passe est affiché une seule fois, et uniquement dans un terminal. Sans terminal, et avec --json, la commande indique à la place où il est enregistré. Elle refuse avec le code de sortie 3 tant qu’une mise à jour est restée inachevée (Mise à jour inachevée).

sudo ironflock appliance reset-admin-password

ironflock appliance backup

Écrit dans une archive tar.gz tout ce que l’appliance ne peut pas recréer : .env avec chaque secret, license.env, la CA locale du certificat TLS, la paire de clés des jetons du registre, le registre des secrets et rotation.log.

ironflock appliance backup [-o <file>] [flags]

S’exécute sous : Linux. Root : requis.

Sans -o, l’archive va sur la sortie standard, qui ne doit pas être un terminal. Un fichier vers lequel elle est redirigée est rendu lisible par son seul propriétaire.

Avertissement : L’archive contient chaque secret de l’appliance. Un FLEETDB_SECRET_KEYS ou un FILE_CRED_KEY perdu ne peut être récupéré d’aucune autre manière. Chiffrez l’archive et conservez-la avec les sauvegardes des volumes.

Ne figurent pas dans l’archive : le certificat TLS et sa clé (un certificat généré est de nouveau signé par la CA), la configuration de Kratos, les fichiers de la version et les volumes Docker. De certs/ca et registry-token-certs, elle prend les fichiers qu’une installation y crée (rootCA.crt, rootCA.key, rootCA.srl ; token_private.key, token_public.crt, token_public.der, aussi avec .prev ou .new). Tout autre fichier qui s’y trouve est omis, avec un avertissement qui le nomme, car restore n’en accepte aucun autre.

# Écrire l'archive dans un fichier que seul root peut lire
sudo ironflock appliance backup -o /root/appliance-secrets.tar.gz
# L'écrire sur la sortie standard, vers un fichier
sudo ironflock appliance backup > appliance-secrets.tar.gz

ironflock appliance restore

Remet dans le répertoire d’installation une sauvegarde qu’a écrite appliance backup.

ironflock appliance restore <file> [flags]

S’exécute sous : Linux. Root : requis.

La commande prend les fichiers que contient une sauvegarde et rien d’autre, chacun avec le propriétaire et le mode que lui donne une installation. Dans certs/ca et registry-token-certs, elle ne prend que les fichiers qu’une installation y crée. Une archive qui contient quoi que ce soit de plus est refusée avant toute modification, et l’erreur nomme ce surplus.

Les secrets d’une appliance installée ne sont remplacés qu’avec --force ; son .env est conservé sous le nom .env.prev. Sans --force, la restauration sur une appliance installée est refusée avant toute modification, avec le code de sortie 3, et le message nomme la restauration avec --force puis appliance restart.

Une clé de licence de la sauvegarde qui n’est pas une clé de licence valide est restaurée telle quelle, avec un avertissement : chaque commande de l’appliance l’ignore.

Mots de passe des bases de données

• Pendant que la base de données de l’appliance tourne, ses rôles prennent immédiatement les mots de passe restaurés. Redémarrez alors l’appliance (appliance restart), afin que chaque service lise les fichiers restaurés.
• Pendant que l’appliance ne tourne pas, les rôles de sa base de données gardent les mots de passe d’avant. La restauration les marque (<install-dir>/.db-roles-pending ; roles_pending avec --json). Le démarrage suivant leur donne ceux du .env restauré : appliance start ou restart, le démarrage du système, une installation ou une mise à jour.

# Restaurer sur une appliance installée, puis la redémarrer
sudo ironflock appliance restore appliance-secrets.tar.gz --force
sudo ironflock appliance restart

Elle refuse avec le code de sortie 3 tant qu’une mise à jour est restée inachevée (Mise à jour inachevée).

ironflock appliance rotate

Donne une nouvelle valeur à un secret de l’appliance. La nouvelle valeur va là où l’ancienne est conservée (un rôle de base de données, le fichier d’appareil de l’agent, la paire de clés des jetons du registre) et dans .env. Ensuite, seuls les services qui la lisent sont recréés, et la commande vérifie qu’ils sont en bonne santé.

ironflock appliance rotate <name> [flags]

S’exécute sous : Linux, avec une appliance en cours d’exécution. Root : requis. Questions : pour un secret que quelque chose d’autre détient aussi ; --yes répond.

Le .env d’avant la modification est conservé sous le nom .env.prev, lisible par root seul. rotation.log liste chaque rotation, jamais une valeur.

• Un secret que quelque chose d’autre détient aussi (des données, un appareil, un jeton) donne lieu à une question avant sa rotation ; --yes répond.
• FILE_CRED_KEY nécessite un choix pour les clés d’accès direct des clients. --keep-direct-access : elles continuent de fonctionner, pour une rotation planifiée ; terminez-la plus tard avec revoke-direct-access. --revoke-direct-access : elles cessent de fonctionner et sont supprimées, après une fuite présumée.
• APPLIANCE_ADMIN_PASSWORD équivaut à reset-admin-password.

Les secrets dont elle effectue la rotation :

POSTGRES_PASSWORD, PGPASSWORD_KRATOS, PGPASSWORD_ACCT_MANAGER,
PGPASSWORD_ACCT_PUSHER, PGPASSWORD_EXT_ACCT_USER, PGPASSWORD_AUDIT_SANDBOX,
DATASERVICE_PASSWORD, WAMP_SYSTEM_SECRET, WAMP_SECRET_SVC_VDM,
WAMP_SECRET_SVC_IDE, WAMP_SECRET_SVC_IDE_PROXY, WAMP_SECRET_SVC_GIT,
WAMP_SECRET_SVC_REGISTRY, WAMP_SECRET_SVC_REGISTRY_PROXY,
WAMP_SECRET_SVC_ACCT, WAMP_SECRET_SVC_ACCT_PUSH, WAMP_SECRET_SVC_PAYMENT,
WAMP_SECRET_SVC_FLEETDB, WAMP_SECRET_SVC_FLEETFILES, WAMP_SECRET_SVC_AI,
WAMP_SECRET_SVC_TUNNEL, WAMP_SECRET_SVC_RENDERER, WAMP_SECRET_SVC_WEBSERVER,
WAMP_SECRET_SVC_REAPI, WAMP_SECRET_SVC_AUTH, RENDER_TICKET_KEY,
FILES_FORWARD_SECRET, KRATOS_WEBHOOK_SECRET, KRATOS_SECRETS_PAGINATION,
REGISTRY_HTTP_SECRET, TUNNEL_DASHBOARD_PASSWORD, EDGE_SESSION_SECRET,
OBJECTSTORE_ADMIN_ACCESS_KEY, OBJECTSTORE_ADMIN_SECRET_KEY, FILE_CRED_KEY,
FLEETDB_SECRET_KEYS, KRATOS_SECRETS_COOKIE, KRATOS_SECRETS_CIPHER,
APPLIANCE_DEVICE_SECRET, APPLIANCE_ADMIN_PASSWORD, REGISTRY_TOKEN_KEY

L’effet d’une rotation sur chaque type de secret, et les secrets dont la rotation ne se fait qu’avec l’équipe IronFlock, sont décrits dans Rotation d’un secret interne.

# Effectuer la rotation du secret d'un service
sudo ironflock appliance rotate WAMP_SECRET_SVC_AI
# Effectuer la rotation planifiée de la clé des fichiers ; les clés d'accès direct continuent de fonctionner
sudo ironflock appliance rotate FILE_CRED_KEY --keep-direct-access --yes

Elle refuse avec le code de sortie 3 tant qu’une mise à jour est restée inachevée (Mise à jour inachevée).

ironflock appliance revoke-direct-access

Termine une rotation de FILE_CRED_KEY effectuée avec --keep-direct-access. Chaque clé d’accès direct des clients qui n’a pas été créée avec le FILE_CRED_KEY actuel cesse de fonctionner et est supprimée ; la clé elle-même reste. Le service fleetfiles est recréé et indique ce qu’il a supprimé.

ironflock appliance revoke-direct-access [flags]

S’exécute sous : Linux, avec une appliance installée. Root : requis. Questions : oui, car les propriétaires de ces clés doivent en créer de nouvelles ; --yes répond.

sudo ironflock appliance revoke-direct-access

Elle refuse avec le code de sortie 3 tant qu’une mise à jour est restée inachevée (Mise à jour inachevée).

ironflock appliance remove

Supprime l’IronFlock Appliance de cette machine et annule ce que son installation a enregistré sur l’hôte. Ses données restent, sauf si vous donnez --purge.

ironflock appliance remove [flags]

S’exécute sous : Linux. Root : requis. Questions : oui, après avoir listé ce qui disparaît et ce qui reste. La question présélectionne « No » : Entrée seule ne supprime rien.

Elle supprime :

• les unités systemd de l’appliance, ses conteneurs et son réseau dans Docker ;
• la connexion de Docker au registre IronFlock ;
• chaque modification que son installation a enregistrée sur l’hôte (/etc/ironflock/appliance.json) : les paramètres de proxy qu’elle a écrits, ses réglages dans le daemon.json de Docker, les réglages du journal et les cibles de veille masquées ;
• la copie de la version précédente qu’une mise à jour a conservée pour son retour arrière (.update-previous dans le répertoire d’installation).

Les volumes anonymes des conteneurs de l’appliance disparaissent aussi, avec ou sans --purge : jamais un volume nommé, et jamais un volume qu’un conteneur utilise encore.

Ce qui reste

Sans --purge, les données de l’appliance restent, afin qu’une installation ultérieure les reprenne :

• le répertoire d’installation (/opt/ironflock) avec .env, qui contient les secrets, license.env, l’enregistrement des choix de l’installation (install.json) et la marque des mots de passe de base de données qu’une restauration n’a pas pu définir (.db-roles-pending) ;
• les volumes dans Docker.

--purge les supprime aussi, ainsi que les images : ce que contenait l’appliance disparaît définitivement.

Ceci reste même avec --purge :

• Docker lui-même, et l’agent de l’appareil de l’hôte. ironflock agent remove supprime l’agent.
• Un fichier écrit par l’appliance et modifié depuis, comme les paramètres de proxy qu’a définis ironflock agent configure, avec les drop-ins qui les nomment, afin que l’agent garde son proxy.
• Ce que l’enregistrement de l’agent (/opt/ironflock/device-init/installed.json) désigne comme appartenant à l’agent, et les cibles de veille que l’agent a masquées. ironflock agent remove les supprime.

Lorsqu’un appel échoue

Lorsqu’un appel de l’annulation échoue sans cesse (par exemple, un redémarrage d’un Docker supprimé à la main), l’enregistrement reste. La commande indique quel appel a échoué et se termine par une erreur. Exécutez-la à nouveau une fois que cela fonctionne, ou avec --force, qui abandonne malgré tout l’enregistrement et passe outre une unité qui ne peut pas être désactivée ou un Docker qui ne répond pas.

Pendant qu’une installation, une mise à jour ou une autre modification de l’appliance s’exécute, la commande attend jusqu’à 30 secondes et l’indique. Lorsque cette exécution se poursuit, elle ne modifie rien et se termine avec le code de sortie 3.

Exemples

# Supprimer l'appliance et garder ses données ; la commande liste ce qui disparaît et pose la question
sudo ironflock appliance remove
# Supprimer l'appliance avec toutes ses données, sans question
sudo ironflock appliance remove --purge --yes

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

Avant de supprimer définitivement une appliance, déplacez ou libérez sa licence tant qu’elle est encore en ligne (Mise hors service).