Comandos do agente do dispositivo

Os comandos ironflock agent conectam uma máquina Linux ao IronFlock como dispositivo e cuidam do agente do dispositivo a partir daí. Com eles, você instala o agente, dá a ele outra configuração de dispositivo ou outro proxy, atualiza, para e inicia o agente, lê o log dele e o remove de novo.

O agente do dispositivo

O agente do dispositivo é o programa que conecta uma máquina ao IronFlock como dispositivo e executa no Docker os apps do projeto do dispositivo. O dispositivo que uma máquina se torna é definido pelo arquivo de configuração do dispositivo (.flock) que o IronFlock Studio fornece para cada dispositivo (Conectar Dispositivos).

Todo comando do agente precisa de root e roda no Linux. Sem root, ele termina com o código de saída 3 e não chama o sudo por conta própria (Privilégios de root). No macOS, os comandos do agente terminam com o código de saída 3 antes de examinar qualquer coisa; execute-os na máquina Linux, ou a partir do Mac com --host. Em um dispositivo IronFlockOS, a imagem traz o agente junto com o seu sistema: o agent install e o agent remove recusam ali, e o agent configure -c registra o dispositivo com outro .flock.

Cada comando também aceita as flags globais --yes, --json, --download-base, --host, --hosts e --parallel (Flags globais). Uma pergunta precisa de um terminal; sem ele, informe --yes (Perguntas e confirmação).

Com --host, um comando roda em outra máquina via SSH (Máquinas remotas via SSH). Em várias máquinas ao mesmo tempo (--host mais de uma vez, ou --hosts), o agent restart, o agent start e o agent logs rodam como estão, mas o agent logs --follow não roda com --json. O agent stop, o agent update, o agent configure e o agent remove precisam de --yes ali, pois ninguém é perguntado, e o agent configure não aceita -c, pois um .flock indica um único dispositivo. O agent install roda em uma máquina por vez.

Como é um agente instalado

O agente também escreve por conta própria algumas configurações do host, a cada início: a slice ironflock.slice em que roda, que reserva memória para ele, o watchdog do systemd, as configurações de crash do kernel e um limite para o tamanho do journal.

Uma máquina configurada por um instalador anterior da IronFlock ainda pode ter o agente no layout legado /opt/reagent (serviço reagent.service, log /var/log/reagent.log), que o agente move sozinho para /opt/ironflock/device-agent; o ironflock status mostra qual layout uma máquina tem, e as recusas abaixo indicam os casos em que isso importa.

ironflock agent install

Instala o agente do dispositivo em /opt/ironflock/device-agent, o Docker quando ele falta e as configurações padrão de host de um dispositivo, e conecta a máquina ao IronFlock como o dispositivo do .flock. O agente inicia imediatamente e, a partir daí, se atualiza sozinho.

ironflock agent install -c <device.flock> [flags]

Roda em: Linux baseado em Debian ou Ubuntu, com systemd; não no IronFlockOS. Root: necessário. Pergunta: antes de instalar os pacotes e o Docker, e para cada configuração padrão de host; --yes responde a cada pergunta com o seu padrão.

A máquina precisa de acesso à internet, ou ao servidor de download informado com --download-base (Base de download), ou ao espelho de downloads do appliance que o .flock indica (De onde vem o agente). Os hosts que um dispositivo precisa alcançar estão listados em Requisitos de Rede.

De onde vem o agente

O agente é o seu mapa de canais, o seu binário e os arquivos .sha256 e .sig do binário. O comando os obtém de:

1. --download-base, senão IRONFLOCK_DL_BASE: apenas desse servidor.
2. Senão, do espelho de downloads do appliance IronFlock que o .flock indica como servidor de atualizações (update_url), quando o host dele não é um da nuvem IronFlock. Uma máquina que alcança o appliance, mas não o ironflock.com, é instalada assim. Um .flock da nuvem IronFlock usa a nuvem.
3. Senão, da nuvem IronFlock, https://instance-registry.ironflock.com/dl.

O comando indica a base no stderr: Download base: ... (from the device's .flock), senão (from --download-base), (from IRONFLOCK_DL_BASE) ou (from default).

Com o espelho do appliance, os arquivos vêm primeiro do espelho e, quando o espelho não os fornece, do mesmo caminho abaixo da base de download da nuvem IronFlock:

• O mapa de canais — quando o espelho não fornece nenhum no momento (sem resposta, nenhum disponível, um status de erro), tudo vem da nuvem, e a versão é a que o mapa da nuvem indica. Um mapa que o espelho fornece e que é rejeitado (pela assinatura, sem versão) faz a instalação falhar, como com qualquer servidor.
• O binário, o seu .sha256 e o seu .sig — cada um que o espelho não fornece vem da nuvem. Quando os arquivos do espelho não passam nas verificações (checksum, assinatura), os três vêm da nuvem.

Cada fallback é uma linha Warning: ... no stderr, com o espelho, o arquivo e o motivo, e, com --json, uma entrada de warnings no resultado. Quando nem o espelho nem a nuvem fornecem um arquivo, a instalação falha com um único erro que indica as duas fontes e os dois motivos (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

O espelho é o servidor de atualizações do .flock, que não passa pelo proxy (Proxy). Um espelho HTTPS com um certificado da CA própria do appliance só funciona onde o sistema da máquina confia nessa CA. Os pacotes da distribuição e o Docker continuam vindo dos seus próprios servidores, e o install.sh e o ironflock, do ironflock.com; com --host, o ironflock vai do seu computador para a máquina.

Verificações antes da instalação

Antes de alterar qualquer coisa, o comando executa as verificações do ironflock doctor que dizem se ele pode ter sucesso: system, systemd, disk_space, clock, dns, proxy, download_tree, device_endpoint, docker_registry e update_server. Elas rodam para o .flock de -c, com a base de download e as flags de proxy da instalação.

Quatro delas param a instalação quando falham, porque a instalação então falharia com certeza ou no meio do caminho:

A mensagem indica a verificação, a constatação e a dica dela. Toda outra constatação é um aviso no stderr, e a instalação continua: o agente se conecta, se atualiza e baixa os seus apps assim que a rede permitir. Um resultado warning ou skipped nunca para a instalação. Execute ironflock doctor -c device.flock para ver todas as verificações antes de instalar.

Etapas

1. Indica os pacotes que instala e pergunta. Instala-os com o apt.
2. Instala o Docker quando a máquina não tem nenhum, e pergunta antes.
3. Baixa o agente do canal de produção e o verifica com o seu checksum e a sua assinatura. Uma instalação que não consegue obter um agente verificado para aqui, antes de qualquer uma das etapas seguintes.
4. Configura o Docker: o proxy, quando um é informado, e, para um Docker que esta instalação trouxe ou que ainda não guarda nada, o data-root na pasta do agente. Um Docker que guarda imagens ou contêineres mantém a sua configuração e os seus dados.
5. Aplica as configurações padrão de host (tabela abaixo). Cada uma é uma escolha no terminal; --yes aceita o padrão.
6. Instala o agente em /opt/ironflock/device-agent e o inicia.

A instalação também adiciona um banner de login. Tudo o que a instalação altera é escrito em /opt/ironflock/device-init/installed.json. Quando uma etapa a partir da etapa 4 falha, o erro diz que a tentativa está registrada e que o mesmo comando, executado de novo, a desfaz primeiro. Quando o comando encontra uma tentativa anterior assim, ele a desfaz depois que as verificações passaram: lista o que desfaz, pergunta e então instala de novo.

Proxy

As flags de proxy definem o proxy corporativo para os downloads da instalação, para o Docker e para o agente. Cada configuração vem da sua flag, senão das variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY (ou das suas formas em minúsculas).

Uma URL de proxy tem a forma http://proxy.example.com:3128; https:// e socks5:// também funcionam, e uma URL sem esquema é tratada como http://. Quando o proxy exige login, a URL indica o usuário sem a senha, http://[email protected]:3128, e --proxy-password-file fornece a senha. O comando coloca a senha nas URLs das flags que indicam um usuário.

Aviso: Nunca escreva a senha do proxy na URL. Linhas de comando aparecem no ps e no histórico do shell, por isso uma URL com senha é recusada como uma linha de comando incorreta, e o erro não a repete. Coloque a senha em uma linha de um arquivo, ou passe-a por um pipe com --proxy-password-file /dev/stdin (Segredos).

Além dos hosts de --no-proxy, estes não passam pelo proxy (NO_PROXY): localhost, 127.0.0.1 e ::1, e o servidor de download e o servidor de atualizações do .flock (o update_url dele) quando não são hosts da nuvem IronFlock, como um appliance ou um espelho na LAN. Os hosts da nuvem IronFlock (ironflock.com, ironflock.dev e os hosts abaixo deles, e storage.googleapis.com) estão na internet e passam pelo proxy.

A instalação escreve o proxy do Docker e do agente em /etc/ironflock/proxy.env, que só o root lê (modo 0600), e o Docker reinicia para usá-lo. Os drop-ins do systemd ironflock-proxy.conf de docker.service e de ironflock-device-agent.service indicam esse arquivo e não contêm nenhuma configuração própria, de modo que o systemctl show mostra a todos os usuários o nome do arquivo e nada do que ele contém. Um drop-in do Docker do próprio host (docker.service.d/http-proxy.conf) permanece; as configurações da IronFlock têm precedência sobre as suas linhas Environment=, e um aviso o indica. Um daemon.json com proxies os mantém, pois o Docker os usa antes de qualquer outra configuração.

Para alterar as configurações depois, use o agent configure. Para o proxy de todo o local, veja Atrás de um Proxy Corporativo.

Exemplos

# Instalar o agente; o comando pergunta antes de cada etapa
sudo ironflock agent install -c device.flock
# Instalar sem perguntas e impedir que o dispositivo entre em suspensão
sudo ironflock agent install -c device.flock --yes --disable-suspend
# Instalar atrás de um proxy que não exige login
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# Instalar atrás de um proxy com login; a senha vem de um arquivo
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

Resultado

$ sudo ironflock agent install -c device.flock --yes
Done: the IronFlock device agent runs (systemctl status ironflock-device-agent).
The device appears online in IronFlock within a minute.

{"action":"installed","device":"demo-device","agent_version":"1.6.9"}

warnings só aparece no resultado quando um arquivo veio da nuvem IronFlock em vez do espelho do appliance: uma entrada para cada um, como as linhas Warning: o dizem.

Quando recusa

Uma linha de comando incorreta termina com o código de saída 2 antes que qualquer coisa rode: uma URL de proxy com senha; uma URL de proxy que indica um usuário, sem --proxy-password-file; --proxy-password-file sem uma URL de proxy que indique um usuário; um valor que não é uma URL de proxy. Uma variável de proxy do ambiente que não é uma URL de proxy também conta; o erro indica a variável, não o seu valor.

O comando recusa com o código de saída 3, e não altera nada, quando:

• não roda como root, ou a máquina não é Linux;
• a máquina roda o IronFlockOS, antes de qualquer outra coisa, com root ou sem. A imagem traz o agente e o ironflock junto com o seu sistema, e cada atualização do sistema operacional substitui o sistema por inteiro. A mensagem diz que o dispositivo se registra com um .flock na sua partição IRONFLOCKOS na próxima inicialização, e que o agent configure -c o registra agora. No pen drive de instalação do IronFlockOS, ela diz que o pen drive não é um dispositivo;
• já há um agente instalado, também no layout legado /opt/reagent. A mensagem indica o agent configure e o agent remove;
• o agente está movendo a máquina para fora do layout legado;
• uma instalação anterior parou antes de o agente ser configurado, tinha movido o data-root do Docker, e o Docker guarda imagens ou contêineres desde então: desfazer essa tentativa os apagaria;
• uma das verificações system, systemd, disk_space ou download_tree falha. --yes não muda nada.

Uma pergunta respondida com não, ou uma pergunta sem terminal e sem --yes, encerra o comando com o código de saída 4. Uma etapa que falha o encerra com o código de saída 1.

ironflock agent configure

Altera o que a instalação configurou: o .flock do dispositivo, o proxy corporativo do Docker e do agente, ou ambos. Reinicia o que precisa usar a alteração.

ironflock agent configure [-c <device.flock>] [flags]

Roda em: Linux com um agente instalado; no IronFlockOS, apenas com -c. Root: necessário. Pergunta: antes de o Docker reiniciar para novas configurações de proxy; --yes responde.

Informe -c, uma flag de proxy, ou ambos. Sem nenhum dos dois, não há nada a alterar: uma linha de comando incorreta (código de saída 2).

Outro .flock

Com -c, o agente recebe o .flock informado e reinicia: a máquina se torna o dispositivo desse .flock. Os apps e os seus dados permanecem. Quando a instalação configurou um usuário SSH, o usuário SSH acompanha o .flock:

• Mesmo proprietário do projeto, outra chave de dispositivo — a chave antiga deixa de ser aceita, e a nova passa a ser.
• Outro proprietário do projeto — o novo proprietário recebe o seu usuário SSH, e o usuário SSH do primeiro proprietário é removido como o agent remove o remove: a regra do sudo, a chave e a conta com a sua pasta pessoal, quando a instalação a criou.
• Um .flock sem chave de dispositivo — o usuário SSH é removido, e nenhum outro é criado.

Quando o dispositivo muda de mãos, quem executa o comando pode ser o primeiro proprietário, via SSH com a própria conta que será removida, e remover uma conta encerra as suas sessões. Por isso, o comando trabalha nesta ordem: configura a conta do novo proprietário (usuário, chave, regra do sudo), reinicia o agente com o novo .flock e só então retira a regra do sudo, as sessões e a conta do primeiro proprietário (ou apenas a chave antiga, no caso do mesmo proprietário). O dispositivo tem uma nova forma de acesso, e está online, antes que a antiga seja removida. Antes que as sessões terminem, uma linha no stderr diz isso, por exemplo Removing the account anna, ...: a session of anna ends here.

• Quando o agente não reinicia com o novo .flock, o primeiro proprietário mantém o acesso: alguém precisa conseguir entrar.
• Quando apenas o usuário SSH do novo proprietário falhou, o acesso do primeiro proprietário é removido mesmo assim: o dispositivo mudou de mãos e está online.
• Os acessos que ainda faltam remover ficam registrados em /opt/ironflock/device-init/installed.json (users_to_remove). Cada agent configure -c e cada agent remove posterior tenta de novo.
• Uma conta que o novo .flock configura de novo nunca é removida (proprietário A, depois B, depois A).
• A partir da sua primeira alteração, um terminal ou uma sessão SSH perdidos não interrompem o comando.

Com --host, a cópia do .flock na máquina é removida assim que o comando a leu. Quando o usuário de login do --host é uma conta que será removida, a sessão SSH termina junto com a conta: a sua execução termina então com o código de saída 255, como depois de uma conexão perdida, e o comando na máquina continua até o fim. A pasta da execução ironflock.XXXXXXXXXX, com o seu binário, fica então na máquina; em uma pasta temporária, fica até que ela seja limpa; na pasta pessoal da conta, é removida junto com a conta.

No IronFlockOS

Com -c, o comando registra o dispositivo como o IronFlockOS o registra na primeira inicialização de cada novo slot raiz, tanto em um dispositivo que já se registrou quanto em um que ainda não. O .flock informado se torna a cópia do agente, /opt/ironflock/device-agent/device-config.flock em /data, e o dispositivo é configurado a partir dele nesta ordem: o usuário SSH do proprietário do projeto, o WiFi, o nome de host a partir do nome do dispositivo (a menos que /etc/ironflockos/enroll.conf diga hostname-from-flock=no), o agente, reiniciado com o novo .flock, e por fim a remoção do acesso do proprietário anterior.

A próxima atualização do sistema operacional faz o registro no seu novo slot raiz a partir da mesma cópia. O arquivo que você informou fica onde está. Uma etapa que falha não impede o agente de reiniciar com o novo .flock, mas o acesso do primeiro proprietário só é removido depois que o agente reiniciou. O comando termina então com o código de saída 1 e indica cada etapa que falhou; execute o mesmo comando de novo para repeti-las.

As flags de proxy são recusadas no IronFlockOS. O IronFlockOS mantém o proxy do Docker, do agente e do seu relógio em /etc/ironflockos/proxy.conf em /data, e um proxy.conf na sua partição IRONFLOCKOS o substitui na próxima inicialização.

Configurações de proxy

• Cada flag de proxy informada substitui a sua configuração, e as outras permanecem. --https-proxy sozinha altera o proxy HTTPS e mantém o proxy HTTP e os hosts que não passam por eles.
• A senha de --proxy-password-file vai para as URLs informadas que indicam um usuário. Sem URL informada, vai para as URLs das configurações do dispositivo que indicam um, de modo que uma nova senha é definida apenas com o arquivo.
• --no-proxy, e o primeiro proxy de um dispositivo que não tinha nenhum, também incluem localhost, 127.0.0.1, ::1 e o servidor de atualizações do .flock do agente quando ele não é um host da nuvem IronFlock (o de um appliance).
• --remove-proxy remove as configurações. Não aceita nenhuma outra flag de proxy.
• As variáveis de proxy do seu ambiente não alteram nada aqui: só as flags contam.

A lista de hosts que não passam pelo proxy fica como o comando a encontra, a menos que --no-proxy informe outra. Quando essa lista indica um host da nuvem IronFlock, um aviso o indica, com o agent configure --no-proxy que informa a lista sem ele. Um dispositivo que só alcança a internet pelo proxy não consegue atualizar o seu agente enquanto o servidor de download da nuvem, instance-registry.ironflock.com, estiver nessa lista.

As configurações ficam em /etc/ironflock/proxy.env, que só o root lê, e são indicadas pelos drop-ins ironflock-proxy.conf de docker.service e de ironflock-device-agent.service. Quando as configurações mudam, o comando as mostra antes e depois, sem a senha. Então o Docker e o agente reiniciam. O reinício do Docker interrompe os apps do dispositivo por um momento, então o comando diz isso e pergunta; --yes responde. Com a senha no stdin, não há terminal para perguntar: informe --yes.

• O Docker não reinicia, e nada é perguntado, quando o daemon.json do Docker define proxies (o Docker os usa antes destas configurações) e quando nada muda.
• Uma unit à qual falta apenas o seu drop-in o recebe, e só essa unit reinicia.
• Um drop-in do Docker do próprio host permanece como está. Outro drop-in do agente, ou do Docker, que define uma variável de proxy é indicado em um aviso; as configurações da IronFlock o substituem em cada variável que definem. Um drop-in ou daemon.json que contém uma senha de proxy que todo usuário pode ler também é indicado em um aviso.
• Quando o reinício do Docker falha, o agente reinicia mesmo assim, e vice-versa. O erro (código de saída 1) indica as units que ainda rodam com as configurações antigas e o systemctl restart que as aplica; uma segunda execução encontra as configurações no lugar e não reinicia nada.
• Quando as configurações não podem ser escritas, nada reinicia, e o erro diz para executar o comando de novo.

Configurações de proxy que uma instalação mais antiga escreveu em linhas Environment= de drop-ins http-proxy.conf, onde todo usuário pode lê-las com systemctl show, inclusive a senha, passam para /etc/ironflock/proxy.env com qualquer execução do agent configure, também uma só com -c. Nenhuma cópia dos arquivos antigos é mantida. Em geral, a migração mantém os valores, então não reinicia nada e não pergunta nada; onde ela altera o proxy que uma unit usa, o comando diz por quê, mostra o proxy dessa unit antes e depois, e pergunta. Um valor que o arquivo de configurações não consegue conter (uma aspa simples no host ou na lista de exceções do proxy, um caractere de controle) não é migrado: uma execução sem flags de proxy o deixa como está, emite um aviso e indica a flag que informa o valor de novo.

Exemplos

# Tornar esta máquina o dispositivo de outro .flock
sudo ironflock agent configure -c new-device.flock
# Definir um proxy HTTPS com login; a senha vem de um arquivo
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# Definir apenas uma nova senha de proxy, lida do stdin, sem pergunta
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# Remover as configurações de proxy: o Docker e o agente se conectam diretamente
sudo ironflock agent configure --remove-proxy

Resultado

$ sudo ironflock agent configure -c new-device.flock
Device configuration updated; the agent restarted.
$ sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
The proxy settings of Docker and the agent change:
  HTTP proxy:   none (unchanged)
  HTTPS proxy:  none -> http://[email protected]:3128 (with a password)
  No proxy for: localhost,127.0.0.1,::1
Docker restarts for the new settings: the apps of the device stop for a moment and start again.
? Continue? Yes
Proxy settings updated: HTTPS through http://[email protected]:3128 (with a password); not for localhost,127.0.0.1,::1.
Restarted: docker.service, ironflock-device-agent.service.

No IronFlockOS, com -c o comando informa o registro:

Device configuration updated: this device enrolled as new-device, as IronFlockOS enrolls it at every new root slot; the agent restarted.

{"action":"configured","device":"new-device","restarted":["ironflock-device-agent.service"]}

{"action":"configured","proxy":{"password":false,"changed":true,"moved":false},"restarted":["docker.service","ironflock-device-agent.service"]}

Quando recusa

Uma linha de comando incorreta termina com o código de saída 2: nada a alterar; --remove-proxy com outra flag de proxy; uma URL de proxy com senha; uma URL de proxy que indica um usuário, sem --proxy-password-file; --proxy-password-file com URLs das quais nenhuma indica um usuário; um valor que não é uma URL de proxy nem uma lista de hosts.

O comando recusa com o código de saída 3, e não altera nada, quando:

• nenhum agente está instalado (a mensagem indica o agent install), exceto no IronFlockOS, onde -c registra um dispositivo que ainda não se registrou;
• o agente está movendo a máquina para fora do layout legado;
• flags de proxy são informadas e o agente ainda roda no layout legado /opt/reagent. Depois que o agente moveu a máquina (o ironflock status mostra o layout), o mesmo comando funciona;
• flags de proxy são informadas no IronFlockOS, com -c ou sem;
• --no-proxy ou --proxy-password-file é informada sozinha em um dispositivo sem proxy, ou o arquivo de senha é informado sozinho quando nenhuma URL de proxy do dispositivo indica um usuário;
• as flags de proxy mantêm um valor da forma antiga que /etc/ironflock/proxy.env não consegue conter; a mensagem indica a flag que o informa de novo.

No IronFlockOS, o -c é recusado com o código de saída 3 quando o registro não manteria o .flock:

• uma redefinição de fábrica foi solicitada e ainda não começou (/boot/efi/factory-reset.conf, que o os reset escreve), ou já começou (/boot/efi/factory-reset.keep): a próxima inicialização apagaria o que o comando configura;
• uma redefinição de fábrica está aberta ou desistiu e retém os arquivos que vieram com ela (/run/ironflockos/factory-reset-hold; o ironflock status diz mais);
• não foi possível montar /data, então a cópia do agente iria parar no slot raiz. Nesse caso, o caminho é um .flock na partição IRONFLOCKOS;
• há um .flock na partição IRONFLOCKOS; o dispositivo se registra com ele na próxima inicialização, e a mensagem o indica;
• o comando roda no pen drive de instalação do IronFlockOS, que não é um dispositivo;
• o sistema não tem /usr/lib/ironflock/image.json, ou tem um agente no layout legado.

ironflock agent update

Faz o agente se atualizar para a release do seu canal e acompanha o que ele faz. O agente procura uma release mais nova a cada início: o comando o reinicia e informa o resultado. O dispositivo fica offline no IronFlock por um momento; os seus apps continuam rodando.

ironflock agent update [flags]

Roda em: Linux, com um agente instalado. Root: necessário. Pergunta: sim, depois de dizer o que o reinício faz; --yes responde.

O comando não tem flags próprias e não aceita versão. O agente segue o seu canal (production, ou test na plataforma de testes da IronFlock), a partir do seu servidor de atualizações: o update_url do seu .flock (o espelho de um appliance), senão a nuvem IronFlock. O --download-base não muda isso.

O que o agente faz, nesta ordem:

1. Lê a release do seu canal. Uma release que falhou duas vezes neste dispositivo não é baixada de novo até que saia uma mais nova.
2. Baixa uma release mais nova para a sua pasta e verifica a assinatura dela.
3. Coloca a nova versão no lugar e reinicia nela, 10 segundos depois do download. Ele adia a atualização quando a sua última conexão com o IronFlock foi entre 12 minutos e um dia atrás: uma atualização é ativada a partir de uma versão que comprovadamente se conecta.
4. A nova versão fica em período de prova: precisa se conectar ao IronFlock em até 10 minutos após o seu início e permanecer ativa por 2 minutos. Se não conseguir, ou parar três vezes antes disso, o agente volta para a versão anterior.
5. Depois de uma reversão, a versão anterior precisa se conectar. Nesse caso, a culpa era da nova versão: ela é tentada mais uma vez na próxima atualização e, depois da sua segunda falha, fica bloqueada até uma release mais nova. Quando a versão anterior também não consegue se conectar em até 10 minutos, o agente culpa a rede, e a nova versão é tentada de novo na próxima atualização.

O comando acompanha isso em update-state.json, na pasta do agente, e no log do agente; não lê nenhum dos dois de antes do reinício. O seu progresso vai para o stderr como linhas de texto, também com --json. Um download mostra uma vez por minuto quanto já baixou.

Com o código de saída 1, o resultado é escrito mesmo assim, e o stderr recebe a linha Error:. Com --json, nenhum objeto de erro vem em seguida: o stdout tem o resultado.

Exemplos

# Atualizar o agente; o comando pergunta antes do reinício
sudo ironflock agent update
# Atualizar sem pergunta e ler o resultado como JSON
sudo ironflock agent update --yes --json

Resultado

$ sudo ironflock agent update --yes
The agent 1.6.9 restarts now and looks for a newer release on its channel: the device is offline in IronFlock for a moment, its apps keep running.
A newer release is downloaded and started. It has to connect to IronFlock within 10 minutes and stay up for 2, or the agent goes back to 1.6.9.
The agent restarted; it looks for a newer release.
Its channel offers 1.7.0: the agent downloads it.
Activating 1.7.0: the agent restarts into it.
1.7.0 runs on probation: it has to connect to IronFlock within 10 minutes and stay up for 2.
The agent was updated from 1.6.9 to 1.7.0: 1.7.0 connected to IronFlock and passed its probation.

Um agente que está atualizado, e um cuja nova versão foi revertida:

{"outcome":"current","version":"1.7.0","channel_version":"1.7.0"}

{"outcome":"rolled_back","version":"1.6.9","channel_version":"1.7.0","failed_version":"1.7.0","reason":"did not connect within 10m0s","retry":"next_update"}

Quando recusa

O comando recusa com o código de saída 3 quando nenhum agente está instalado (a mensagem indica o agent install), enquanto o agente move a máquina para fora do layout legado, quando o agente roda no layout legado (as atualizações dele não guardam nenhum estado que o comando possa acompanhar) e com um agente anterior à versão 1.3.0, a primeira que se atualiza sob a sua unit.

Ele falha com o código de saída 1, e com um erro que diz onde olhar, quando o reinício falha e quando a atualização não avança dentro dos prazos do agente: a verificação do agente em até 3 minutos após o reinício, o download em até 30 minutos, a ativação em até 3 minutos, cada início da nova versão em período de prova em até 12 minutos, o julgamento do agente após uma reversão em até 12 minutos, e tudo isso em até 84 minutos. O agente continua sozinho; o ironflock status mostra em que ponto ele está.

Ctrl-C interrompe o acompanhamento, não a atualização, e encerra o comando com o código de saída 130.

ironflock agent remove

Remove o agente do dispositivo e desfaz o que a instalação dele registrou. O próprio Docker e os pacotes continuam instalados.

ironflock agent remove [flags]

Roda em: Linux, com um agente instalado; não no IronFlockOS. Root: necessário. Pergunta: sim, depois de listar o que remove. A pergunta vem com “No” pré-selecionado: Enter sozinho não remove nada.

O comando não tem flags próprias. Ele remove:

• O agente — o agente, o seu banco de dados e /opt/ironflock/device-agent. Os apps do dispositivo e os seus dados vão junto quando o Docker os mantém na pasta do agente.
• O usuário SSH — a conta, apenas quando a instalação a criou. De uma conta que já existia, é removida apenas a chave do dispositivo do seu authorized_keys, que continua sendo do usuário. O acesso de um proprietário de projeto anterior cuja remoção pelo agent configure -c tinha falhado também é removido, listado com “(a removal that had failed)”.
• As configurações padrão de host — o perfil de WiFi, o banner de login e os targets de suspensão mascarados.
• Os arquivos que a instalação escreveu ou substituiu — os originais voltam, com o seu modo, dono e grupo.
• As configurações de proxy — /etc/ironflock/proxy.env com os drop-ins que o indicam, e as configurações de proxy que uma instalação mais antiga deixou em drop-ins http-proxy.conf. Nada volta no lugar delas: depois disso, o Docker não tem proxy da IronFlock, e o comando não escreveu a senha do proxy em lugar nenhum. Quando o Docker tinha um proxy da IronFlock, a lista antes da pergunta diz isso.
• As configurações que o agente escreveu no host por conta própria — a slice ironflock.slice com o drop-in 10-ironflock-resources.conf da sua unit, o watchdog do systemd (/etc/systemd/system.conf.d/10-ironflock-watchdog.conf), as configurações de crash do kernel (/etc/sysctl.d/60-ironflock-crash-recovery.conf, que o kernel mantém até a próxima inicialização) e o limite do journal (/etc/systemd/journald.conf.d/10-ironflock.conf).
• Os logins de registry do agente — depois que o agente parou, o comando executa docker logout para o registry que o .flock indica (docker_registry_url) e, em um dispositivo de um appliance, para registry.<appliance_domain>. Nenhum outro login em /root/.docker/config.json é tocado. Um Docker ausente ou que falha não interrompe a remoção; uma linha diz qual login não foi removido.

Um drop-in do Docker do próprio host permanece como está. Um Docker que não reinicia para a remoção (os dados dele não estavam na pasta do agente) usa o proxy com que iniciou até o seu próximo reinício.

O comando lista no stderr o que remove e depois pergunta. Com --json, a lista é o campo removed do resultado. Depois que o comando começou a remover, um terminal ou uma sessão SSH perdidos não o interrompem: o usuário SSH removido leva junto as suas sessões, talvez a que executa o comando, e a remoção continua até o fim.

Exemplos

# Remover o agente; o comando lista o que será removido e pergunta
sudo ironflock agent remove
# Remover o agente sem pergunta
sudo ironflock agent remove --yes

Resultado

$ sudo ironflock agent remove --yes
This removes:
  - the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)
  - the user operator and its home directory
  - /etc/profile.d/ironflock-motd.sh
The IronFlock device agent was removed from this machine.

{"action":"removed","removed":["the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)","the user operator and its home directory","/etc/profile.d/ironflock-motd.sh"]}

Quando recusa

O comando recusa com o código de saída 3 quando nenhum agente está instalado e enquanto o agente move a máquina para fora do layout legado. No IronFlockOS, ele recusa antes de qualquer outra coisa, com root ou sem: a imagem traz o agente junto com o seu sistema, e cada atualização do sistema operacional e o próximo registro o configurariam de novo. A mensagem indica o ironflock os reset, que devolve o dispositivo a um IronFlockOS recém-gravado, sem a sua identidade no IronFlock. No pen drive de instalação do IronFlockOS, ela diz que o pen drive não é um dispositivo.

A resposta não, ou uma pergunta sem terminal e sem --yes, encerra o comando com o código de saída 4.

ironflock agent restart

Reinicia o serviço do agente e verifica se o agente volta a rodar: a unit dele precisa rodar por cinco segundos com um processo. O dispositivo fica offline no IronFlock durante esses segundos; os apps continuam rodando.

ironflock agent restart [flags]

Roda em: Linux, com um agente instalado. Root: necessário. Pergunta: nada.

O comando não tem flags próprias. O serviço é ironflock-device-agent.service. Executado em um terminal que passa pelo agente (o terminal do dispositivo no IronFlock Studio, ou SSH pelo IronFlock), o reinício encerra essa sessão; o dispositivo volta em até um minuto.

# Reiniciar o agente
sudo ironflock agent restart
# Reiniciá-lo e ler o novo processo como JSON
sudo ironflock agent restart --json

$ sudo ironflock agent restart
The agent restarted: ironflock-device-agent.service runs, with process 4242.

{"action":"restarted","unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

state é o estado da unit depois disso, com os nomes usados em ironflock status. main_pid é o processo do agente, um novo depois de cada reinício.

Recusa com o código de saída 3 quando nenhum agente está instalado (a mensagem indica agent install -c <file>), enquanto o agente move a máquina para fora do layout legado e quando o systemd não conhece a unit do agente (a mensagem indica o agent remove).

Falha com o código de saída 1 quando o agente não sobe: o systemd não consegue iniciar a unit, ou o processo dela termina dentro dos cinco segundos. O erro indica a unit e onde estão as suas últimas linhas de log: o log do agente (agent logs) e o journal (journalctl -u <unit>).

ironflock agent stop

Para o serviço do agente. O dispositivo fica offline no IronFlock, e o acesso remoto pelo IronFlock para junto com o agente: uma sessão que veio por esse caminho (o terminal do dispositivo no IronFlock Studio, SSH pelo IronFlock) termina, e o IronFlock não consegue alcançar o dispositivo até que o agente rode de novo. Os apps continuam rodando, pois quem os executa é o Docker, não o agente.

ironflock agent stop [flags]

Roda em: Linux, com um agente instalado. Root: necessário. Pergunta: sim, depois de dizer o que a parada do agente encerra; --yes responde.

O comando não tem flags próprias. O agent start inicia o agente de novo, assim como a próxima inicialização. Um agente parado não pode ser iniciado de novo pelo IronFlock. Um agente que não está rodando não tem nada a parar; nesse caso, o comando não pergunta nada, e o resultado não tem action.

# Parar o agente; o comando diz o que isso encerra e pergunta
sudo ironflock agent stop
# Pará-lo sem pergunta
sudo ironflock agent stop --yes

$ sudo ironflock agent stop --yes
Stopping the agent (ironflock-device-agent.service) takes this device offline in IronFlock.
The remote access through IronFlock goes with it: a session that came that way (the device's terminal in Studio, SSH through IronFlock) ends.
The apps keep running. 'sudo ironflock agent start' starts the agent again, and so does the next boot.
The agent is stopped (ironflock-device-agent.service): the device is offline in IronFlock, and its apps keep running. 'sudo ironflock agent start' starts the agent again.

{"action":"stopped","unit":"ironflock-device-agent.service","state":"stopped"}

Recusa com o código de saída 3 como o agent restart. A resposta não, ou uma pergunta sem terminal e sem --yes, o encerra com o código de saída 4.

ironflock agent start

Inicia o serviço do agente quando ele não está rodando e verifica se o agente sobe, como o agent restart: a unit dele precisa rodar por cinco segundos com um processo. Um agente que já está rodando fica como está, e o resultado então não tem action.

ironflock agent start [flags]

Roda em: Linux, com um agente instalado. Root: necessário. Pergunta: nada. O comando não tem flags próprias.

# Iniciar o agente
sudo ironflock agent start
# Iniciá-lo e ler o seu processo como JSON
sudo ironflock agent start --json

$ sudo ironflock agent start
The agent started: ironflock-device-agent.service runs, with process 4242. The device appears online in IronFlock within a minute.

Com --json, para um agente que já está rodando:

{"unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

Recusa e falha como o agent restart: código de saída 3 quando nenhum agente está instalado, enquanto o agente move a máquina para fora do layout legado e quando o systemd não conhece a unit do agente; código de saída 1 quando o agente não sobe.

ironflock agent logs

Mostra o log do agente, /var/log/ironflock/device-agent.log, e os arquivos para os quais o agente o rotacionou. Não altera nada.

ironflock agent logs [flags]

Roda em: Linux, com um agente instalado; lê os arquivos e não precisa do systemd. Root: necessário, pois o agente escreve o seu log só para o root (modo 0600). Pergunta: nada.

Com 100 MB, o agente renomeia o seu log para device-agent-<time>.log na mesma pasta e começa um novo; ele mantém dois. O comando lê o log e esses arquivos.

O agente escreve um objeto JSON por linha: o horário da entrada (com precisão de segundos), o seu nível, a sua mensagem e outros campos. A forma em texto mostra uma entrada como o IronFlock Studio mostra o log do agente: o horário em UTC, o nível, a mensagem e o seu erro. Uma linha que não é uma entrada, como o stack trace de uma falha, é mostrada como está. Caracteres de controle são escapados (\n, \x1b), de modo que uma entrada ocupa uma linha no terminal e não consegue controlá-lo. Com --json, cada linha é um objeto JSON no stdout: a entrada como o agente a escreveu, com todos os seus campos, ou {"message":...} para uma linha que não é uma entrada.

• --since começa pela primeira entrada desse momento ou posterior. As linhas ficam na ordem em que o agente as escreveu. Uma linha sem horário pertence à entrada anterior.
• Com --follow, uma linha é mostrada assim que está completa. Quando o agente começa um novo arquivo, o resto do antigo vem primeiro, depois o novo desde o início. Um log que ainda não existe é aguardado. Ctrl-C encerra o comando com o código de saída 0; com --host, Ctrl-C encerra a execução com o código de saída 130.
• Quando o agente ainda não escreveu nenhum log, o stderr diz isso, o stdout fica vazio e o código de saída é 0.

Exemplos

# As últimas 100 linhas
sudo ironflock agent logs
# Tudo da última hora
sudo ironflock agent logs --since 1h
# As últimas 20 linhas, depois cada nova linha até Ctrl-C
sudo ironflock agent logs --follow --lines 20
# Os últimos dez minutos como JSON, um objeto por linha
sudo ironflock agent logs --since 10m --json

Resultado

$ sudo ironflock agent logs --lines 3
2026-11-10T11:58:02Z INFO connected to IronFlock
2026-11-10T11:58:03Z INFO 3 apps running
2026-11-10T11:59:40Z ERROR pulling demo-app:1.2 failed: context deadline exceeded

{"level":"info","time":"2026-11-10T11:58:02Z","caller":"agent.go:212","message":"connected to IronFlock"}

Quando recusa

Um --since que não é nem uma duração nem um horário, uma duração negativa e um --lines que não é nem um número nem all são linhas de comando incorretas (código de saída 2). O comando recusa com o código de saída 3 quando não roda como root e quando nenhum agente está instalado (a mensagem indica agent install -c <file>).