Status e Doctor
ironflock status mostra cosa c’è di IronFlock su una macchina e se è in esecuzione. ironflock doctor verifica se una macchina può eseguire l’agente del dispositivo e se raggiunge gli host con cui l’agente comunica. Usali prima di collegare una macchina e quando un dispositivo non va online.
Entrambi i comandi non modificano nulla e non chiedono nulla. Funzionano su Linux e macOS, senza root, e come root leggono di più. Con --host vengono eseguiti su un’altra macchina, anche su più macchine contemporaneamente (Macchine remote via SSH). Lì vengono eseguiti come root quando l’utente di login è root o può usare sudo senza password e senza terminale; altrimenti vengono eseguiti come utente di login, senza chiedere, e il loro suggerimento indica il comando con --host root@machine.
ironflock status
Mostra l’agente del dispositivo, l’Appliance e il sistema operativo di questa macchina: cosa è installato, la sua versione, se il suo servizio è in esecuzione, il dispositivo e il suo progetto, e l’ultimo aggiornamento automatico dell’agente. L’Appliance è il sistema IronFlock completo su una macchina in sede (IronFlock Appliance); per un Appliance il comando mostra anche l’indirizzo della sua UI, la sua licenza, lo stato di salute dei suoi servizi e un aggiornamento in attesa (Comandi dell’Appliance). Su IronFlockOS il comando mostra anche gli slot di root e ciò che richiede attenzione.
ironflock status [flags]Funziona su: Linux; su macOS mostra il sistema e che non è installato nulla. Root: non richiesto; alcune informazioni lo richiedono. Chiede: nulla.
Il comando non ha flag propri. Accetta i flag globali (Flag globali).
Senza root alcune informazioni non si possono leggere: il dispositivo e il suo progetto, perché il .flock dell’agente è accessibile solo a root, e su un Appliance, la cui cartella /opt/ironflock appartiene a root, anche le versioni, l’URL dell’Appliance, la sua licenza e il suo aggiornamento, e l’aggiornamento dell’agente. Lo stato di salute dei servizi dell’Appliance richiede root o il gruppo docker. Queste informazioni indicano unknown (needs root), il campo JSON needs_root le elenca e sudo ironflock status le legge.
# Cosa c'è su questa macchina, letto con il tuo utente di login
ironflock status
# Tutto, come JSON
sudo ironflock status --json
# Lo stato di un'altra macchina via SSH
ironflock --host pi@device-17 statusOutput di testo
$ 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 è il progetto del dispositivo. Connection è unknown per un agente in esecuzione: gli agenti rilasciati finora non comunicano sulla macchina lo stato della loro connessione.
Su IronFlockOS
La riga del sistema mostra l’immagine e i suoi due slot di root (Slot di root e partizione dati):
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 BL’agente di un dispositivo IronFlockOS è quello che l’immagine ha configurato quando il dispositivo si è registrato, in /opt/ironflock/device-agent su /data, e viene mostrato come su qualsiasi altro sistema. Un dispositivo che non si è ancora registrato non ha un agente; l’immagine ne contiene uno, e la riga dice come si registra il dispositivo (prima riga qui sotto). Quando non è stato possibile montare /data a questo avvio, non si vede nemmeno la cartella dell’agente, registrato o no, e la riga lo dice al posto dell’altra (seconda riga):
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 missingSotto il sistema compaiono altre righe, una per caso, solo quando IronFlockOS ha qualcosa da segnalare:
| Riga | Mostrata quando |
|---|---|
Last reset: | l’ultimo reset di fabbrica non è riuscito o ha rinunciato. os reset spiega il significato di un record |
Reset hold: | un reset è aperto (wait: un .flock o un proxy.conf sulla partizione IRONFLOCKOS non viene preso in carico finché i dati del vecchio proprietario possono trovarsi su /data; copy: il reset ha iniziato a cancellare), oppure ha rinunciato e non è riuscito a rimuovere il .flock e il proxy.conf arrivati con esso, che restano inutilizzati (gave-up) |
/data: | non è stato possibile montare /data: il dispositivo funziona con le cartelle proprie dello slot di root, senza Docker e senza le app |
/apps: | /apps non è la cartella della partizione dati: le app funzionano, ma perdono i loro dati al prossimo aggiornamento del sistema operativo |
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 updateUn tentativo di reset fallito riporta attempt 1 of 3 failed at <time>: <reason>; /data holds the old data; the next start tries again finché il blocco è wait o copy, e no request is open now senza blocco. Senza root, il record del reset mostrato è la sua copia nello slot in esecuzione, perché la partizione IRONFLOCKOS appartiene a root.
L’ultimo os install
Su qualsiasi Linux con variabili EFI, una riga OS install: mostra ciò che l’ultimo ironflock os install ha annotato nella variabile EFI di IronFlock IronFlockInstall, se è presente. Ogni utente può leggere la variabile. Dove non può essere letta, o la macchina non ha variabili EFI, non compaiono né la riga né un avviso; un valore che non si riesce a interpretare produce un avviso.
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| Fase | La riga dice |
|---|---|
stopped | che si è fermato prima di scrivere il disco, il motivo, e che non è stato modificato nulla |
handed-over | sul vecchio sistema: l’installer non è partito al riavvio, e non è stato modificato nulla. Su IronFlockOS: ha scritto questo sistema ma non è riuscito ad annotare come si è conclusa l’installazione |
writing | ha iniziato a scrivere il disco e non ha annotato di aver finito |
done | su IronFlockOS: questo sistema è stato installato da os install. Altrove: ha scritto IronFlockOS su un disco della macchina, e il sistema in esecuzione è un altro |
failed | ha scritto il disco, e ciò che ha scritto non ha superato la rilettura, con il motivo |
Il record non viene mai cancellato. La riga resta finché il prossimo os install non lo sostituisce, e su un dispositivo convertito resta come nota del fatto che il sistema è stato installato in questo modo.
Risultato JSON
--json scrive le stesse informazioni come un unico oggetto JSON, mostrato qui su più righe; il comando lo scrive su una riga.
{
"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": []
}Un’informazione che non può essere letta è unknown; quando il motivo non è la mancanza di root, un avviso su stderr dice perché.
| Campo | Valori |
|---|---|
agent.installed | true quando è installato un agente. In tal caso, e solo in tal caso, sono presenti i campi da layout a update. Su IronFlockOS, false significa che il dispositivo non si è ancora registrato |
agent.unfinished_install | true: nessun agente, ma un’installazione precedente si è fermata prima di arrivare all’agente; agent install la annulla per prima cosa. Assente negli altri casi |
agent.layout | current (/opt/ironflock/device-agent), legacy (/opt/reagent, da un installer precedente), migrating (l’agente sta spostando proprio ora la struttura legacy in quella attuale) |
agent.dir | la cartella dell’agente |
agent.version | ciò che il binario dell’agente indica con -version |
agent.service | unit e state: running, starting, stopping, stopped, failed, not_found (systemd non conosce la unit), unknown |
agent.connection | disconnected quando l’agente non è in esecuzione. La connessione di un agente in esecuzione è unknown; connected arriva dagli agenti che la comunicano |
agent.device, agent.swarm | il nome del dispositivo e il suo progetto, dal .flock. Del .flock non viene letto nient’altro |
agent.update | l’ultimo aggiornamento automatico. state: none (nulla in corso, nulla fallito), activating, probation (la nuova versione è in esecuzione e deve connettersi per dimostrare di funzionare), rolled_back (non è riuscito, la versione precedente è di nuovo in esecuzione, la nuova verrà riprovata più tardi), blocked (non è riuscito in modo definitivo; l’agente attende una release più recente), unknown. Con version, previous_version, reason e updated_at |
appliance.installed | true quando l’IronFlock Appliance è installato (la sua unit ironflock.service è presente); in tal caso sono presenti dir, version, channel, url, license, service, health e update |
appliance.data_left | solo quando l’Appliance non è installato e /opt/ironflock contiene ancora i suoi dati, lasciati da appliance remove senza --purge o da un’installazione che si è fermata: quella cartella |
appliance.version, appliance.channel | i file VERSION e CHANNEL nella sua cartella |
appliance.url | l’indirizzo della sua UI: HOME_URL del suo .env. Nient’altro di .env, che contiene i suoi segreti, viene letto |
appliance.license | present quando il suo license.env contiene una chiave di licenza, missing quando no, invalid quando il suo LICENSE_KEY non è una chiave di licenza (un UUID): ogni comando dell’Appliance ignora una chiave del genere, e il testo lo dice. La chiave non viene mai mostrata |
appliance.service | ironflock.service, con gli stessi stati del servizio dell’agente. running significa che la unit ha avviato i container, non che ciascuno di essi sia integro |
appliance.health | lo stato dei suoi servizi, da docker ps: state healthy (ognuno è in esecuzione e supera il suo controllo di salute, oppure non ne ha uno, oppure è stato eseguito una volta ed è terminato con 0), starting (un controllo di salute è in sospeso), unhealthy, down (nessun container), unknown; services, quanti container; problems, ogni servizio non integro con il suo state (unhealthy, starting, restarting, exited con exit_code, …) |
appliance.update | un aggiornamento in attesa, dal file di stato che scrivono la sua UI e il suo timer di ripetizione: state none (nessuno richiesto, oppure l’ultimo è concluso), running, failed (il timer di ripetizione lo riprova), unknown; con version, since e message. cut_short (solo root) indica la release i cui file sono stati conservati da un aggiornamento rimasto a metà: il prossimo aggiornamento li ripristina per primi. Non viene cercata alcuna release |
appliance.ironflock | solo quando l’ironflock che le unit dell’Appliance eseguono a ogni avvio (path, /usr/local/bin/ironflock) è missing o older (state; version, ciò che dice) rispetto a quello che ha installato o aggiornato l’Appliance per ultimo (installed). Solo root, e solo per un Appliance installato da ironflock. Il testo ha allora una riga ironflock:, che dice cosa installare |
os.name, os.id, os.version | PRETTY_NAME, ID e VERSION_ID di /etc/os-release; su un Mac macOS 15.5, macos, 15.5 |
os.ironflockos | true su IronFlockOS. In tal caso os.version è il suo IMAGE_VERSION, e seguono i campi sottostanti |
os.image, os.build | IMAGE_ID e BUILD_ID dell’immagine |
os.booted_slot, os.primary_slot | lo slot da cui è in esecuzione il sistema, e quello che verrà avviato al prossimo boot: A o B |
os.slots | gli slot di root: name (A), rauc_slot (rootfs.0), state (booted, active, inactive), boot_status (good, bad), e version e installed_at della release che un aggiornamento vi ha installato (assenti per uno slot scritto con l’immagine). Assente quando gli slot non possono essere letti |
os.last_reset | il record dell’ultimo reset di fabbrica, solo quando è failed o gave-up: result, time, version, attempt, attempts_max, reason, data (old, new, none: cosa contiene ora /data), e per gave-up left (tra data, booted-slot, other-slot: cosa del vecchio proprietario potrebbe essere ancora presente) |
os.reset_hold | wait, copy o gave-up, solo finché è presente un blocco del reset (vedi la tabella sopra) |
os.data_missing | true, solo quando non è stato possibile montare /data |
os.install | ciò che l’ultimo os install ha annotato, su qualsiasi Linux con variabili EFI, solo quando è presente e leggibile: stage, time (RFC 3339, UTC) e reason (con stopped e failed) |
os.apps_not_persistent | true, solo quando /apps non è la cartella della partizione dati |
needs_root | i campi che indicano unknown perché il comando non è stato eseguito come root, come agent.device e agent.swarm. Vuoto quando non è stato tralasciato nulla |
Codice di uscita
Il codice di uscita è 0 ogni volta che il riepilogo viene scritto, anche quando mostra un agente arrestato, un aggiornamento finito in rollback o uno slot difettoso: status riferisce e non giudica, e uno script legge i campi. È 1 quando il riepilogo non può essere scritto. Per gli altri codici di uscita, vedi Codici di uscita.
ironflock doctor
Verifica se questa macchina può eseguire l’agente del dispositivo e se raggiunge gli host con cui l’agente comunica: il sistema, systemd, Docker, lo spazio libero su disco, l’orologio, il DNS, il proxy, il server di download e gli host indicati nel .flock del dispositivo.
ironflock doctor [flags]Funziona su: Linux e macOS. Root: non richiesto; un controllo che senza root non può verificare risulta skipped e lo dice. Chiede: nulla.
| Flag | Significato |
|---|---|
-c, --config <file> | il file .flock del dispositivo, di cui vengono verificati gli host (predefinito: quello dell’agente installato) |
agent install esegue questi controlli, tutti tranne privileges e docker, prima di modificare qualsiasi cosa, e si ferma quando system, systemd, disk_space o download_tree falliscono.
# Verifica questa macchina, con il tuo utente di login
ironflock doctor
# Verifica tutto come root, in JSON
sudo ironflock doctor --json
# Verifica gli host di un .flock prima di installarlo
ironflock doctor -c device.flockRisultati
Ogni controllo ha un id, un risultato e un riscontro di una riga. Un risultato diverso da ok è accompagnato da un suggerimento che dice cosa fare.
| Risultato | Significato |
|---|---|
ok | nulla da fare |
warning | può funzionare, ma non bene |
failed | con la macchina nello stato attuale l’agente non può essere installato, o non funziona |
skipped | il controllo non ha potuto verificare; il riscontro dice perché |
Controlli
I controlli, nell’ordine in cui vengono mostrati. Un controllo mantiene il suo id; un nuovo controllo riceve un nuovo id.
| Id | Verifica | Quando non è ok |
|---|---|---|
privileges | se il comando viene eseguito come root | warning senza root quando un controllo non ha potuto verificare; il riscontro indica quei controlli. Esegui sudo ironflock doctor |
system | Linux basato su Debian o Ubuntu (l’installazione prende i suoi pacchetti da apt) o IronFlockOS, e l’architettura per cui viene scaricato l’agente | failed su un altro sistema, warning su un altro Linux con apt. agent install si ferma con failed |
systemd | systemd gestisce il sistema (/run/systemd/system è presente) | failed quando systemd non gestisce il sistema; in tal caso agent install si ferma. warning mentre il sistema è degraded: una unit è fallita |
docker | Docker è in esecuzione (docker info) | ok senza Docker, perché agent install lo installa, ma failed con un agente installato. skipped senza root quando l’utente non è nel gruppo docker |
disk_space | lo spazio libero per /opt/ironflock e per /var (Docker, apt, i log) | failed sotto 128 MiB in /opt: un’installazione o un aggiornamento dell’agente vi tiene il suo binario due volte. warning sotto 2 GiB in uno dei due |
clock | l’orologio di questa macchina confrontato con il Date della risposta del server di download, e con il suo Age quando una cache l’ha conservata | ok entro 10 s, warning fino a 5 minuti, failed oltre: le richieste firmate e i token di breve durata vengono rifiutati, e i dati delle app riportano l’ora sbagliata. Un orologio molto sfasato impedisce il TLS stesso: failed, con l’ora che ha la macchina. Vedi Sincronizzazione oraria (NTP) |
dns | i nomi che questa macchina risolve da sé: gli host che raggiunge direttamente, e il proxy | un nome non viene risolto. Un host raggiunto tramite il proxy viene risolto dal proxy |
proxy | il proxy attraverso cui passano i controlli di rete, e da dove viene l’impostazione: la configurazione salvata dall’installazione (/etc/ironflock/proxy.env), altrimenti l’ambiente | failed quando non è l’URL di un proxy. skipped senza root quando l’impostazione si trova nel file, che solo root può leggere |
download_tree | l’agente sul server di download che usa agent install: la sua mappa dei canali, come la legge agent install (device-agent/manifest-v2.json, altrimenti manifest.json), e l’agente del canale di produzione per questa architettura. Con il mirror di un Appliance, ciò che il mirror non fornisce viene cercato nel cloud IronFlock, come lo prende agent install: l’intero agente quando il mirror non fornisce una mappa dei canali, il file dell’agente quando fornisce la mappa senza il file | failed quando non c’è un agente da scaricare, con il mirror dell’Appliance quando né il mirror né il cloud lo hanno; in tal caso agent install si ferma. Un errore del server (5xx) è un warning, e lo è anche un agente che il cloud fornisce dove il mirror non lo fa |
device_endpoint | il device_endpoint_url del .flock risponde | nessuna risposta: l’agente si connette a IronFlock a quell’indirizzo |
docker_registry | il docker_registry_url del .flock risponde (https://<host>/v2/; con una porta, HTTP semplice, come il registry di un Appliance nella LAN) | nessuna risposta: il dispositivo scarica da lì le immagini delle sue app |
update_server | il server di aggiornamento dell’agente ha la sua mappa dei canali: l’update_url del .flock (il mirror di un Appliance), altrimenti il cloud IronFlock | nessuna risposta o nessuna mappa dei canali: l’agente cerca lì i suoi aggiornamenti |
Il server di download è quello che usa agent install: --download-base, altrimenti la variabile d’ambiente IRONFLOCK_DL_BASE, altrimenti il mirror di download dell’Appliance indicato dal .flock (il suo update_url, quando non è un host del cloud IronFlock), con il cloud per ciò che il mirror non fornisce, altrimenti il cloud IronFlock (Da dove viene l’agente). Gli host che un dispositivo deve raggiungere sono elencati in Requisiti di Rete.
Con e senza -c e root
Gli ultimi tre controlli richiedono un .flock: quello di -c, altrimenti quello dell’agente installato.
| Come root | Senza root | |
|---|---|---|
Senza -c | gli host del .flock dell’agente installato | gli ultimi tre controlli risultano skipped: il .flock dell’agente installato è accessibile solo a root |
Con -c | gli host del .flock indicato | gli host del .flock indicato |
Senza root, anche docker risulta skipped fuori dal gruppo docker, e proxy risulta skipped quando l’installazione ha salvato il proxy. In questo caso anche un controllo di rete il cui host non risponde risulta skipped (per dns, un nome che non viene risolto), perché potrebbe ricevere risposta tramite il proxy salvato. privileges indica ogni controllo che non ha potuto verificare, e sudo ironflock doctor li esegue.
Come decidono i controlli di rete
- Un host risponde quando arriva una risposta HTTP, qualunque sia il suo stato. Un 502, 503 o 504 a una richiesta HTTP semplice tramite il proxy non è una risposta: il proxy lo restituisce quando non riesce a raggiungere l’host.
- Un certificato che TLS rifiuta non è una risposta. L’unica eccezione è il certificato della CA propria di un Appliance, quando il
.flockindica unappliance_domain: l’agente lo considera attendibile. - I controlli passano attraverso il proxy del controllo
proxy, secondo le regole diHTTPS_PROXY,HTTP_PROXYeNO_PROXYseguite dai download, anche per ogni richiesta di un redirect, e attendono una risposta per 20 s. - Un host che una voce di
NO_PROXYesclude dal proxy viene raggiunto direttamente. Quando in quel modo non risponde, il riscontro indica la voce, ad esempio(directly: instance-registry.ironflock.com is in NO_PROXY), e il suggerimento dice di togliere la voce, indicando il comandoagent configure --no-proxyche lo fa quando l’impostazione è quella salvata dall’installazione.
Output
$ 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.Con il mirror dell’Appliance del .flock, la prima riga lo dice:
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)Con --json, qui abbreviato e mostrato su più righe; il comando scrive una sola riga.
{
"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"
}| Campo | Valori |
|---|---|
result | failed quando un controllo è fallito, warning quando uno ha dato un avviso, altrimenti ok. Un controllo saltato non fa fallire nulla |
checks | i controlli, nell’ordine indicato sopra: id, result, finding e hint con ogni risultato tranne ok |
download_base | il server di download verificato. Con il mirror dell’Appliance, solo il mirror; i riscontri indicano il cloud quando cercano lì |
flock | il .flock di cui sono stati verificati gli host; null se non ce n’è uno |
Nessun output mostra un segreto: di un .flock i controlli leggono solo gli host, e la password di un proxy compare come xxxxx.
Codice di uscita
Il codice di uscita è 0 quando nessun controllo è fallito; un avviso non fa fallire. È 1 quando un controllo è fallito: il risultato dice quale, non segue alcuna riga di errore e, con --json, stdout contiene il risultato, non un oggetto errore. È 1 con un errore quando il .flock di -c non può essere letto. Per gli altri codici di uscita, vedi Codici di uscita.