Atualizar, reverter e redefinir

Estes comandos cuidam de um dispositivo que roda o IronFlockOS. O os update instala uma release, o os rollback volta para a release que rodava antes, e o os reset torna o dispositivo novamente um dispositivo recém-gravado.

Slots raiz e a partição de dados

O disco de um dispositivo IronFlockOS contém:

• Dois slots raiz, A e B — cada um contém um sistema IronFlockOS completo. Um deles roda. O outro contém o sistema que rodava antes ou, em um dispositivo recém-gravado, ainda nada. O RAUC, a ferramenta de atualização que o IronFlockOS usa, grava uma release no slot que não está rodando e registra qual slot inicia em seguida.
• A partição de dados (/data) — os apps e os seus dados, e o agente do dispositivo com a sua cópia do arquivo de configuração do dispositivo (.flock). Os dois sistemas a usam, então uma atualização ou uma reversão deixa os apps e os seus dados como estão.
• A partição IRONFLOCKOS (montada em /boot/efi) — uma pequena partição FAT. O dispositivo se registra com um arquivo .flock que encontra ali ao iniciar, e o os reset escreve ali a sua solicitação.

Um novo sistema precisa se provar: o dispositivo o mantém depois que o agente do dispositivo alcançou o IronFlock a partir dele e o marcou como bom. Um sistema que não inicia, ou não chega a isso, é abandonado na próxima reinicialização em favor do que rodava antes. O ironflock status mostra os slots:

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

Onde os comandos rodam

Os três comandos rodam em um dispositivo que roda o IronFlockOS, precisam de root e perguntam antes de agir. Em outro sistema (macOS, um Linux que não é IronFlockOS, o pen drive de instalação do IronFlockOS), eles terminam com o código de saída 3.

• No dispositivo — as releases do IronFlockOS posteriores à 0.15.0 trazem o ironflock. Faça login no dispositivo e execute o comando com sudo.
• A partir de outro computador — as releases do IronFlockOS até a 0.15.0 não trazem o ironflock. Execute o comando a partir de um computador Linux ou macOS com --host, como o usuário SSH do dispositivo: a conta que o arquivo .flock configura para o proprietário do projeto, operator nos exemplos. O --host copia o ironflock para o dispositivo durante a execução e executa o comando lá via sudo.

ironflock --host operator@kitchen-pc os update --reboot --yes

O os update e o os rollback rodam em vários dispositivos ao mesmo tempo (--host mais de uma vez, ou --hosts) quando --yes é informado. O os reset roda em um dispositivo por vez; em vários, termina com o código de saída 2. As flags globais estão em Flags, saída e códigos de saída.

ironflock os update

Instala no slot raiz que não está rodando a release do IronFlockOS que o canal do dispositivo oferece. O novo sistema inicia na próxima reinicialização, ou imediatamente com --reboot.

ironflock os update [flags]

O canal do dispositivo é o que o agente do dispositivo segue, a partir do environment do arquivo .flock do agente: test na plataforma de testes da IronFlock e production nos outros casos. Quando o catálogo não tem o canal do dispositivo, ele é production. A base de download vem de --download-base, depois de IRONFLOCK_DL_BASE, depois do servidor de atualizações (update_url) do arquivo .flock do agente (em um dispositivo de um appliance IronFlock, o espelho de download do appliance, que é tudo o que um dispositivo assim pode alcançar); caso contrário, é a nuvem IronFlock.

O que ele faz, nesta ordem:

1. Lê o catálogo assinado do IronFlockOS e pega o pacote de atualização da imagem do dispositivo na release do canal (ou de --version).
2. Diz qual release roda em qual slot, qual release ele instala, em qual slot, o que esse slot contém agora e o tamanho do download. Então pergunta.
3. Baixa o pacote para /var/cache/ironflockos, na partição de dados. Um download interrompido é retomado. O arquivo só é usado quando o seu tamanho e o seu SHA-256 são os do catálogo.
4. Faz o RAUC instalar o pacote no slot que não está rodando. O RAUC verifica a assinatura do pacote, grava o slot e o torna o slot que inicia em seguida. O que o slot continha antes é sobrescrito. O pacote é removido depois de instalado.
5. Com --reboot, reinicia o dispositivo no novo sistema.

O sistema em execução fica como está até a reinicialização. Os apps e os seus dados permanecem. O slot que roda agora mantém a sua release, e o dispositivo volta para ele quando a nova release não inicia ou não alcança o IronFlock.

Nada é instalado, e o código de saída é 0, quando o dispositivo já roda a release e quando a release já está instalada no outro slot e espera a reinicialização. No segundo caso, --reboot pergunta e reinicia o dispositivo.

# Instalar a release do canal do dispositivo; ela inicia na próxima reinicialização
sudo ironflock os update
# Instalá-la e reiniciar nela, sem pergunta
sudo ironflock os update --reboot --yes
# Instalar uma release mais antiga do catálogo
sudo ironflock os update --version 0.13.0

O progresso vai para o stderr: o download e a sua verificação, depois cada etapa que o RAUC indica. O que o os update --yes imprime em um dispositivo que roda a 0.13.0 no slot A:

Download base: https://instance-registry.ironflock.com/dl (from default)
IronFlockOS catalog of 2026-11-20T09:00:00Z, signed with key 036ef3bd: production 0.14.0, test 0.14.0.
This device runs IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) from slot A.
IronFlockOS 0.14.0, the release of the production channel, is installed into slot B, which holds nothing yet:
  - the bundle (580.2 MB) is downloaded into /var/cache/ironflockos
  - RAUC checks its signature and writes it into slot B
  - it starts with the next restart
Slot A keeps IronFlockOS 0.13.0: the device goes back to it when 0.14.0 does not start or does not reach IronFlock. Apps and their data stay.
Downloading: 0% (0 B of 580.2 MB)
...
Installing IronFlockOS 0.14.0 into slot B.
Installing:   0% Installing
...
Installing:  82% Copying image to rootfs.1
...
Installing: 100% Installing done.
IronFlockOS 0.14.0, the release of the production channel, is installed in slot B and starts with the next restart ('sudo reboot').

Com --json, a instalação é a fase de progresso installing, em porcentagem. O resultado de os update --reboot --yes --json:

{"action":"installed","image":"ironflockos-amd64-efi-base","channel":"production","version":"0.14.0","running_version":"0.13.0","slot":"B","up_to_date":false,"reboot":true}

Recusa quando, com o código de saída 3:

• não roda como root, em uma máquina que não roda o IronFlockOS e no pen drive de instalação.
• o RAUC já está instalando um pacote, iniciado pelo IronFlock Studio por meio do agente ou por outra chamada. O RAUC instala um por vez.
• a release não tem pacote para a imagem do dispositivo.
• a release é mais antiga que a que está rodando, a menos que --version a indique. Quando o outro slot contém essa release, a mensagem indica o os rollback.
• /var/cache/ironflockos não tem espaço para o que ainda falta baixar. A mensagem lista os pacotes de atualizações anteriores na pasta, que você pode apagar.

Linhas de comando incorretas, código de saída 2: --channel e --version juntas, uma versão em formato inválido, um canal ou uma release que o catálogo não tem.

Falha quando, com o código de saída 1: o catálogo não passa na verificação ou não pode ser lido; o download é interrompido (o que chegou fica em /var/cache/ironflockos, e o mesmo comando o retoma); o download não é o arquivo do catálogo; o RAUC recusa o pacote ou não consegue instalá-lo. O erro dá o motivo do RAUC. Quando o RAUC já tinha começado a gravar, o slot é marcado como ruim e não contém nenhum sistema utilizável, e o dispositivo continua iniciando o sistema que está rodando. O pacote fica no cache para a próxima tentativa.

Ctrl-C durante o download, ou logo depois dele, encerra o comando com o código de saída 130 antes que qualquer coisa seja instalada ou reiniciada; o mesmo comando retoma o download. Uma pergunta respondida com não encerra o comando com o código de saída 4.

ironflock os rollback

Torna o outro slot raiz o slot que inicia e reinicia o dispositivo nele: de volta ao sistema que rodava antes da última atualização. Use-o para um sistema que inicia, mas se comporta mal. Um sistema que não inicia, ou não alcança o IronFlock, é abandonado pelo próprio IronFlockOS na próxima reinicialização.

ironflock os rollback [flags]

O comando não tem flags próprias. Ele sempre reinicia o dispositivo: uma reversão sem a reinicialização não mudaria nada até a próxima.

Só serve um slot cujo sistema iniciou neste dispositivo:

• um slot cujo sistema foi marcado como bom enquanto rodava e não foi testado de novo desde então. Um slot que foi testado e nunca marcado como bom não serve.
• o slot com o qual o dispositivo foi gravado (A), desde que nada tenha sido instalado nele e ele não tenha sido marcado como ruim.

Os apps e os seus dados permanecem, pois os dois sistemas usam a mesma partição de dados. O slot que rodava mantém a sua release. Depois da reinicialização, o sistema mais antigo precisa se provar de novo: o dispositivo o mantém depois que o agente do dispositivo alcançou o IronFlock a partir dele. Em uma máquina UEFI, um slot que já fez isso antes também é mantido depois de ficar ativo por dois minutos. Até lá, uma reinicialização pode trazer de volta o sistema mais novo. O IronFlock Studio oferece de novo a release do canal, e o os update a instala.

# Voltar para o sistema do outro slot, depois de uma pergunta
sudo ironflock os rollback
# Sem pergunta
sudo ironflock os rollback --yes

O que o os rollback --yes imprime em um dispositivo que roda a 0.14.0 no slot B:

This device runs IronFlockOS 0.14.0 from slot B.
Slot A holds IronFlockOS 0.13.0, which ran on this device before. The rollback makes slot A the one that starts and restarts the device now.
Slot B keeps IronFlockOS 0.14.0. Apps and their data stay: both systems use the same data partition.
The device keeps IronFlockOS 0.13.0 once it has proven itself again (the device agent reaches IronFlock from it); until then a restart can bring back 0.14.0.
Rolled back to IronFlockOS 0.13.0 in slot A: the device restarts now.

Com --json, slot e version são o slot que inicia e a sua release (vazio quando não pode ser lida), e from_slot e from_version, o sistema que rodava:

{"action":"rolled_back","slot":"A","version":"0.13.0","from_slot":"B","from_version":"0.14.0"}

Recusa quando, com o código de saída 3, e diz por quê:

• não roda como root, em uma máquina que não roda o IronFlockOS, no pen drive de instalação, e enquanto o RAUC instala um pacote.
• o dispositivo tem um bootloader que o comando não conhece: ele conhece o GRUB (máquinas UEFI) e o do Raspberry Pi.
• o outro slot ainda não contém nada (um dispositivo recém-gravado), contém um sistema que foi testado e não marcado como bom, não contém nenhum sistema utilizável porque a sua instalação não terminou, ou está marcado como ruim.
• o outro slot espera a próxima reinicialização, depois de uma atualização que foi instalada ou de uma reversão que não reiniciou. sudo reboot o inicia, e sudo rauc status mark-bad other o descarta.

Falha quando, com o código de saída 1: o RAUC não consegue tornar o slot o que inicia (nada foi alterado); a reinicialização falha (o slot então inicia na próxima reinicialização). Uma pergunta respondida com não encerra o comando com o código de saída 4.

ironflock os reset

Solicita a redefinição de fábrica do IronFlockOS e reinicia o dispositivo. Durante a próxima inicialização, o dispositivo limpa o que o seu proprietário, os seus apps e o registro deixaram, e inicia como um dispositivo recém-gravado; com -c, ele se registra como o dispositivo de um novo arquivo .flock.

ironflock os reset [-c <new.flock>] [flags]

O IronFlockOS 0.15.0 é a primeira release com a redefinição de fábrica. Em uma release mais antiga, o comando recusa; o os update instala uma mais nova.

A redefinição limpa, na partição de dados e nos dois slots raiz:

• os apps com os seus dados, e os contêineres, as imagens e os volumes do Docker.
• a identidade do dispositivo no IronFlock: o agente do dispositivo com a sua cópia do arquivo .flock, o seu banco de dados e o seu serviço. O nome de host volta a ser ironflockos, e o machine ID é gerado de novo.
• o usuário SSH e todas as outras contas de usuário, com as suas pastas pessoais e regras do sudo.
• os logs, as chaves de host SSH, as atualizações baixadas e o ajuste de tempo real.
• sem --keep-network: os perfis de rede (entre eles o WiFi), a configuração de proxy (proxy.conf) e a configuração de PTP (ptp.conf).

Ela mantém os sistemas IronFlockOS nos slots raiz, o que está rodando e o outro, quando ele contém um sistema, e o registro do RAUC sobre eles, de modo que as atualizações e as reversões funcionam como antes. Com --keep-network, ela também mantém as configurações de rede acima. Ela não desfaz o que foi alterado manualmente no próprio sistema, como um pacote ou um arquivo em /etc; gravar o IronFlockOS no disco de novo com o os flash desfaz.

O que ele faz, nesta ordem:

1. Recusa o que o dispositivo não faria como solicitado (abaixo) e verifica o arquivo .flock de -c: um arquivo com nome *.flock de no máximo 5 MiB, um objeto JSON com um secret e um device_key, cujos name e serial_number são nomes simples.
2. Diz no stderr o que é removido, o que fica, como o dispositivo volta e o que a sua última redefinição fez, depois pede que você digite o nome do dispositivo: o nome dele no arquivo .flock do agente, como o ironflock status o mostra, ou o nome de host de um dispositivo que não está registrado. Qualquer outra coisa, inclusive Enter sozinho, responde não.
3. Escreve a solicitação na partição IRONFLOCKOS, depois que a verificação do próprio dispositivo a aceitou. Uma solicitação que já está lá é substituída; esta é uma nova solicitação, com três tentativas próprias.
4. Com -c, remove da partição todos os outros arquivos .flock, porque o dispositivo se registra com o mais novo, e escreve ali o novo arquivo .flock. Quando isso falha, a solicitação é removida de novo.
5. Reinicia o dispositivo. Durante a próxima inicialização, o dispositivo se redefine, em segundos (minutos em um cartão SD lento), reinicia mais uma vez e inicia como um dispositivo recém-gravado, com novas chaves de host SSH.

Depois da redefinição, com -c, o dispositivo se registra como o dispositivo desse arquivo .flock e pode ser alcançado via SSH como o usuário SSH dele. Sem -c, ele espera por um arquivo .flock na sua partição IRONFLOCKOS e só pode ser alcançado pelo seu console: ele não tem usuário SSH nem conexão com o IronFlock. Uma conexão SSH com o dispositivo, também a do --host, termina com a reinicialização; sem -c, nenhuma volta.

Nota: Se você só alcança o dispositivo pela rede, informe o novo arquivo .flock com -c. Sem ele, alguém precisa estar junto ao dispositivo para colocá-lo online de novo.

Uma tentativa que falha não reinicia o dispositivo: ele sobe como está, e a sua próxima inicialização, por uma pessoa ou por uma atualização, tenta de novo. Depois de três tentativas que falharam, a redefinição desiste, e o dispositivo inicia com o que está lá. Com os seus dados antigos, ele continua sendo o dispositivo que era, online com a sua identidade antiga, e o arquivo .flock e a configuração de proxy que vieram com a solicitação são removidos. Uma solicitação que terminou, concluída ou abandonada, nunca dispara de novo, em nenhum slot e depois de nenhuma atualização. Um disco que não responde pode prender uma tentativa por até 25 minutos. O ironflock status mostra uma redefinição que falhou ou desistiu na sua linha Last reset:.

Antes de perguntar, o comando mostra a última redefinição que o dispositivo registrou:

# Redefinir o dispositivo; depois ele espera por um arquivo .flock
sudo ironflock os reset
# Redefini-lo e torná-lo o dispositivo de new-device.flock
sudo ironflock os reset -c new-device.flock
# Manter as configurações de rede, sem pergunta
sudo ironflock os reset --keep-network --yes
# A partir de outro computador, no IronFlockOS 0.15.0
ironflock --host operator@edge-01 os reset -c new-device.flock

O que o os reset -c kitchen-pi.flock imprime no dispositivo edge-01, cuja última redefinição desistiu, com o nome digitado na pergunta:

This device runs IronFlockOS 0.15.0 from slot B and is the IronFlock device edge-01.
The last factory reset of this device: 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; the device stayed the device it was, online with its old identity, and the .flock and proxy.conf that came with the request were removed.
What can be done: request the reset again, as this command does now, with three new attempts; or write IronFlockOS to the device's disk anew ('ironflock os flash'), which clears everything.
The factory reset restarts the device now. During the next boot the device resets itself, in seconds (minutes on a slow SD card), and restarts once more. It clears:
  - the apps with their data, and Docker's containers, images and volumes
  - the device's identity at IronFlock: the agent with its copy of the .flock and its database; the hostname goes back to ironflockos
  - the SSH user and every other user account, with their home folders
  - the logs, the SSH host keys and the downloaded updates
  - the network profiles (the WiFi among them), the proxy setting and the PTP setting
It keeps IronFlockOS 0.15.0 in slot B, which runs, and IronFlockOS 0.14.0 in slot A, so updates and rollbacks work as before.
It does not undo what was changed by hand in the system itself, such as a package or a file in /etc.
Then the device starts as a freshly written one with kitchen-pi.flock, which goes onto its IRONFLOCKOS partition: it enrolls as kitchen-pi and can be reached over SSH as operator, with the device key of that .flock and new SSH host keys.
An attempt that fails does not restart the device: it comes up as it is, and its next start tries again; after three failed attempts the reset gives up, and the device starts with what is there. 'ironflock status' shows a failed or given-up reset.
An SSH connection to the device, also the one of --host, ends with the restart.
? Type the device's name, edge-01, to reset it: edge-01
Factory reset requested: the device restarts now, resets itself and enrolls as kitchen-pi.

O resultado de os reset --keep-network --yes --json:

{"action":"reset","device":"edge-01","keep_network":true}

Recusa quando, com o código de saída 3, e diz por quê e o que fazer:

• não roda como root, em uma máquina que não roda o IronFlockOS, no pen drive de instalação, e enquanto o RAUC instala um pacote.
• o IronFlockOS não tem redefinição de fábrica: uma release mais nova a traz, e o os update a instala.
• /boot/efi não é a partição IRONFLOCKOS montada: nada está montado ali, ou está montado um sistema de arquivos que não é FAT.
• uma redefinição já começou: ela continua na próxima inicialização, e nada deve ser alterado até lá. A mensagem dá a última tentativa.
• sem -c, há um arquivo .flock na partição IRONFLOCKOS: depois da redefinição, o dispositivo se registraria com ele em vez de esperar por um.
• a próxima inicialização não seria a do sistema em execução marcado como bom. Uma atualização ou uma reversão espera a sua reinicialização: sudo reboot a inicia, sudo rauc status mark-bad other a descarta. Ou o sistema em execução ainda não foi marcado como bom: sudo rauc status mark-good o mantém, o os rollback volta atrás.
• a verificação do próprio dispositivo não aceita a solicitação: nada é solicitado, e a mensagem dá o motivo do dispositivo.

Falha quando, com o código de saída 1:

• a tabela de montagem não pode ser lida, então o comando não consegue saber se /boot/efi é a partição IRONFLOCKOS. Nada é escrito.
• o arquivo .flock de -c não é válido.
• a solicitação ou o arquivo .flock não pode ser escrito, ou outro arquivo .flock não pode ser removido. A solicitação é retirada, e o erro diz o que já foi removido.
• a reinicialização falha. O dispositivo então se redefine na sua próxima inicialização; remover /boot/efi/factory-reset.conf e o arquivo .flock da partição IRONFLOCKOS cancela a redefinição.

Ctrl-C, SIGTERM ou uma sessão SSH perdida enquanto o comando escreve a sua solicitação fazem com que ele retire a solicitação: ele termina com o código de saída 130, e o dispositivo não reinicia. Um nome digitado errado na pergunta encerra o comando com o código de saída 4.

Os códigos de saída de todos os comandos são explicados em Flags, saída e códigos de saída. Com --host, o código de saída 255 significa que a conexão SSH falhou.