Skip to Content
Développement d'applications IoTCLI IronFlockConnexion et gestion des appareils

Connexion et gestion des appareils

Ces commandes s’adressent à une instance IronFlock, le cloud ou une appliance, et non à la machine sur laquelle elles s’exécutent. ironflock login enregistre une clé API sur cette machine, whoami nomme le compte auquel la clé appartient, et logout supprime la clé. ironflock device create, list et delete travaillent ensuite sur les appareils de vos projets. agent install, os flash et os install peuvent créer l’appareil pour vous avec --project et --name.

Aucune d’elles n’a besoin de root, et toutes s’exécutent sous Linux, macOS et Windows. Elles n’agissent que sur cette machine : --host et --hosts sont refusées avec le code de sortie 2, et ni la clé ni le fichier d’identifiants ne vont jamais sur une autre machine (Machines distantes via SSH).

login et whoami ont besoin d’une instance dont le service API répond à GET /v1/ironflock/whoami (Endpoints de l’API). Le cloud IronFlock le fait. Une instance sans cette route répond 404, et les commandes le disent. Une IronFlock Appliance propose la route dès qu’elle exécute le service API IronFlock ; les versions de l’appliance qui ne l’exécutent pas encore ne peuvent pas être utilisées avec ces commandes. Les commandes s’adressent à l’API de l’instance et à rien d’autre, et utilisent le proxy de l’environnement (HTTPS_PROXY, NO_PROXY) comme toute autre requête de ironflock.

L’instance

Le cloud est la valeur par défaut. --instance, ou à défaut la variable d’environnement IRONFLOCK_INSTANCE, désigne une autre instance : une appliance. Indiquez ce que vous avez sous la main, et la commande en déduit l’adresse de l’API :

Vous indiquezL’API est
rien, ou ironflock.com, studio.ironflock.com ou api.ironflock.comhttps://api.ironflock.com
le domaine de l’appliance, factory.example.comhttps://api.factory.example.com
l’adresse avec laquelle Studio est ouvert, https://factory.example.com/projects/12https://api.factory.example.com
l’hôte propre de l’API, api.factory.example.comhttps://api.factory.example.com

Sans schéma, https:// est sous-entendu. Le simple http n’est accepté que pour une adresse de loopback, pour une pile sur cette machine. Une adresse IP autre que le loopback est refusée : l’API d’une appliance est jointe par son nom. Une appliance en mode HTTP simple n’a pas de api.<domain>, et login ne l’atteint pas. Le certificat de l’instance est vérifié par rapport au magasin de confiance de cette machine et aux autorités de certification de --ca-cert (un fichier PEM, plusieurs fois pour plusieurs), par exemple la CA de votre entreprise qui a signé le certificat d’une appliance. Rien ne désactive la vérification.

Le fichier d’identifiants

login conserve la clé dans credentials.json, dans le dossier ironflock du dossier de configuration de votre utilisateur : ~/.config/ironflock/ sous Linux, ~/Library/Application Support/ironflock/ sur un Mac et %LOCALAPPDATA%\ironflock\credentials\ sous Windows. Il contient une entrée par instance et n’est lisible que par vous. Un fichier ou un dossier que d’autres peuvent lire ou modifier n’est pas utilisé : la commande se termine avec le code de sortie 3, indique comment le réparer et ne modifie rien.

Pour les scripts et la CI, IRONFLOCK_API_KEY contient une clé que chaque commande utilise à la place de celle enregistrée. login ne la lit ni ne l’enregistre jamais.

VariableSignification
IRONFLOCK_INSTANCEL’instance lorsque --instance n’est pas indiquée
IRONFLOCK_API_KEYLa clé API à utiliser à la place de celle enregistrée
HTTPS_PROXY, NO_PROXYLe proxy pour les requêtes vers l’instance

ironflock login

Enregistre une clé API pour une instance, après avoir demandé à l’instance à qui appartient la clé.

ironflock login [--key-file <file>] [--instance <domain or URL>] [--ca-cert <file>]...
$ ironflock login --key-file key.txt --instance factory.example.com Logged in to https://api.factory.example.com as operator (account 12). The key is stored in /home/operator/.config/ironflock/credentials.json.

S’exécute sous : Linux, macOS et Windows. Root : non requis. Questions : aucune.

OptionSignification
--key-file <file>Le fichier ou le pipe qui contient la clé. Par défaut : l’entrée standard, lorsque ce n’est pas un terminal
--instance <instance>L’instance. Par défaut : IRONFLOCK_INSTANCE, sinon le cloud
--ca-cert <file>Une autorité de certification à laquelle faire confiance en plus de celles de cette machine ; plusieurs fois pour plusieurs
  • La clé ne figure jamais sur une ligne de commande. Elle provient d’un fichier ou d’un pipe, et la commande ne la demande jamais dans le terminal. Sans l’un ou l’autre, elle se termine avec le code de sortie 2 et indique comment en passer une. Les espaces autour de la clé sont supprimés. Une clé fait 40 caractères 0-9 et a-f ; tout le reste est refusé avant toute requête, et l’erreur ne la répète pas.
  • Avant que quoi que ce soit ne soit enregistré, on demande à l’instance à qui appartient la clé. Une clé que l’instance n’accepte pas, une instance qui ne peut pas répondre, un certificat non approuvé ou une instance injoignable se terminent avec le code de sortie 1, et ce qui était enregistré auparavant reste tel quel.
  • Une connexion à une instance qui en a déjà une la remplace. Les connexions des autres instances restent.
  • La requête ne suit aucune redirection, afin que la clé n’aille vers aucun autre hôte.
  • Avec --json, le résultat est un objet avec action (logged_in), instance, account_id, username, scopes, restriction et credential_file.

Placez la clé dans un fichier que vous seul pouvez lire, puis connectez-vous :

(umask 077; cat > key.txt) ironflock login --key-file key.txt

Tapez ou collez la clé dans le terminal après cat > key.txt, terminez par Ctrl-D, et supprimez key.txt une fois que login a enregistré la clé.

ironflock whoami

Nomme le compte auquel la clé appartient, et indique ce que la clé peut faire.

ironflock whoami [--instance <domain or URL>] [--ca-cert <file>]...
$ ironflock whoami --instance factory.example.com Instance: https://api.factory.example.com Account: operator (12) Scopes: devices:read, devices:write Restriction: the projects 3 Key: stored by 'ironflock login' on 2026-11-19 10:00 UTC

La clé est IRONFLOCK_API_KEY lorsqu’elle est définie, sinon celle que login a enregistrée pour l’instance. Sans l’une ni l’autre, la commande se termine avec le code de sortie 3 et nomme le login à exécuter. Scopes sont les autorisations de la clé, none lorsqu’elle n’en a aucune. Restriction vaut none: everything the account may do, the projects 3, 5 ou the app 5. Avec --json, le résultat contient instance, account_id, username, scopes, restriction, key_source (environment ou credential_file) et, pour une clé enregistrée, logged_in_at.

Une clé enregistrée que l’instance n’accepte plus, par exemple une clé supprimée dans Studio, n’est pas retirée : l’erreur nomme le login qui la remplace.

ironflock logout

Supprime la clé enregistrée d’une instance. Les connexions des autres instances restent.

ironflock logout [--instance <domain or URL>]
$ ironflock logout --instance factory.example.com Logged out of https://api.factory.example.com: its key is removed from /home/operator/.config/ironflock/credentials.json. The key itself stays valid until it is deleted in Studio.

logout ne s’adresse à aucune instance : la clé reste valable jusqu’à ce que vous la supprimiez dans Studio. L’absence de connexion enregistrée n’est pas une erreur : la commande le dit et se termine avec le code de sortie 0. Si IRONFLOCK_API_KEY est définie, une note indique que les commandes utilisent toujours la variable.

ironflock device create

Crée un appareil dans un projet et écrit le fichier .flock de l’appareil, qui contient les identifiants de l’appareil.

ironflock device create --project <project> --name <name> -o <file.flock> [flags]
$ ironflock device create --project 12 --name press-7 -o press-7.flock Created the device press-7 (key 345) in the project Packaging (key 12). Its .flock is in press-7.flock: it holds the device's credentials, which the platform shows no more. 'sudo ironflock agent install -c press-7.flock' connects a machine as this device.

S’exécute sous : Linux, macOS et Windows. Root : non requis. Nécessite : une clé avec l’autorisation devices:write ; un projet indiqué par son nom est recherché avec devices:read.

OptionSignification
--project <project>Obligatoire. La clé du projet, ou son nom
--name <name>Obligatoire. Le nom de l’appareil : 1 à 100 lettres, chiffres, points, tirets bas et traits d’union. Le projet ne doit pas encore avoir d’appareil de ce nom
-o, --output <file>Obligatoire. Le fichier pour le .flock, nommé *.flock, ou - pour la sortie standard
--description <text>2000 caractères au plus
--wifi-ssid <name>Le réseau Wi-Fi de l’appareil. Va avec --wifi-password-file
--wifi-password-file <file>Le fichier ou le pipe contenant la phrase secrète du réseau. Va avec --wifi-ssid
--forceRemplacer le fichier de -o s’il existe
--instance, --ca-certComme pour whoami
  • Un projet indiqué par son nom est recherché parmi les projets dans lesquels la clé peut travailler, et doit être exactement le nom d’un projet. Un nom qui ne correspond à aucun donne le code de sortie 1. Un nom porté par plusieurs projets donne le code de sortie 2, et le message nomme leurs clés.
  • Le fichier .flock est privé dès son premier octet : mode 0600, ou sous Windows une liste d’accès qui ne l’accorde qu’à vous. Un fichier existant n’est pas remplacé sans --force, et le dossier et le nom sont vérifiés avant la création de l’appareil, car l’API ne renvoie les identifiants qu’à la création de l’appareil. Sur un système de fichiers sans modes de fichier, comme une clé USB formatée en FAT, le fichier n’est pas privé : écrivez-le sur un disque de la machine et copiez-le de là.
  • -o - écrit le fichier sur la sortie standard, qui ne doit pas être un terminal, par exemple pour le transmettre par pipe à une autre machine. La ligne de résultat va alors sur la sortie d’erreur standard.
  • Rien du fichier n’est affiché : le résultat nomme l’appareil par sa clé et son nom, ainsi que le projet.
  • Si quelque chose échoue après la création de l’appareil, l’erreur le dit et nomme la commande qui supprime l’appareil.

Connectez une machine avec le fichier comme décrit dans Commandes de l’agent de l’appareil, ou écrivez-le sur un lecteur avec os flash.

ironflock device list

Liste les appareils sur lesquels votre compte a des droits, dans les projets où la clé peut agir.

ironflock device list [--project <project>] [--instance <instance>] [--ca-cert <file>]...
$ ironflock device list --project Packaging KEY NAME PROJECT STATUS ARCHITECTURE AGENT 17 press-7 12 CONNECTED amd64 1.4.2 18 press-8 12 CONFIGURING amd64 -

Nécessite : une clé avec l’autorisation devices:read. --project ne garde que les appareils d’un projet. L’absence d’appareil n’est pas une erreur : la commande dit No devices. Avec --json, le résultat contient instance et devices, chaque appareil avec device_key, name, project_key, description, status, architecture et agent_version. Seuls ces champs sont lus dans la réponse : les identifiants d’un appareil n’en font jamais partie.

ironflock device delete

Supprime un appareil d’un projet. Un appareil supprimé ne peut pas être récupéré.

ironflock device delete --project <project> <device_key> [--yes] [--instance <instance>] [--ca-cert <file>]...
$ ironflock device delete --project Packaging 17 This deletes the device 17 from the project Packaging (key 12) of https://api.ironflock.com. A deleted device cannot be brought back. Delete the device 17? [y/N] Deleted the device press-7 (key 17) from the project 12.

Nécessite : une clé avec l’autorisation devices:write. La clé de l’appareil est l’unique argument. La commande dit ce qui disparaît et pose la question, avec Non présélectionné ; --yes répond oui. Sans terminal, et avec --json, elle ne pose aucune question et se termine avec le code de sortie 4, sauf si --yes est indiqué : rien n’est alors supprimé. Un appareil qui n’est pas dans le projet, ou que la clé ne peut pas voir, donne 404.

Installer un nouvel appareil avec --project et --name

ironflock agent install, ironflock os flash et ironflock os install acceptent --project <project> --name <name> à la place de -c <device.flock>. La commande crée l’appareil et continue avec le .flock que la plateforme envoie, exactement comme elle continue avec le fichier de -c. Le .flock est conservé en mémoire et dans aucun fichier dont vous auriez à vous occuper.

sudo ironflock agent install --project Packaging --name press-9 --yes ironflock os flash --project 12 --name cell-4 -d /dev/sdb ironflock --host admin@machine os install --project 12 --name cell-4 --disk /dev/sda --yes --wait-online
OptionSignification
--project <project>Le projet dans lequel créer l’appareil : sa clé ou son nom, comme pour device create
--name <name>Le nom du nouvel appareil, comme pour device create
--instance <instance>L’instance, comme pour whoami
--ca-cert <file>agent install : une autorité de certification du certificat de l’instance. os flash et os install ont leur propre --ca-cert, pour l’appareil ; avec --project, on lui fait aussi confiance pour l’instance
--wait-online[=<duration>]os install via --host uniquement : après la commande sur la machine, attendre jusqu’à la durée indiquée (1 minute à 2 heures ; seule, 15 minutes) que la plateforme voie l’appareil en ligne. La valeur suit =, comme dans --wait-online=20m
  • --project et --name vont ensemble et excluent -c. agent install et os flash ont besoin de l’un des deux ; os install sans l’un ni l’autre prend le .flock de l’agent installé, comme auparavant. --dry-run avec --project est refusé, car une exécution à blanc ne crée rien.
  • La clé est celle de whoami : IRONFLOCK_API_KEY, sinon la connexion enregistrée. Une commande exécutée avec sudo s’exécute en tant que root et cherche la connexion de root : passez la clé avec sudo --preserve-env=IRONFLOCK_API_KEY, ou exécutez la commande depuis votre propre machine avec --host. Avec --host, la plateforme est interrogée depuis votre machine, et la machine ne reçoit que le .flock : la clé, le fichier d’identifiants et IRONFLOCK_API_KEY ne l’atteignent jamais.
  • La plateforme ne donne le .flock d’un appareil que dans la réponse qui le crée. Un nom que le projet a déjà est donc refusé (code de sortie 1) : installez cet appareil avec son .flock et -c, ou supprimez-le d’abord avec device delete.
  • Si une étape échoue après la création de l’appareil, l’erreur le dit et nomme la commande device delete qui supprime l’appareil. Exécutez-la, puis relancez la même commande.

Erreurs

Un échec se termine avec le code de sortie 1 et une phrase. La phrase de l’instance suit le statut.

RéponseLa phrase dit
Injoignable, certificat non approuvéL’instance ne peut pas être jointe, avec une indication pour --ca-cert
400L’instance a refusé la requête, et pourquoi
401L’instance n’accepte pas la clé, et d’où elle venait. Pour une clé enregistrée, le login qui la remplace
403La clé n’a pas le droit de faire cela : ses autorisations, ou les projets ou l’application auxquels elle est limitée, ne le permettent pas. whoami les affiche
404Pour delete : l’appareil n’est pas dans le projet, ou la clé ne peut pas le voir. Pour create : le projet n’existe pas pour cette clé
409Un conflit avec ce que contient la plateforme, comme un nom d’appareil que le projet a déjà
500, 503, 504La plateforme n’est pas disponible. Pour create et delete, aussi que la modification a pu être effectuée, et le device list qui le montre

Après tout échec survenu une fois la requête écrite, et après Ctrl-C pendant que create ou delete attend, le message indique que la modification a pu être effectuée. Exécutez ironflock device list avant de la répéter : un second create du même nom est un conflit, et l’API ne renvoie pas à nouveau les identifiants du premier appareil (Studio peut télécharger son fichier de configuration).

Codes de sortie

Ces commandes utilisent les codes de sortie de toutes les commandes.

CodeSignifie ici
0Terminé
1L’instance ou la plateforme a refusé ou échoué, un nom de projet ne correspond à aucun projet, ou un fichier n’a pas pu être écrit
2La ligne de commande est erronée : une option manquante ou incorrecte, un nom de projet porté par plusieurs projets, un fichier existant sans --force, --host ou --hosts. La plateforme n’a pas été interrogée
3Aucune connexion : IRONFLOCK_API_KEY n’est pas définie et aucune n’est enregistrée ; ou le fichier d’identifiants ne peut pas être utilisé. La plateforme n’a pas été interrogée
4La question de device delete a reçu la réponse non, ou n’a pas pu être posée et --yes n’a pas été indiqué. Rien n’a été supprimé
130Interrompue pendant que la plateforme était interrogée. La modification a pu être effectuée
Last updated on