Gravar o IronFlockOS em uma unidade

O ironflock os flash prepara a unidade a partir da qual um novo dispositivo inicia. Ele grava o IronFlockOS e o arquivo de configuração do dispositivo (.flock) na unidade, e o dispositivo se registra na sua primeira inicialização: ele se conecta ao IronFlock como o dispositivo desse arquivo .flock. Você pode preparar:

• um pen drive, um cartão SD ou um disco externo a partir do qual o dispositivo inicia,
• um pen drive de instalação que instala o IronFlockOS no disco interno de um PC,
• um arquivo de imagem de disco a partir do qual uma máquina virtual inicia.

O FlockFlasher é o app de desktop para a mesma tarefa. Para obter o arquivo .flock de um dispositivo, veja Conectar Dispositivos.

Execução típica

# 1. Conectar o pen drive ou o cartão SD e listar as unidades que podem ser gravadas
ironflock os drives
# 2. Opcional: listar as imagens que o catálogo oferece
ironflock os images
# 3. Gravar o IronFlockOS e o arquivo .flock do dispositivo na unidade
sudo ironflock os flash -c device.flock -d /dev/sdb

O os flash mostra o seu plano e pergunta antes de apagar a unidade. Quando ele terminar, coloque a unidade no dispositivo e inicie o dispositivo a partir dela.

ironflock os images

Lista as imagens do IronFlockOS que podem ser gravadas em uma unidade. Por padrão, lista as imagens da release do canal de produção.

ironflock os images [flags]

Roda no Linux e no macOS. Não precisa de root. Não pergunta nada.

Flags

As flags de todos os comandos estão em Flags, saída e códigos de saída.

O que faz

A lista vem do catálogo assinado do IronFlockOS no servidor de download, <download base>/ironflockos/manifest.json. O ironflock usa o catálogo apenas quando a sua assinatura Ed25519 é válida para a chave do catálogo embutida no ironflock. O FlockFlasher e o agente do dispositivo fixam a mesma chave. Nenhuma flag e nenhuma variável de ambiente desativa essa verificação. A base de download é a nuvem IronFlock, a menos que você indique outra; veja Base de download.

O último catálogo verificado fica guardado em uma pasta de cache, uma cópia por base de download:

Quando o servidor de download não pode ser alcançado, a cópia guardada o substitui, com uma nota no stderr. Um catálogo da mesma base de download que é mais antigo que a cópia guardada é recusado.

Uma imagem tem o nome do seu alvo de hardware, da sua variante e do seu kernel: ironflockos-<target>-<variant>, com -rt para o kernel de tempo real. ironflockos-amd64-efi-base-rt é o sistema base com o kernel de tempo real para PCs x86-64 com UEFI. Os alvos são:

• amd64-efi — PC x86-64 com UEFI
• arm64-efi — máquina ARM64 com UEFI
• rpi-arm64 — Raspberry Pi 4, 400 e CM4; Raspberry Pi 5 e CM5

As variantes são base, nvidia e installer. A imagem de instalação gera um pen drive que instala uma das imagens que traz no disco da máquina que inicia a partir dele. Uma imagem de uma variante, de um kernel ou de uma arquitetura que este ironflock não conhece (de uma release mais nova) fica de fora, com uma nota no stderr.

Exemplos

# As imagens da release de produção atual
ironflock os images
# Apenas as imagens para Raspberry Pi
ironflock os images --target rpi-arm64
# As imagens do canal de teste, como JSON
ironflock os images --channel test --json

Resultado

IMAGE                            VERSION  SIZE      HARDWARE
ironflockos-amd64-efi-base       0.13.0   638.1 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-base-rt    0.13.0   650.4 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-nvidia     0.13.0   1.0 GB    x86-64 PC with UEFI
ironflockos-amd64-efi-installer  0.13.0   2.5 GB    x86-64 PC with UEFI, installer stick for base, base-rt, nvidia
ironflockos-arm64-efi-base       0.13.0   582.4 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-base-rt    0.13.0   594.1 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-installer  0.13.0   1.5 GB    ARM64 machine with UEFI, installer stick for base, base-rt
ironflockos-rpi-arm64-base       0.13.0   639.4 MB  Raspberry Pi 4, 400 and CM4; Raspberry Pi 5 and CM5

Com --json (aqui com --target rpi-arm64):

{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"channels":{"production":"0.13.0","test":"0.13.0"},"images":[{"image_id":"ironflockos-rpi-arm64-base","version":"0.13.0","channels":["production","test"],"target":"rpi-arm64","variant":"base","kernel":"std","architecture":"arm64","boards":["raspberrypi4","raspberrypi5"],"hardware":["Raspberry Pi 4, 400 and CM4","Raspberry Pi 5 and CM5"],"file":"ironflockos-rpi-arm64-base-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-rpi-arm64-base-0.13.0.img.gz","size":639408901,"sha256":"9abd17f2098dfa236d440005222d0a6b583546ea9768e5eca8807c4e24ec88db"}]}

issued_at e key_id descrevem o catálogo, channels indica a release de cada canal, e from_cache é true quando o servidor de download não respondeu. Cada imagem tem o seu file com url, size e sha256. boards são os modelos de placa que um arquivo .flock indica (board.model), e hardware são os nomes deles. Uma imagem de instalação também tem payloads, os ids das imagens que ela traz.

Quando falha

• Código de saída 2 — --channel e --version juntas, uma versão em formato inválido, ou um canal, uma release, um alvo, uma variante ou um kernel que o catálogo não tem. O erro indica o que o catálogo tem.
• Código de saída 1 — o catálogo não passa na verificação, tem mais de 64 KiB, não está em um formato que este ironflock consiga ler, ou é mais antigo que a cópia guardada; ou ele não pode ser obtido e não há cópia guardada.

ironflock os drives

Lista as unidades desta máquina em que uma imagem do IronFlockOS pode ser gravada: pen drives, cartões SD, discos externos. Ele não grava, não desmonta e não abre nenhuma unidade.

ironflock os drives [flags]

Roda no Linux e no macOS. Não precisa de root. Não pergunta nada. No Linux, executa o lsblk (do util-linux) e lê /proc e /sys. No macOS, executa diskutil list, diskutil info e hdiutil info.

Flags

As flags de todos os comandos estão em Flags, saída e códigos de saída.

Quais unidades são recusadas

O os flash recusa as unidades que o os drives recusa, pelos mesmos motivos. Uma unidade é recusada quando ela (o motivo mostrado é o primeiro que se aplica):

1. é uma partição, como /dev/sdb1. A recusa indica o disco dela: uma imagem vai para o disco inteiro.
2. não é um disco: uma unidade óptica, um disco em memória (zram), um volume construído sobre outras unidades (LVM, dm-crypt, RAID, device-mapper; no macOS, um contêiner APFS, um conjunto AppleRAID ou outro disco sintetizado), ou um tipo de dispositivo que o comando não conhece (nbd, mtdblock).
3. contém parte do sistema em execução: /, /boot, /efi, /usr, /var, /etc ou um ponto de montagem abaixo de um deles (a partição EFI em /boot/efi, os dados do Docker em /var/lib/docker), /home, /opt, /srv, /data, swap, ou a mídia de um sistema live. Isso vale seja qual for a forma como o sistema está na unidade: em uma partição, via LVM, dm-crypt, RAID ou device-mapper, em um sistema de arquivos btrfs distribuído por várias unidades, em um pool ZFS, em um overlay, ou em um arquivo que um dispositivo loop lê. No macOS: / e os volumes abaixo de /System, passando pelos seus contêineres APFS até o disco que os contém.
4. está em uso: por LVM, dm-crypt, RAID ou device-mapper, por um pool ZFS com um dataset montado, ou por um dispositivo loop que lê um arquivo nela. No macOS, também por um contêiner APFS nela, um conjunto AppleRAID, uma imagem de disco cujo arquivo está nela, ou por Core Storage, AppleRAID ou um contêiner APFS que não está anexado. O macOS só libera um pen drive com um contêiner APFS quando o pen drive é apagado, por isso o motivo indica o comando que o apaga, por exemplo diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6 (ou Apagar no Utilitário de Disco).
5. é um disco interno da máquina: um disco SATA ou NVMe, o eMMC de uma placa. Uma unidade é interna, a menos que esteja conectada por USB ou por outro barramento cujos dispositivos podem ser desconectados. Um leitor de cartão embutido é interno, mas o seu cartão SD é uma mídia removível e é oferecido, também em um Mac. No macOS, um disco que não diz onde está conta como interno. O os flash --allow-internal grava um disco interno que --drive indica, quando nenhum outro motivo o recusa.
6. pode conter parte do sistema em execução: quando uma parte do sistema em execução não pode ser rastreada até uma unidade, todas as unidades são recusadas. É o caso em um contêiner, cujo sistema está no seu host, e no macOS para um sistema em um volume que não chega a nenhum disco físico, como o Core Storage.
7. é somente leitura, como um cartão SD travado.
8. não tem mídia, como um leitor de cartão sem cartão.

Uma unidade com sistemas de arquivos montados é oferecida; mounted os lista, e o os flash os desmonta antes de gravar. Dispositivos loop e, no macOS, imagens de disco anexadas não são listados, mas o os flash grava um deles quando --drive o indica.

Em um dispositivo que roda o IronFlockOS, o comando emite um aviso no stderr e em warnings: todas as imagens do IronFlockOS de um alvo têm os mesmos UUIDs de partição, então, enquanto uma segunda unidade IronFlockOS estiver conectada, o sistema em execução não consegue distinguir as suas próprias partições das partições da unidade.

Exemplos

# As unidades que podem ser gravadas
ironflock os drives
# Todas as unidades, com o motivo de cada recusa
ironflock os drives --all
# As unidades como JSON
ironflock os drives --json

Resultado

No Linux:

DEVICE        SIZE     BUS  MODEL
/dev/sdb      15.9 GB  usb  SanDisk Ultra
/dev/mmcblk0  31.9 GB  mmc  SD32G

Com --all:

DEVICE        SIZE     BUS   MODEL                    WRITABLE
/dev/sda      2.0 TB   sata  WDC WD20EZBX-00AYRA0     no: is an internal disk of this machine
/dev/sdb      15.9 GB  usb   SanDisk Ultra            yes
/dev/mmcblk0  31.9 GB  mmc   SD32G                    yes
/dev/nvme0n1  1.0 TB   nvme  Samsung SSD 980 PRO 1TB  no: holds / of the running system

Em um Mac, com --all:

DEVICE      SIZE      BUS             MODEL                 WRITABLE
/dev/disk0  500.3 GB  Apple Fabric    APPLE SSD AP0512R     no: holds / of the running system
/dev/disk1  524.3 MB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk2  5.4 GB    Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk3  494.4 GB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk5  15.9 GB   Secure Digital  Built In SDXC Reader  yes

Com --json (abreviado):

{"drives":[{"device":"/dev/sdb","kind":"disk","size":15931539456,"bus":"usb","removable":true,"internal":false,"read_only":false,"vendor":"SanDisk","model":"Ultra","serial":"4C530001230812115352","mounted":[{"device":"/dev/sdb1","mountpoint":"/media/anna/STICK"}],"system":[],"maybe_system":[],"holders":[],"writable":true},{"device":"/dev/mmcblk0",...}],"warnings":[]}

Quando não há unidade em que gravar, o texto diz isso, drives fica vazio e o código de saída é 0.

Quando falha

• Código de saída 3 — no Linux, o lsblk não está instalado; ou o comando roda em um sistema que não é Linux nem macOS.

ironflock os flash

Grava o IronFlockOS em uma unidade (um pen drive, um cartão SD, um disco externo) e coloca o arquivo .flock do dispositivo na partição IRONFLOCKOS da unidade, a partição FAT32 com esse nome que toda unidade IronFlockOS tem. O dispositivo se registra com esse arquivo na sua primeira inicialização. Com --output, em vez disso, ele escreve o mesmo conteúdo em um arquivo de imagem de disco para uma máquina virtual.

Aviso: Tudo o que está na unidade é apagado. Confira o nome da unidade com ironflock os drives antes de gravar. O os flash nunca escolhe uma unidade por conta própria.

ironflock os flash -c <device.flock> (-d <drive> | --output <file>) [flags]

Sem root, o erro indica a linha de comando a digitar, com sudo na frente. No macOS, um usuário que pode gravar no dispositivo raw da unidade não precisa de root: o usuário que anexou uma imagem de disco, ou um usuário a quem o proprietário da máquina deu a unidade, por exemplo com sudo chown <user> /dev/disk4 /dev/rdisk4. Com --output, o comando não precisa de root. Veja também Privilégios de root.

Flags

As flags de todos os comandos estão em Flags, saída e códigos de saída.

O que faz

1. Verifica a unidade. Ele resolve --drive e recusa a unidade pelos motivos que o os drives dá, antes de ler, obter ou perguntar qualquer coisa. Sem --drive (e sem --output), ele indica as unidades que pode gravar e termina com o código de saída 2.
2. Lê o arquivo .flock. Ele precisa ser 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.
3. Escolhe a imagem do catálogo assinado, que ele obtém e verifica como o os images faz. Ele usa a imagem que --image indica, senão a imagem padrão (variante base, kernel padrão) do hardware que o arquivo .flock indica: o seu board.model, senão o seu architecture quando o catálogo tem um único hardware para ela. Com --installer, usa o pen drive de instalação desse hardware que traz a imagem.
4. Mostra o plano no stderr: a imagem, de onde vem o arquivo dela, o arquivo .flock (pelo nome), o WiFi, a unidade e os sistemas de arquivos da unidade que ele desmonta. Então pergunta. “No” vem pré-selecionado, então Enter sozinho não apaga nada.
5. Obtém o arquivo de imagem: o arquivo de --image-file, senão a cópia no cache, senão um download para o cache, retomado de onde um download anterior parou. Como root, o cache é /var/cache/ironflock/images no Linux e /var/root/Library/Caches/ironflock/images no macOS. O download vai para um arquivo .part. Cada arquivo só é escrito quando o seu tamanho e o seu SHA-256 são os do catálogo. Uma tentativa de download que não traz nenhum byte durante um minuto termina, e o download desiste depois de três tentativas assim seguidas.
6. Verifica a unidade de novo. Ela precisa ser a unidade que o plano mostrou e continuar não recusada: o mesmo dispositivo, tamanho, número de série e mídia. No Linux, isso inclui o fabricante, o modelo, o barramento e cada partição com o seu sistema de arquivos, rótulo, UUID e tamanho. No macOS, que não indica número de série, são o modelo, o barramento, a posição na árvore de dispositivos e as partições com os seus UUIDs. Um pen drive retirado depois do plano deixa o seu nome para a próxima unidade conectada; essa unidade não é gravada, e nada é desmontado. Então o comando desmonta os sistemas de arquivos que o plano listou, e apenas esses, e abre a unidade com acesso exclusivo para gravação. No macOS, ele grava pelo dispositivo raw (/dev/rdisk4), que um segundo os flash não consegue abrir ao mesmo tempo.
7. Grava a imagem, depois relê a unidade e compara o conteúdo.
8. Escreve o arquivo .flock na pasta raiz da partição IRONFLOCKOS, sem montá-la. Um pen drive de instalação também recebe installer.conf. Com --wifi-ssid, a cópia na unidade indica essa rede; o próprio arquivo .flock não é alterado.
9. No macOS, ejeta a unidade (diskutil eject), para que você possa retirá-la. Quando a ejeção falha, a unidade é gravada mesmo assim: o comando emite um aviso, e você ejeta a unidade no Finder antes de retirá-la.

Como root, o comando só usa uma pasta de cache quando ela é uma pasta e não um link, pertence ao root e ninguém mais pode escrever nela. Ele cria uma que falte com o modo 0700 e, diante de qualquer outra, para antes de ler, apagar ou baixar qualquer coisa ali. Antes de obter uma imagem do catálogo, ele apaga os arquivos de imagem no cache que o catálogo não lista mais, e os downloads parciais deles.

Um --image para um hardware diferente do que o arquivo .flock indica é gravado depois de um aviso no plano: o dispositivo não executaria os seus apps. Em um dispositivo que roda o IronFlockOS, o plano emite o aviso como o os drives faz. Com --allow-internal, o plano avisa que a unidade é um disco interno.

--yes responde sim à pergunta. Sem terminal (um pipe, um script) e sem --yes, o comando não pergunta e termina com o código de saída 4. O --json também não pergunta nada, então precisa de --yes para gravar uma unidade. Com --json, o plano não é impresso: o stderr traz apenas os eventos de progresso, e os avisos ficam no resultado. Veja Perguntas e confirmação e Saída e JSON.

WiFi

O dispositivo entra no WiFi que o seu arquivo .flock indica. --wifi-ssid lhe dá outra rede. O IronFlockOS só entra em um WiFi com senha, então --wifi-ssid e --wifi-password-file sempre vão juntas. A senha de WiFi vem de um arquivo ou de um pipe, nunca da linha de comando, onde o ps e o histórico do shell a mostrariam. O comando não a imprime em lugar nenhum. A cópia do arquivo .flock na unidade indica a rede em wlanssid e password.

Nota: Quando a senha de WiFi vem por /dev/stdin, o stdin não é um terminal, então o comando não pode perguntar. Adicione --yes.

Pen drive de instalação

Com --installer, a unidade se torna um pen drive de instalação para um PC com UEFI (amd64-efi, arm64-efi); ironflock os images --variant installer lista as imagens de instalação. O pen drive traz várias imagens do seu hardware; o installer.conf no pen drive indica a que ele instala (payload, a imagem escolhida como na etapa 3) e contém as flags --installer-* que você informou. Quando o PC inicia a partir do pen drive, o instalador:

1. escolhe o disco por --installer-disk: o maior disco (padrão), o disco /dev/<name>, ou o disco com o id by-id:<id>. Ele só grava um disco USB com --installer-allow-usb yes.
2. pergunta no console do PC antes de gravar, a menos que se use --installer-confirm no.
3. grava a imagem e o arquivo .flock do dispositivo nesse disco.
4. desliga o PC (padrão), ou o reinicia com --installer-after reboot.

Retire o pen drive e inicie o PC a partir do seu disco interno. O dispositivo se registra na sua primeira inicialização.

Aviso: Um pen drive gravado com --installer-confirm no apaga o disco de todo PC que inicia a partir dele, sem perguntar. Identifique esse pen drive com uma etiqueta e mantenha-o longe de outras máquinas.

Para substituir o Linux de uma máquina em execução sem um pen drive, veja Substituir o Linux pelo IronFlockOS.

Um arquivo de imagem baixado

--image-file grava um arquivo de imagem que você baixou antes, por exemplo em uma máquina que não consegue baixar os arquivos de imagem do catálogo. Pegue o endereço do arquivo no url do os images --json. O arquivo só é gravado quando tem o tamanho e o SHA-256 que o catálogo indica para a imagem.

O comando ainda precisa do catálogo assinado para verificar o arquivo. Ele obtém o catálogo ou, quando o servidor de download não pode ser alcançado, usa a cópia que guardou da última vez que um catálogo da mesma base de download foi verificado. Essa cópia é por usuário: como root, é a cópia do root. Um servidor próprio também funciona: com outra base de download (--download-base ou IRONFLOCK_DL_BASE), o comando obtém o catálogo de <download base>/ironflockos/manifest.json e o arquivo de imagem de <download base>/ironflockos/<version>/<file>.

Nota: O arquivo é lido mais uma vez enquanto é gravado, e o seu SHA-256 só volta a ser conhecido depois da gravação. Mantenha o arquivo onde nenhum outro usuário possa alterá-lo.

Um arquivo de imagem para uma máquina virtual

--output <file> escreve a imagem e os arquivos do dispositivo em um arquivo regular no lugar de uma unidade: uma imagem de disco raw a partir da qual uma máquina virtual inicia, como o seu disco. A imagem, as suas verificações e os arquivos em IRONFLOCKOS são os mesmos que para uma unidade. Nenhuma unidade é procurada, desmontada ou aberta, então o comando não precisa de root. --image, --image-file, --installer com as suas flags, e --wifi-ssid funcionam como com uma unidade.

• Tamanho — O plano indica o arquivo e o seu tamanho: o tamanho da imagem descompactada. Quando a imagem ainda precisa ser baixada, essa linha vem depois do download.
• Pergunta — Um arquivo novo não apaga nada, e o comando não pergunta. Um arquivo que já existe é substituído: o plano diz isso, e o comando pergunta antes.
• Primeiro com outro nome — A imagem vai para um arquivo novo na mesma pasta, <file>.<number>.part. Ele só recebe o nome <file> quando contém a imagem inteira, foi relido e tem os arquivos do dispositivo na sua partição IRONFLOCKOS. Uma escrita que falha ou é interrompida remove o arquivo .part, e com o nome não fica nada, ou fica o arquivo que já estava lá, sem alteração. Um kill -9 ou uma queda de energia pode deixar o arquivo .part para trás.
• Privado — O arquivo contém o segredo do dispositivo, assim como o arquivo .flock. Ele recebe o modo 0600, também quando substitui um arquivo com um modo mais aberto.
• Esparso — Onde a imagem tem um bloco inteiro de zeros (blocos de 4 MiB), o arquivo recebe um buraco, em um sistema de arquivos que suporta buracos. Ele é lido da mesma forma e ocupa menos espaço.

# Escrever um arquivo de imagem de disco para uma máquina virtual, sem root
ironflock os flash -c device.flock --output device.img

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Output:       device.img, a new file: the image, unpacked; its size is known once the image is downloaded
(the progress of downloading, checking)
Unpacked, the image has 4.6 GB: the size of device.img.
(the progress of writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is in device.img and read back, with device.flock in its IRONFLOCKOS partition.
Grow the file to the size of the virtual machine's disk before the machine starts from it (truncate -s 20G device.img): on its first boot IronFlockOS makes slot B and /data in that space, and the device enrolls as kitchen-pc.

A imagem contém a partição IRONFLOCKOS e o primeiro dos dois slots de sistema que o IronFlockOS atualiza alternadamente (slot A). Na primeira inicialização, o IronFlockOS cria o slot B, do mesmo tamanho do slot A, e a partição de dados /data no resto do disco. Aumente o arquivo antes que a máquina virtual inicie a partir dele pela primeira vez: para pelo menos 10 GiB para base e 18 GiB para nvidia. O que o arquivo ganha são zeros, que o sistema de arquivos guarda como um buraco. Um hypervisor que aceita discos raw usa o arquivo como está. Para outro formato, converta o arquivo aumentado, por exemplo com qemu-img convert -f raw -O qcow2 device.img device.qcow2.

As imagens de amd64-efi e arm64-efi iniciam no QEMU; a imagem do Raspberry Pi (rpi-arm64) não. Para amd64-efi no Linux com KVM e o firmware UEFI do pacote ovmf (Debian, Ubuntu):

# Aumentar o arquivo, copiar as variáveis do firmware e iniciar a máquina
truncate -s 20G device.img
cp /usr/share/OVMF/OVMF_VARS_4M.fd device-vars.fd
qemu-system-x86_64 -machine q35 -accel kvm -cpu host -m 2048 -smp 2 \
  -drive if=pflash,format=raw,unit=0,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,unit=1,file=device-vars.fd \
  -drive file=device.img,format=raw,if=virtio \
  -netdev user,id=net0 -device virtio-net-pci,netdev=net0 \
  -device i6300esb \
  -nographic

• -nographic coloca a primeira porta serial no terminal, onde o GRUB e o kernel escrevem. Ctrl-A X encerra o QEMU.
• -device i6300esb é um watchdog, pelo qual o IronFlockOS reinicia uma máquina que trava.
• -netdev user dá à máquina a rede do host, pela qual o dispositivo alcança o IronFlock.
• Sem KVM (sem /dev/kvm, ou em um host de outra arquitetura), omita -accel kvm e use -cpu max. O QEMU então emula a máquina, o que é muito mais lento.

arm64-efi inicia com qemu-system-aarch64 -machine virt e o firmware do pacote qemu-efi-aarch64 (/usr/share/AAVMF/AAVMF_CODE.fd, e uma cópia de AAVMF_VARS.fd), sem o watchdog. Em um Mac com Apple silicon, o QEMU do Homebrew a inicia com -accel hvf -cpu host e o firmware /opt/homebrew/share/qemu/edk2-aarch64-code.fd, com uma cópia de edk2-arm-vars.fd.

Exemplos

# Gravar a imagem padrão para o hardware do arquivo .flock em um pen drive
sudo ironflock os flash -c device.flock -d /dev/sdb
# Gravar um pen drive de instalação que instala a imagem NVIDIA em um PC
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# Gravar um cartão SD para um dispositivo que entra no WiFi "Workshop"
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Gravar um pen drive em um Mac
sudo ironflock os flash -c device.flock -d /dev/disk4

Resultado

O plano e o progresso vão para o stderr; as últimas linhas são o resultado. No Linux:

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Drive:        /dev/sdb: SanDisk Ultra, 15.9 GB, usb, serial 4C530001230812115352
Everything on /dev/sdb is erased. Unmounted first: /media/anna/STICK.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is on /dev/sdb and read back, with device.flock in its IRONFLOCKOS partition.
Start the device from it: it enrolls as kitchen-pc on its first boot.

Em um Mac, primeiro sem root, depois com sudo:

$ ironflock os flash -c pi.flock -d /dev/disk5
Error: "ironflock os flash" must run as root (sudo) to write a drive: sudo ironflock os flash -c pi.flock -d /dev/disk5
$ sudo ironflock os flash -c pi.flock -d /dev/disk5 --yes
IronFlockOS catalog of 2026-11-10T16:41:54Z, signed with key 036ef3bd.
Image:        ironflockos-rpi-arm64-base 0.14.0, for Raspberry Pi 4, 400 and CM4
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.14.0/ironflockos-rpi-arm64-base-0.14.0.img.gz (640.1 MB), downloaded and checked against the catalog
Device file:  pi.flock, for the device pi-workshop
WiFi:         Office (from the .flock)
Drive:        /dev/disk5: Built In SDXC Reader, 15.9 GB, Secure Digital
Everything on /dev/disk5 is erased. Unmounted first: /Volumes/UNTITLED.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.14.0 (ironflockos-rpi-arm64-base) is on /dev/disk5 and read back, with pi.flock in its IRONFLOCKOS partition.
/dev/disk5 is ejected and can be taken out.
Start the device from it: it enrolls as pi-workshop on its first boot.

Com --json, aqui para um pen drive de instalação (--installer --installer-confirm no --yes --json):

{"action":"flashed","device":"kitchen-pc","device_file":"device.flock","hardware":"x86-64 PC with UEFI","image":{"image_id":"ironflockos-amd64-efi-installer","version":"0.13.0","file":"ironflockos-amd64-efi-installer-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-installer-0.13.0.img.gz","size":2512345678,"sha256":"..."},"installer":{"payload":"ironflockos-amd64-efi-base","disk":"largest","confirm":"no","after":"poweroff","allow_usb":"no"},"wifi":{"ssid":"Office","from":"flock"},"drive":{"device":"/dev/sdb","size":15931539456,"bus":"usb","model":"SanDisk Ultra","serial":"4C530001230812115352","internal":false},"source":"download","unmounted":["/media/anna/STICK"],"bytes":6442450944,"verified":true,"ejected":false,"files":["device.flock","installer.conf"],"catalog":{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"notes":[]},"warnings":[]}

Com --output, o resultado tem output no lugar de drive, por exemplo "output":{"file":"/home/anna/device.img","replaced":true}.

Quando recusa

Código de saída 3, e nada é gravado:

• A unidade é uma que o os drives recusa; o erro dá o motivo, e --yes não muda nada. A única exceção é um disco interno desta máquina: --allow-internal o grava quando --drive o indica, e o erro indica a flag quando ela tornaria a unidade gravável. A flag não suspende nenhuma outra recusa e não responde à pergunta.
• A unidade mudou entre o plano e a gravação, ou é recusada nesse momento. O erro diz o que mudou.
• A unidade está em uso quando é aberta: está montado um sistema de arquivos que o plano não listou, um sistema de arquivos não é desmontado, ou um programa mantém a unidade aberta.
• O comando não roda como root (ou, no macOS, como um usuário que pode gravar no dispositivo raw da unidade). O erro indica a linha de comando com sudo.
• Com --output: o nome não é um arquivo regular (um dispositivo, uma pasta, um named pipe ou qualquer link simbólico), ou a sua pasta não existe, antes que qualquer coisa seja lida ou obtida. Uma pasta que não aceita um arquivo novo (sem permissão, um sistema de arquivos somente leitura) é recusada depois do plano e antes do download. Um arquivo que ocupou o nome enquanto a imagem era escrita, onde o plano indicava um arquivo novo, não é substituído.

Código de saída 2, uma linha de comando incorreta:

• Nem --drive nem --output, também com --allow-internal. --output com --drive ou com --allow-internal, sem nome, ou com -. Um --output que indica o arquivo .flock de -c ou o arquivo de --image-file.
• Uma flag --installer-* sem --installer, ou com um valor que o instalador não aceita.
• --wifi-ssid sem --wifi-password-file, ou vice-versa.
• Um arquivo .flock que não diz para qual hardware é; nesse caso, --image escolhe a imagem.
• Uma imagem que o catálogo não tem, um pen drive de instalação que não traz a imagem, ou um hardware sem pen drive de instalação.
• Com --host: --image-file e --output, porque o --host não copia o arquivo de imagem para a outra máquina e não traz nenhum arquivo de volta. Execute o comando aqui sem --host, ou na própria máquina. Já o arquivo .flock e o arquivo da senha de WiFi vão junto.

Código de saída 4: a pergunta foi respondida com não (Enter sozinho ou Esc), ou não pôde ser feita e --yes não foi informado.

Código de saída 1, o comando falhou:

• O arquivo .flock ou o arquivo da senha de WiFi não é válido, ou o arquivo de imagem não é o do catálogo.
• O catálogo não pode ser usado, pelos motivos com que o os images falha.
• O download, a gravação ou a releitura falha. Uma gravação que falha depois do seu primeiro bloco (um erro de E/S, uma unidade menor que a imagem) diz que a unidade agora contém uma parte da imagem, que não inicia nada: grave-a de novo.
• A imagem está na unidade e foi relida, mas o arquivo .flock não pôde ser escrito em IRONFLOCKOS. Sem ele, o dispositivo não se registra; o mesmo comando grava os dois de novo.
• Com --output: o sistema de arquivos está cheio, os arquivos do dispositivo não podem ser colocados na imagem, ou a entrada do arquivo .part foi substituída enquanto a imagem era escrita. O nome fica então como estava antes.

Código de saída 130: Ctrl-C enquanto a imagem é baixada, gravada ou relida. Um download interrompido não gravou nada, e o mesmo comando o retoma. Uma gravação ou releitura para no próximo bloco, e o erro diz o que a unidade contém. Depois que o último bloco foi relido, o comando conclui as suas últimas etapas curtas e termina com 0. Um segundo Ctrl-C encerra o comando imediatamente; com --output, ele pode deixar o arquivo .part para trás.