Status et Doctor

ironflock status affiche ce qu’une machine contient d’IronFlock et si cela fonctionne. ironflock doctor vérifie si une machine peut exécuter l’agent de l’appareil et si elle joint les hôtes avec lesquels l’agent communique. Utilisez-les avant de connecter une machine, et lorsqu’un appareil ne passe pas en ligne.

Les deux commandes ne modifient rien et ne posent aucune question. Elles s’exécutent sous Linux et macOS, sans root, et lisent davantage en tant que root. Avec --host, elles s’exécutent sur une autre machine, y compris sur plusieurs à la fois (Machines distantes via SSH). Elles s’y exécutent en tant que root lorsque le compte de connexion est root ou peut utiliser sudo sans mot de passe et sans terminal ; sinon, elles s’exécutent sous le compte de connexion, sans rien demander, et leur conseil indique la commande avec --host root@machine.

ironflock status

Affiche l’agent de l’appareil, l’appliance et le système d’exploitation de cette machine : ce qui est installé, sa version, si son service tourne, l’appareil et son projet, et la dernière mise à jour automatique de l’agent. L’appliance est le système IronFlock complet sur une machine sur site (IronFlock Appliance) ; pour une appliance, la commande affiche aussi l’adresse de son UI, sa licence, la santé de ses services et une mise à jour en attente (Commandes de l’appliance). Sur IronFlockOS, la commande affiche aussi les slots racine et ce qui demande votre attention.

ironflock status [flags]

S’exécute sous : Linux ; sous macOS, la commande affiche le système et indique que rien n’est installé. Root : non requis ; quelques informations en ont besoin. Questions : aucune.

La commande n’a pas d’options propres. Elle accepte les options globales (Options globales).

Sans root, certaines informations ne peuvent pas être lues : l’appareil et son projet, car le .flock de l’agent n’est accessible qu’à root, et sur une appliance, dont le dossier /opt/ironflock appartient à root, également les versions, l’URL de l’appliance, sa licence et sa mise à jour, ainsi que la mise à jour de l’agent. La santé des services de l’appliance nécessite root ou le groupe docker. Elles indiquent unknown (needs root), le champ JSON needs_root les liste, et sudo ironflock status les lit.

# Ce qui se trouve sur cette machine, lu sous votre compte
ironflock status
# Tout, en JSON
sudo ironflock status --json
# L'état d'une autre machine via SSH
ironflock --host pi@device-17 status

Sortie texte

$ ironflock status
Agent:         installed in /opt/ironflock/device-agent
  Version:     1.6.9
  Service:     running (ironflock-device-agent.service)
  Connection:  unknown (this agent does not report it)
  Device:      unknown (needs root)
  Swarm:       unknown (needs root)
  Update:      none pending
Appliance:     not installed
System:        Debian GNU/Linux 12 (bookworm)

Run 'sudo ironflock status' to read what needs root.

Swarm est le projet de l’appareil. Connection vaut unknown pour un agent en cours d’exécution : les agents publiés jusqu’ici n’indiquent pas leur connexion sur la machine.

Sur IronFlockOS

La ligne du système affiche l’image et ses deux slots racine (Slots racine et partition de données) :

System:        IronFlockOS 0.13.0 (amd64-efi, base)
  Image:       ironflockos-amd64-efi-base (build 20261105T120000Z-g1a2b3c4)
  Slot A:      inactive, good
  Slot B:      booted, good, 0.13.0 installed 2026-11-05T14:00:00Z
  Next boot:   slot B

L’agent d’un appareil IronFlockOS est celui que l’image a mis en place lors de l’enrôlement de l’appareil, dans /opt/ironflock/device-agent sur /data, et il est affiché comme sur n’importe quel autre système. Un appareil qui ne s’est pas encore enrôlé n’a pas d’agent ; l’image en contient un, et la ligne indique comment l’appareil s’enrôle (première ligne ci-dessous). Lorsque /data n’a pas pu être monté lors de ce démarrage, le dossier de l’agent n’est pas visible non plus, que l’appareil soit enrôlé ou non, et la ligne le dit à la place (deuxième ligne) :

Agent:         not enrolled yet: the device enrolls with a .flock on its IRONFLOCKOS partition at its next start, or now with 'sudo ironflock agent configure -c <file>'
Agent:         not to be seen: /data, which holds the agent and its .flock, could not be mounted (below); a .flock on the IRONFLOCKOS partition enrolls the device at its next start for as long as /data is missing

Sous le système, chacune des lignes suivantes n’apparaît que lorsqu’IronFlockOS a quelque chose à signaler :

  Last reset:  gave up after 3 attempts at 2026-11-11T09:00:00Z: the data partition is not the partition named data on the disk of the root slot; /data holds the old data; left of the old owner: the data partition, the booted root slot, the other root slot
  Reset hold:  wait: a reset is open; a .flock or proxy.conf on the IRONFLOCKOS partition is not taken while the old owner's data may be on /data
  /data:       NOT MOUNTED: the device runs on the root slot's own folders; Docker and the apps do not run, and what is written now is lost with the next update
  /apps:       not the data partition's folder: the apps run, but lose their data at the next OS update

Une tentative de réinitialisation qui a échoué se lit attempt 1 of 3 failed at <time>: <reason>; /data holds the old data; the next start tries again tant que le verrou vaut wait ou copy, et no request is open now sans verrou. Sans root, l’enregistrement de réinitialisation affiché est sa copie dans le slot en cours d’exécution, car la partition IRONFLOCKOS appartient à root.

Le dernier os install

Sur tout Linux doté de variables EFI, une ligne OS install: indique ce que le dernier ironflock os install a enregistré dans la variable EFI IronFlockInstall d’IronFlock, lorsqu’elle existe. Chaque utilisateur peut lire la variable. Là où elle ne peut pas être lue, ou si la machine n’a pas de variables EFI, il n’y a ni ligne ni avertissement ; une valeur qui ne s’analyse pas donne un avertissement.

System:        Debian GNU/Linux 13 (trixie)
  OS install:  'ironflock os install' stopped at 2026-11-11T10:00:00Z before it wrote the disk: the disk /dev/sda is not the plan's: its size changed from 64.0 GB to 32.0 GB; nothing was changed, and this system runs as before

L’enregistrement n’est jamais effacé. La ligne reste jusqu’à ce que le prochain os install le remplace et, sur un appareil converti, elle reste comme indication que le système a été installé de cette façon.

Résultat JSON

--json écrit la même chose sous la forme d’un objet JSON, présenté ici sur plusieurs lignes ; la commande l’écrit sur une seule ligne.

{
  "agent": {
    "installed": true,
    "layout": "current",
    "dir": "/opt/ironflock/device-agent",
    "version": "1.6.9",
    "service": {"unit": "ironflock-device-agent.service", "state": "running"},
    "connection": "unknown",
    "device": "demo-device",
    "swarm": "demo_swarm",
    "update": {"state": "none"}
  },
  "appliance": {"installed": false},
  "os": {"name": "Debian GNU/Linux 12 (bookworm)", "id": "debian", "version": "12", "ironflockos": false},
  "needs_root": []
}

Une information qui ne peut pas être lue vaut unknown ; lorsque root n’en est pas la raison, un avertissement sur stderr dit pourquoi.

Code de sortie

Le code de sortie est 0 chaque fois que la vue d’ensemble est écrite, y compris lorsqu’elle montre un agent arrêté, une mise à jour annulée ou un slot défectueux : status rend compte et ne juge pas, et un script lit les champs. Il est 1 lorsque la vue d’ensemble ne peut pas être écrite. Pour les autres codes de sortie, voir Codes de sortie.

ironflock doctor

Vérifie si cette machine peut exécuter l’agent de l’appareil, et si elle joint les hôtes avec lesquels l’agent communique : le système, systemd, Docker, l’espace disque libre, l’horloge, le DNS, le proxy, le serveur de téléchargement et les hôtes que nomme le .flock de l’appareil.

ironflock doctor [flags]

S’exécute sous : Linux et macOS. Root : non requis ; une vérification qui ne peut pas examiner sans root est skipped et le dit. Questions : aucune.

agent install exécute ces vérifications, toutes sauf privileges et docker, avant de modifier quoi que ce soit, et s’arrête lorsque system, systemd, disk_space ou download_tree échoue.

# Vérifier cette machine, sous votre compte
ironflock doctor
# Tout vérifier en tant que root, en JSON
sudo ironflock doctor --json
# Vérifier les hôtes d'un .flock avant de l'installer
ironflock doctor -c device.flock

Résultats

Chaque vérification a un identifiant, un résultat et un constat d’une ligne. Un résultat autre que ok s’accompagne d’un conseil qui indique quoi faire.

Vérifications

Les vérifications, dans l’ordre où elles sont affichées. Une vérification garde son identifiant ; une nouvelle vérification en reçoit un nouveau.

Le serveur de téléchargement est celui que prend agent install : --download-base, sinon la variable d’environnement IRONFLOCK_DL_BASE, sinon le miroir de téléchargement de l’appliance que nomme le .flock (son update_url, lorsque ce n’est pas un hôte du cloud IronFlock), avec le cloud pour ce que le miroir ne fournit pas, sinon le cloud IronFlock (D’où vient l’agent). Les hôtes qu’un appareil doit joindre sont listés dans Exigences réseau.

Avec et sans -c et root

Les trois dernières vérifications ont besoin d’un .flock : celui de -c, sinon celui de l’agent installé.

Sans root, docker est aussi skipped en dehors du groupe docker, et proxy est skipped lorsque l’installation a enregistré le proxy. Une vérification réseau dont l’hôte ne répond pas est alors aussi skipped (pour dns, un nom qui ne se résout pas), car elle pourrait obtenir une réponse via le proxy enregistré. privileges nomme chaque vérification qui n’a pas pu examiner, et sudo ironflock doctor les exécute.

Comment les vérifications réseau décident

• Un hôte répond lorsqu’une réponse HTTP arrive, quel que soit son statut. Un 502, 503 ou 504 à une requête HTTP simple via le proxy n’est pas une réponse : le proxy le renvoie lorsqu’il ne peut pas joindre l’hôte.
• Un certificat que TLS refuse n’est pas une réponse. La seule exception est le certificat de la propre CA d’une appliance, lorsque le .flock nomme un appliance_domain : l’agent lui fait confiance.
• Les vérifications passent par le proxy de la vérification proxy, selon les règles de HTTPS_PROXY, HTTP_PROXY et NO_PROXY que suivent les téléchargements, y compris pour chaque requête d’une redirection, et attendent une réponse pendant 20 s.
• Un hôte qu’une entrée de NO_PROXY tient à l’écart du proxy est joint directement. Lorsqu’il ne répond pas de cette façon, le constat nomme l’entrée, par exemple (directly: instance-registry.ironflock.com is in NO_PROXY), et le conseil dit de retirer l’entrée, avec la commande agent configure --no-proxy qui le fait lorsque le paramètre est l’enregistrement de l’installation.

Sortie

$ sudo ironflock doctor
Download base: https://instance-registry.ironflock.com/dl
Device file:   /opt/ironflock/device-agent/device-config.flock

CHECK            RESULT  FINDING
privileges       ok      runs as root
system           ok      Debian GNU/Linux 12 (bookworm), amd64
systemd          ok      systemd runs this system
docker           ok      Docker 27.3.1 runs
disk_space       ok      50.0 GB free for /opt and /var
clock            ok      within 10 s of the download server's clock
dns              ok      resolves instance-registry.ironflock.com, cbw.ironflock.com, europe-docker.pkg.dev
proxy            ok      none: the connections go direct
download_tree    ok      https://instance-registry.ironflock.com/dl has the agent 1.6.9 for amd64
device_endpoint  ok      cbw.ironflock.com answers
docker_registry  failed  europe-docker.pkg.dev cannot be reached: no answer within 20 s
update_server    ok      https://instance-registry.ironflock.com/dl has the agent's updates

What to do:
  docker_registry: the device pulls its apps' images from there: let this machine reach europe-docker.pkg.dev on port 443, directly or through the proxy

Failed: docker_registry.

Avec le miroir de l’appliance du .flock, la première ligne l’indique :

Download base: http://10.0.0.5:15002/dl (the appliance's mirror of the .flock; the IronFlock cloud for what it does not give)

Avec --json, ici raccourci et présenté sur plusieurs lignes ; la commande écrit une seule ligne.

{
  "result": "failed",
  "checks": [
    {"id": "privileges", "result": "ok", "finding": "runs as root"},
    {"id": "docker_registry", "result": "failed", "finding": "europe-docker.pkg.dev cannot be reached: no answer within 20 s", "hint": "the device pulls its apps' images from there: let this machine reach europe-docker.pkg.dev on port 443, directly or through the proxy"}
  ],
  "download_base": "https://instance-registry.ironflock.com/dl",
  "flock": "/opt/ironflock/device-agent/device-config.flock"
}

Aucune sortie ne montre de secret : d’un .flock, les vérifications ne lisent que les hôtes, et le mot de passe d’un proxy s’affiche sous la forme xxxxx.

Code de sortie

Le code de sortie est 0 lorsqu’aucune vérification n’a échoué ; un avertissement ne fait pas échouer. Il est 1 lorsqu’une vérification a échoué : le résultat dit laquelle, aucune ligne d’erreur ne le suit et, avec --json, stdout contient le résultat, pas un objet d’erreur. Il est 1 avec une erreur lorsque le .flock de -c ne peut pas être lu. Pour les autres codes de sortie, voir Codes de sortie.