Status e Doctor
O ironflock status mostra o que há do IronFlock em uma máquina e se está em execução. O ironflock doctor verifica se uma máquina pode executar o agente do dispositivo e se alcança os hosts com que o agente se comunica. Use-os antes de conectar uma máquina e quando um dispositivo não fica online.
Os dois comandos não alteram nada e não perguntam nada. Eles rodam no Linux e no macOS, sem root, e leem mais como root. Com --host, rodam em outra máquina, também em várias ao mesmo tempo (Máquinas remotas via SSH). Lá, rodam como root quando o usuário de login é root ou pode usar sudo sem senha e sem terminal; caso contrário, rodam como o usuário de login, sem perguntar, e a dica deles indica o comando com --host root@machine.
ironflock status
Mostra o agente do dispositivo, o appliance e o sistema operacional desta máquina: o que está instalado, a versão, se o serviço está rodando, o dispositivo e o seu projeto, e a última autoatualização do agente. O appliance é o sistema IronFlock completo em uma máquina no local (IronFlock Appliance); para um appliance, o comando também mostra o endereço da sua UI, a sua licença, a saúde dos seus serviços e uma atualização pendente (Comandos do appliance). No IronFlockOS, o comando também mostra os slots raiz e o que exige atenção.
ironflock status [flags]Roda em: Linux; no macOS, mostra o sistema e que nada está instalado. Root: não necessário; algumas informações precisam dele. Pergunta: nada.
O comando não tem flags próprias. Ele aceita as flags globais (Flags globais).
Sem root, algumas informações não podem ser lidas: o dispositivo e o seu projeto, pois o .flock do agente pertence só ao root, e, em um appliance, cuja pasta /opt/ironflock pertence ao root, também as versões, a URL do appliance, a sua licença e a sua atualização, e a atualização do agente. A saúde dos serviços do appliance precisa de root ou do grupo docker. Elas aparecem como unknown (needs root), o campo JSON needs_root as lista, e sudo ironflock status as lê.
# O que há nesta máquina, lido com o seu usuário de login
ironflock status
# Tudo, em JSON
sudo ironflock status --json
# O status de outra máquina via SSH
ironflock --host pi@device-17 statusSaída em texto
$ 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 é o projeto do dispositivo. Connection é unknown para um agente em execução: os agentes lançados até agora não informam a sua conexão na máquina.
No IronFlockOS
A linha do sistema mostra a imagem e os seus dois slots raiz (Slots raiz e a partição de dados):
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 BO agente de um dispositivo IronFlockOS é o que a imagem configurou quando o dispositivo se registrou, em /opt/ironflock/device-agent em /data, e é mostrado como em qualquer outro sistema. Um dispositivo que ainda não se registrou não tem agente; a imagem traz um, e a linha diz como o dispositivo se registra (primeira linha abaixo). Quando não foi possível montar /data nesta inicialização, a pasta do agente também não pode ser vista, com o dispositivo registrado ou não, e a linha diz isso (segunda linha):
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 missingAbaixo do sistema, uma linha para cada caso aparece apenas quando o IronFlockOS tem algo a dizer:
| Linha | Mostrada quando |
|---|---|
Last reset: | a última redefinição de fábrica falhou ou desistiu. os reset explica o que um registro significa |
Reset hold: | uma redefinição está aberta (wait: um .flock ou proxy.conf na partição IRONFLOCKOS não é aplicado enquanto os dados do proprietário anterior puderem estar em /data; copy: a redefinição começou a apagar), ou ela desistiu e não conseguiu remover o .flock e o proxy.conf que vieram com ela, que permanecem sem uso (gave-up) |
/data: | não foi possível montar /data: o dispositivo roda nas pastas próprias do slot raiz, sem o Docker e os apps |
/apps: | /apps não é a pasta da partição de dados: os apps rodam, mas perdem os seus dados na próxima atualização do sistema operacional |
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 updateUma tentativa de redefinição que falhou aparece como attempt 1 of 3 failed at <time>: <reason>; /data holds the old data; the next start tries again enquanto a retenção é wait ou copy, e diz no request is open now quando não há retenção. Sem root, o registro de redefinição mostrado é a cópia dele no slot em execução, pois a partição IRONFLOCKOS pertence ao root.
O último os install
Em qualquer Linux com variáveis EFI, uma linha OS install: mostra o que o último ironflock os install registrou na variável EFI IronFlockInstall da IronFlock, quando ela existe. Todo usuário pode ler a variável. Onde ela não pode ser lida, ou a máquina não tem variáveis EFI, não há linha nem aviso; um valor que não pode ser interpretado gera um aviso.
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| Etapa | A linha diz |
|---|---|
stopped | que ele parou antes de gravar o disco, o motivo, e que nada foi alterado |
handed-over | no sistema antigo: o instalador não rodou na reinicialização, e nada foi alterado. No IronFlockOS: ele gravou este sistema, mas não conseguiu registrar como a instalação terminou |
writing | ele começou a gravar o disco e não registrou que terminou |
done | no IronFlockOS: este sistema foi instalado pelo os install. Em outros sistemas: ele gravou o IronFlockOS em um disco da máquina, e o sistema em execução é outro |
failed | ele gravou o disco, e a releitura não confirmou o que ele gravou, com o motivo |
O registro nunca é apagado. A linha permanece até que o próximo os install o substitua e, em um dispositivo convertido, fica como a nota de que o sistema foi instalado dessa forma.
Resultado JSON
O --json escreve o mesmo como um único objeto JSON, mostrado aqui em várias linhas; o comando o escreve em uma linha.
{
"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": []
}Uma informação que não pode ser lida é unknown; quando o motivo não é a falta de root, um aviso no stderr diz por quê.
| Campo | Valores |
|---|---|
agent.installed | true quando há um agente instalado. Os campos de layout a update existem então, e somente então. No IronFlockOS, false significa que o dispositivo ainda não se registrou |
agent.unfinished_install | true: nenhum agente, mas uma instalação anterior parou antes de chegar ao agente; o agent install a desfaz primeiro. Ausente nos outros casos |
agent.layout | current (/opt/ironflock/device-agent), legacy (/opt/reagent, de um instalador anterior), migrating (o agente está movendo agora o layout legado para o atual) |
agent.dir | a pasta do agente |
agent.version | o que o binário do agente informa com -version |
agent.service | unit e state: running, starting, stopping, stopped, failed, not_found (o systemd não conhece a unit), unknown |
agent.connection | disconnected quando o agente não está rodando. A conexão de um agente em execução é unknown; connected vem de agentes que a informam |
agent.device, agent.swarm | o nome do dispositivo e o seu projeto, do .flock. Nada mais do .flock é lido |
agent.update | a última autoatualização. state: none (nada em andamento, nada falhou), activating, probation (a nova versão roda e precisa se conectar para se provar), rolled_back (falhou, a versão anterior roda de novo, a nova é tentada de novo mais tarde), blocked (falhou de vez; o agente espera uma release mais nova), unknown. Com version, previous_version, reason e updated_at |
appliance.installed | true quando o appliance IronFlock está instalado (a sua unit ironflock.service existe); então dir, version, channel, url, license, service, health e update existem |
appliance.data_left | apenas quando o appliance não está instalado e /opt/ironflock ainda guarda os seus dados, deixados pelo appliance remove sem --purge ou por uma instalação que parou: essa pasta |
appliance.version, appliance.channel | os arquivos VERSION e CHANNEL na pasta dele |
appliance.url | o endereço da sua UI: o HOME_URL do seu .env. Nada mais do .env, que guarda os seus segredos, é lido |
appliance.license | present quando o seu license.env contém uma chave de licença, missing quando não, invalid quando o seu LICENSE_KEY não é uma chave de licença (um UUID): todo comando do appliance ignora essa chave, e o texto diz isso. A chave nunca é mostrada |
appliance.service | ironflock.service, com os mesmos estados do agente. running significa que a unit iniciou os contêineres, não que cada um deles esteja saudável |
appliance.health | como estão os seus serviços, segundo o docker ps: state healthy (cada um roda e passa na sua verificação de saúde, ou não tem nenhuma, ou rodou uma vez e terminou com 0), starting (uma verificação de saúde está pendente), unhealthy, down (nenhum contêiner), unknown; services, quantos contêineres; problems, cada serviço que não está saudável, com o seu state (unhealthy, starting, restarting, exited com exit_code, …) |
appliance.update | uma atualização pendente, segundo o arquivo de status que a sua UI e o seu timer de nova tentativa escrevem: state none (nenhuma pedida, ou a última terminou), running, failed (o timer de nova tentativa a tenta de novo), unknown; com version, since e message. cut_short (só com root) indica a release cujos arquivos uma atualização incompleta guardou: a próxima atualização os coloca de volta primeiro. Nenhuma release é consultada |
appliance.ironflock | apenas quando o ironflock que as units do appliance executam a cada início (path, /usr/local/bin/ironflock) está missing ou older (state; version, o que ele informa) que o que instalou ou atualizou o appliance por último (installed). Só com root, e só para um appliance que o ironflock instalou. O texto tem então uma linha ironflock:, que diz o que instalar |
os.name, os.id, os.version | PRETTY_NAME, ID e VERSION_ID de /etc/os-release; em um Mac, macOS 15.5, macos, 15.5 |
os.ironflockos | true no IronFlockOS. Então os.version é o seu IMAGE_VERSION, e os campos abaixo vêm em seguida |
os.image, os.build | IMAGE_ID e BUILD_ID da imagem |
os.booted_slot, os.primary_slot | o slot a partir do qual o sistema roda e o slot que a próxima inicialização usa: A ou B |
os.slots | os slots raiz: name (A), rauc_slot (rootfs.0), state (booted, active, inactive), boot_status (good, bad), e version e installed_at da release que uma atualização instalou ali (ausentes para um slot gravado com a imagem). Ausente quando os slots não podem ser lidos |
os.last_reset | o registro da última redefinição de fábrica, apenas quando é failed ou gave-up: result, time, version, attempt, attempts_max, reason, data (old, new, none: o que /data contém agora) e, para gave-up, left (de data, booted-slot, other-slot: o que do proprietário anterior ainda pode estar lá) |
os.reset_hold | wait, copy ou gave-up, apenas enquanto há uma retenção de redefinição (veja a tabela acima) |
os.data_missing | true, apenas quando não foi possível montar /data |
os.install | o que o último os install registrou, em qualquer Linux com variáveis EFI, apenas quando o registro existe e pode ser lido: stage, time (RFC 3339, UTC) e reason (com stopped e failed) |
os.apps_not_persistent | true, apenas quando /apps não é a pasta da partição de dados |
needs_root | os campos que dizem unknown porque o comando não rodou como root, como agent.device e agent.swarm. Vazio quando nada ficou de fora |
Código de saída
O código de saída é 0 sempre que a visão geral é escrita, também quando ela mostra um agente parado, uma atualização revertida ou um slot ruim: o status informa e não julga, e um script lê os campos. Ele é 1 quando a visão geral não pode ser escrita. Para os outros códigos de saída, veja Códigos de saída.
ironflock doctor
Verifica se esta máquina pode executar o agente do dispositivo e se alcança os hosts com que o agente se comunica: o sistema, o systemd, o Docker, o espaço livre em disco, o relógio, o DNS, o proxy, o servidor de download e os hosts que o .flock do dispositivo indica.
ironflock doctor [flags]Roda em: Linux e macOS. Root: não necessário; uma verificação que não consegue examinar sem root fica skipped e diz isso. Pergunta: nada.
| Flag | Significado |
|---|---|
-c, --config <file> | o arquivo .flock do dispositivo, cujos hosts são verificados (padrão: o do agente instalado) |
O agent install executa estas verificações, todas exceto privileges e docker, antes de alterar qualquer coisa, e para quando system, systemd, disk_space ou download_tree falha.
# Verificar esta máquina, com o seu usuário de login
ironflock doctor
# Verificar tudo como root, em JSON
sudo ironflock doctor --json
# Verificar os hosts de um .flock antes de instalá-lo
ironflock doctor -c device.flockResultados
Cada verificação tem um id, um resultado e uma constatação de uma linha. Um resultado diferente de ok vem com uma dica que diz o que fazer.
| Resultado | Significado |
|---|---|
ok | nada a fazer |
warning | pode funcionar, mas não bem |
failed | o agente não pode ser instalado, ou não funciona, com a máquina como está |
skipped | a verificação não conseguiu examinar; a constatação diz por quê |
Verificações
As verificações, na ordem em que são mostradas. Uma verificação mantém o seu id; uma verificação nova recebe um id novo.
| Id | O que examina | Quando não é ok |
|---|---|---|
privileges | se o comando roda como root | warning sem root quando uma verificação não conseguiu examinar; a constatação indica essas verificações. Execute sudo ironflock doctor |
system | Linux baseado em Debian ou Ubuntu (a instalação obtém os seus pacotes do apt) ou IronFlockOS, e a arquitetura para a qual o agente é baixado | failed em outro sistema, warning em outro Linux com apt. O agent install para em failed |
systemd | o sistema roda com systemd (/run/systemd/system existe) | failed quando o sistema não roda com systemd; o agent install para nesse caso. warning enquanto o sistema está degraded: uma unit falhou |
docker | o Docker roda (docker info) | ok sem Docker, pois o agent install o instala, mas failed quando há um agente instalado. skipped sem root quando o usuário não está no grupo docker |
disk_space | o espaço livre para /opt/ironflock e para /var (Docker, apt, os logs) | failed abaixo de 128 MiB em /opt: uma instalação ou uma atualização do agente mantém o binário dele ali duas vezes. warning abaixo de 2 GiB em qualquer um dos dois |
clock | o relógio desta máquina comparado com o Date da resposta do servidor de download e, quando um cache guardou a resposta, com o Age dela | ok dentro de 10 s, warning até 5 minutos, failed acima disso: requisições assinadas e tokens de curta duração são recusados, e os dados dos apps ficam com a hora errada. Um relógio muito errado quebra o próprio TLS: failed, com a hora que a máquina tem. Veja Sincronização de horário (NTP) |
dns | os nomes que esta máquina resolve por conta própria: os hosts que ela alcança diretamente, e o proxy | um nome não é resolvido. Um host alcançado pelo proxy é resolvido pelo proxy |
proxy | o proxy pelo qual passam as verificações de rede, e de onde vem a configuração: o registro da instalação (/etc/ironflock/proxy.env), senão o ambiente | failed quando não é a URL de um proxy. skipped sem root quando o registro está no arquivo, que só o root lê |
download_tree | o agente no servidor de download que o agent install usa: o mapa de canais dele, como o agent install o lê (device-agent/manifest-v2.json, senão manifest.json), e o agente do canal de produção para esta arquitetura. Com o espelho de um appliance, o que o espelho não fornece é procurado na nuvem IronFlock, como o agent install o obtém: o agente inteiro quando o espelho não fornece mapa de canais, o arquivo do agente quando ele fornece o mapa sem o arquivo | failed quando não há agente para baixar, com o espelho do appliance quando nem o espelho nem a nuvem o têm; o agent install para nesse caso. Um erro do servidor (5xx) é um warning, assim como um agente que a nuvem fornece onde o espelho não fornece |
device_endpoint | o device_endpoint_url do .flock responde | sem resposta: é ali que o agente se conecta ao IronFlock |
docker_registry | o docker_registry_url do .flock responde (https://<host>/v2/; com uma porta, HTTP simples, como o registry de um appliance na LAN) | sem resposta: é dali que o dispositivo baixa as imagens dos seus apps |
update_server | o servidor de atualizações do agente tem o seu mapa de canais: o update_url do .flock (o espelho de um appliance), senão a nuvem IronFlock | sem resposta ou sem mapa de canais: é ali que o agente busca as suas atualizações |
O servidor de download é o que o agent install usa: --download-base, senão a variável de ambiente IRONFLOCK_DL_BASE, senão o espelho de downloads do appliance que o .flock indica (o seu update_url, quando ele não é um host da nuvem IronFlock), com a nuvem para o que o espelho não fornece, senão a nuvem IronFlock (De onde vem o agente). Os hosts que um dispositivo precisa alcançar estão listados em Requisitos de Rede.
Com e sem -c e root
As três últimas verificações precisam de um .flock: o de -c, senão o do agente instalado.
| Como root | Sem root | |
|---|---|---|
Sem -c | os hosts do .flock do agente instalado | as três últimas verificações ficam skipped: o .flock do agente instalado pertence só ao root |
Com -c | os hosts do .flock informado | os hosts do .flock informado |
Sem root, também docker fica skipped fora do grupo docker, e proxy fica skipped quando a instalação registrou o proxy. Uma verificação de rede cujo host não responde fica então também skipped (para dns, um nome que não é resolvido), pois ela pode obter uma resposta pelo proxy registrado. privileges indica cada verificação que não conseguiu examinar, e sudo ironflock doctor as executa.
Como as verificações de rede decidem
- Um host responde quando chega uma resposta HTTP, seja qual for o status. Um 502, 503 ou 504 a uma requisição HTTP simples pelo proxy não é resposta: o proxy o envia quando não consegue alcançar o host.
- Um certificado que o TLS recusa não é resposta. A única exceção é o certificado da CA própria de um appliance, quando o
.flockindica umappliance_domain: o agente confia nele. - As verificações passam pelo proxy da verificação
proxy, pelas regras deHTTPS_PROXY,HTTP_PROXYeNO_PROXYque os downloads seguem, também em cada requisição de um redirecionamento, e esperam 20 s por uma resposta. - Um host que uma entrada de
NO_PROXYmantém fora do proxy é acessado diretamente. Quando ele não responde assim, a constatação indica a entrada, por exemplo(directly: instance-registry.ironflock.com is in NO_PROXY), e a dica diz para remover a entrada, com oagent configure --no-proxyque faz isso quando a configuração é o registro da instalação.
Saída
$ 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.Com o espelho do appliance do .flock, a primeira linha diz isso:
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)Com --json, abreviado aqui e mostrado em várias linhas; o comando escreve uma linha.
{
"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 | Valores |
|---|---|
result | failed quando uma verificação falhou, warning quando uma emitiu um aviso, senão ok. Uma verificação pulada não faz nada falhar |
checks | as verificações, na ordem acima: id, result, finding e hint com todo resultado exceto ok |
download_base | o servidor de download verificado. Com o espelho do appliance, apenas o espelho; as constatações indicam a nuvem quando procuram ali |
flock | o .flock cujos hosts foram verificados; null quando não há nenhum |
Nenhuma saída mostra um segredo: de um .flock, as verificações leem apenas os hosts, e a senha de um proxy aparece como xxxxx.
Código de saída
O código de saída é 0 quando nenhuma verificação falhou; um aviso não causa falha. Ele é 1 quando uma verificação falhou: o resultado diz qual, nenhuma linha de erro vem depois dele e, com --json, o stdout tem o resultado, não um objeto de erro. Ele é 1, com um erro, quando o .flock de -c não pode ser lido. Para os outros códigos de saída, veja Códigos de saída.