IronFlockOS를 드라이브에 쓰기

ironflock os flash는 새 디바이스가 시작할 드라이브를 준비합니다. IronFlockOS와 디바이스 구성 파일(.flock)을 드라이브에 쓰면, 디바이스는 첫 부팅 때 등록됩니다. 즉 그 .flock 파일의 디바이스로 IronFlock에 연결됩니다. 다음을 준비할 수 있습니다:

• 디바이스가 시작하는 USB 스틱, SD 카드 또는 외장 디스크
• PC의 내부 디스크에 IronFlockOS를 설치하는 설치 USB 스틱
• 가상 머신이 시작하는 디스크 이미지 파일

FlockFlasher는 같은 작업을 하는 데스크톱 앱입니다. 디바이스의 .flock 파일을 받는 방법은 디바이스 연결을 참조하십시오.

일반적인 사용 순서

# 1. 스틱이나 SD 카드를 꽂은 다음, 쓸 수 있는 드라이브 나열
ironflock os drives
# 2. 선택 사항: 카탈로그가 제공하는 이미지 나열
ironflock os images
# 3. IronFlockOS와 디바이스의 .flock 파일을 드라이브에 쓰기
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash는 계획을 보여 주고, 드라이브를 지우기 전에 묻습니다. 작업이 끝나면 드라이브를 디바이스에 넣고 디바이스를 그 드라이브로 시작하십시오.

ironflock os images

드라이브에 쓸 수 있는 IronFlockOS 이미지를 나열합니다. 기본적으로 프로덕션 채널에 있는 릴리스의 이미지를 나열합니다.

ironflock os images [flags]

Linux와 macOS에서 실행됩니다. root 권한이 필요 없습니다. 아무것도 묻지 않습니다.

플래그

모든 명령의 플래그는 플래그, 출력 및 종료 코드에 나와 있습니다.

동작 방식

목록은 다운로드 서버에 있는 서명된 IronFlockOS 카탈로그 <download base>/ironflockos/manifest.json에서 가져옵니다. ironflock은 카탈로그의 Ed25519 서명이 ironflock에 내장된 카탈로그 키로 검증될 때만 카탈로그를 사용합니다. FlockFlasher와 디바이스 에이전트도 같은 키를 고정해 사용합니다. 어떤 플래그나 환경 변수로도 이 검사를 끌 수 없습니다. 다른 다운로드 베이스를 지정하지 않으면 다운로드 베이스는 IronFlock 클라우드입니다. 다운로드 베이스를 참조하십시오.

마지막으로 검증된 카탈로그는 다운로드 베이스마다 하나씩 캐시 폴더에 보관됩니다:

다운로드 서버에 도달할 수 없으면 보관된 사본을 대신 사용하며, stderr에 그 사실이 나옵니다. 같은 다운로드 베이스의 카탈로그 중 보관된 사본보다 오래된 카탈로그는 거부됩니다.

이미지 이름은 하드웨어 타깃, 변형, 커널로 정해집니다. 형식은 ironflockos-<target>-<variant>이며, 실시간 커널이면 -rt가 붙습니다. ironflockos-amd64-efi-base-rt는 UEFI를 사용하는 x86-64 PC용으로, 실시간 커널을 쓰는 기본 시스템입니다. 타깃은 다음과 같습니다:

• amd64-efi — UEFI를 사용하는 x86-64 PC
• arm64-efi — UEFI를 사용하는 ARM64 머신
• rpi-arm64 — Raspberry Pi 4, 400, CM4 및 Raspberry Pi 5, CM5

변형은 base, nvidia, installer입니다. 설치 이미지로는 USB 스틱을 만듭니다. 이 스틱은 자신이 담고 있는 이미지 중 하나를, 스틱으로 시작하는 머신의 디스크에 설치합니다. 이 ironflock이 모르는 변형, 커널 또는 아키텍처의 이미지(더 새로운 릴리스의 이미지)는 목록에서 빠지며, stderr에 그 사실이 나옵니다.

예시

# 현재 프로덕션 릴리스의 이미지
ironflock os images
# Raspberry Pi 이미지만
ironflock os images --target rpi-arm64
# test 채널의 이미지를 JSON으로
ironflock os images --channel test --json

결과

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

--json을 사용한 경우(여기서는 --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과 key_id는 카탈로그를 설명하고, channels는 각 채널의 릴리스를 나타내며, from_cache는 다운로드 서버가 응답하지 않았을 때 true입니다. 각 이미지에는 file과 그 url, size, sha256이 있습니다. boards는 .flock 파일이 지정하는 보드 모델(board.model)이고, hardware는 그 이름입니다. 설치 이미지에는 자신이 담고 있는 이미지의 ID인 payloads도 있습니다.

실패하는 경우

• 종료 코드 2 — --channel과 --version을 함께 지정한 경우, 올바른 버전이 아닌 버전, 또는 카탈로그에 없는 채널, 릴리스, 타깃, 변형, 커널. 오류 메시지는 카탈로그에 있는 것을 알려 줍니다.
• 종료 코드 1 — 카탈로그가 검증되지 않거나, 64 KiB보다 크거나, 이 ironflock이 읽을 수 있는 카탈로그가 아니거나, 보관된 사본보다 오래된 경우. 또는 카탈로그를 가져올 수 없고 보관된 사본도 없는 경우.

ironflock os drives

이 머신의 드라이브 중 IronFlockOS 이미지를 쓸 수 있는 드라이브를 나열합니다: USB 스틱, SD 카드, 외장 디스크. 어떤 드라이브에도 쓰지 않고, 언마운트하지 않고, 열지 않습니다.

ironflock os drives [flags]

Linux와 macOS에서 실행됩니다. root 권한이 필요 없습니다. 아무것도 묻지 않습니다. Linux에서는 lsblk(util-linux)를 실행하고 /proc과 /sys를 읽습니다. macOS에서는 diskutil list, diskutil info, hdiutil info를 실행합니다.

플래그

모든 명령의 플래그는 플래그, 출력 및 종료 코드에 나와 있습니다.

거부되는 드라이브

os flash는 os drives가 거부하는 드라이브를 같은 이유로 거부합니다. 드라이브는 다음 경우에 거부됩니다(해당하는 첫 번째 이유가 표시됨):

1. 파티션인 경우. 예: /dev/sdb1. 이미지는 디스크 전체에 쓰이므로, 거부 메시지는 그 파티션의 디스크를 알려 줍니다.
2. 디스크가 아닌 경우: 광학 드라이브, 메모리 안의 디스크(zram), 다른 드라이브 위에 구성된 볼륨(LVM, dm-crypt, RAID, device-mapper. macOS에서는 APFS 컨테이너, AppleRAID 세트 또는 그 밖의 합성 디스크), 또는 명령이 모르는 종류의 디바이스(nbd, mtdblock).
3. 실행 중인 시스템의 일부가 있는 경우: /, /boot, /efi, /usr, /var, /etc 또는 그 아래의 마운트(/boot/efi의 EFI 파티션, /var/lib/docker의 Docker 데이터), /home, /opt, /srv, /data, 스왑, 또는 라이브 시스템의 매체. 시스템이 드라이브에 어떤 방식으로 있든 마찬가지입니다: 파티션에, LVM, dm-crypt, RAID 또는 device-mapper를 통해, 여러 드라이브에 걸친 btrfs 파일 시스템에, ZFS 풀에, 오버레이에, 또는 루프 디바이스가 읽는 파일에. macOS에서는 /와 /System 아래의 볼륨이며, 그 APFS 컨테이너를 거쳐 이를 담은 디스크까지 추적합니다.
4. 사용 중인 경우: LVM, dm-crypt, RAID 또는 device-mapper, 데이터 세트가 마운트된 ZFS 풀, 또는 드라이브에 있는 파일을 읽는 루프 디바이스가 사용하는 경우. macOS에서는 드라이브에 있는 APFS 컨테이너, AppleRAID 세트, 파일이 드라이브에 있는 디스크 이미지, 또는 연결되지 않은 Core Storage, AppleRAID, APFS 컨테이너가 사용하는 경우도 해당합니다. macOS는 APFS 컨테이너가 있는 스틱을 지워야만 놓아 주므로, 이유에는 스틱을 지우는 명령이 나옵니다. 예: diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6(또는 디스크 유틸리티의 지우기).
5. 머신의 내부 디스크인 경우: SATA 또는 NVMe 디스크, 보드의 eMMC. USB나 연결된 디바이스를 분리할 수 있는 다른 버스로 연결되지 않은 드라이브는 내부 드라이브입니다. 내장 카드 리더는 내부 드라이브이지만, 그 SD 카드는 이동식 매체이므로 Mac에서도 목록에 나옵니다. macOS에서 위치를 알리지 않는 디스크는 내부 디스크로 간주합니다. os flash --allow-internal은 다른 이유로 거부되지 않으면 --drive가 지정하는 내부 디스크에 씁니다.
6. 실행 중인 시스템의 일부가 있을 수 있는 경우: 실행 중인 시스템의 일부를 드라이브까지 추적할 수 없으면 모든 드라이브가 거부됩니다. 시스템이 호스트에 있는 컨테이너 안에서, 그리고 macOS에서 시스템이 Core Storage처럼 물리 디스크에 이르지 않는 볼륨에 있을 때 그렇습니다.
7. 읽기 전용인 경우. 예: 잠긴 SD 카드.
8. 매체가 없는 경우. 예: 카드가 없는 카드 리더.

파일 시스템이 마운트된 드라이브는 목록에 나옵니다. mounted가 그 파일 시스템을 나열하며, os flash는 쓰기 전에 이를 언마운트합니다. 루프 디바이스와 macOS의 연결된 디스크 이미지는 나열되지 않지만, --drive로 지정하면 os flash가 씁니다.

IronFlockOS를 실행하는 디바이스에서는 명령이 stderr와 warnings로 경고합니다. 같은 타깃의 모든 IronFlockOS 이미지는 파티션 UUID가 같으므로, 두 번째 IronFlockOS 드라이브가 연결되어 있는 동안 실행 중인 시스템은 자신의 파티션과 드라이브의 파티션을 구분할 수 없습니다.

예시

# 쓸 수 있는 드라이브
ironflock os drives
# 모든 드라이브. 거부된 드라이브는 이유와 함께
ironflock os drives --all
# 드라이브를 JSON으로
ironflock os drives --json

결과

Linux에서:

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

--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

Mac에서 --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

--json을 사용한 경우(줄임):

{"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":[]}

쓸 수 있는 드라이브가 없으면 텍스트가 그 사실을 알려 주고, drives는 비어 있으며, 종료 코드는 0입니다.

실패하는 경우

• 종료 코드 3 — Linux에서 lsblk가 설치되어 있지 않은 경우. 또는 Linux나 macOS가 아닌 시스템에서 명령을 실행한 경우.

ironflock os flash

IronFlockOS를 드라이브(USB 스틱, SD 카드, 외장 디스크)에 쓰고, 디바이스의 .flock 파일을 드라이브의 IRONFLOCKOS 파티션에 넣습니다. 이 파티션은 모든 IronFlockOS 드라이브에 있는 같은 이름의 FAT32 파티션입니다. 디바이스는 첫 부팅 때 이 파일로 등록됩니다. --output을 사용하면 같은 내용을 드라이브 대신 가상 머신용 디스크 이미지 파일에 씁니다.

경고: 드라이브의 모든 내용이 지워집니다. 쓰기 전에 ironflock os drives로 드라이브 이름을 확인하십시오. os flash는 드라이브를 직접 고르지 않습니다.

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

root가 아니면 오류 메시지가 입력할 명령줄을 앞에 sudo를 붙여 알려 줍니다. macOS에서는 드라이브의 raw 디바이스에 쓸 수 있는 사용자라면 root가 필요 없습니다. 디스크 이미지를 연결한 사용자, 또는 머신 소유자가 드라이브를 넘겨준 사용자입니다. 예: sudo chown <user> /dev/disk4 /dev/rdisk4. --output을 사용하면 명령에 root 권한이 필요 없습니다. root 권한도 참조하십시오.

플래그

모든 명령의 플래그는 플래그, 출력 및 종료 코드에 나와 있습니다.

동작 방식

1. 드라이브를 검사합니다. --drive가 가리키는 드라이브를 확인하고, 무엇이든 읽거나 가져오거나 묻기 전에 os drives가 제시하는 이유로 거부합니다. --drive가 없으면(--output도 없으면) 쓸 수 있는 드라이브를 알려 주고 종료 코드 2로 끝납니다.
2. .flock 파일을 읽습니다. 이름이 *.flock이고 최대 5 MiB인 파일이어야 하며, secret과 device_key가 있는 JSON 객체이고, name과 serial_number가 일반 이름이어야 합니다.
3. 이미지를 고릅니다. os images와 마찬가지로 서명된 카탈로그를 가져와 검증하고, 그 카탈로그에서 고릅니다. --image가 지정하는 이미지를, 없으면 .flock 파일이 지정하는 하드웨어의 기본 이미지(base 변형, 표준 커널)를 택합니다. 하드웨어는 .flock의 board.model로, 없으면 카탈로그에 그 아키텍처용 하드웨어가 하나뿐일 때 architecture로 정합니다. --installer를 사용하면 그 이미지를 담은 해당 하드웨어의 설치 USB 스틱을 택합니다.
4. 계획을 보여 줍니다. stderr에 이미지, 이미지 파일의 출처, .flock 파일(이름), WiFi, 드라이브, 언마운트할 드라이브의 파일 시스템이 나옵니다. 그런 다음 묻습니다. “No”가 미리 선택되어 있으므로 Enter만 누르면 아무것도 지우지 않습니다.
5. 이미지 파일을 가져옵니다. --image-file의 파일, 없으면 캐시의 사본을 사용하고, 그것도 없으면 캐시로 다운로드하며, 이전 다운로드가 멈춘 곳에서 이어받습니다. root로 실행하면 캐시는 Linux에서 /var/cache/ironflock/images, macOS에서 /var/root/Library/Caches/ironflock/images입니다. 다운로드는 .part 파일로 들어갑니다. 각 파일은 크기와 SHA-256이 카탈로그와 같을 때만 쓰입니다. 1분 동안 1바이트도 받지 못한 다운로드 시도는 끝나며, 이런 시도가 연속 세 번이면 다운로드를 포기합니다.
6. 드라이브를 다시 검사합니다. 계획에 나온 드라이브여야 하고, 여전히 거부 대상이 아니어야 합니다. 디바이스, 크기, 일련번호, 매체가 같아야 합니다. Linux에서는 제조사, 모델, 버스, 그리고 각 파티션과 그 파일 시스템, 레이블, UUID, 크기도 포함합니다. 일련번호를 알려 주지 않는 macOS에서는 모델, 버스, 디바이스 트리에서의 위치, 파티션과 그 UUID입니다. 계획 이후에 뽑힌 스틱의 이름은 다음에 꽂히는 드라이브가 물려받습니다. 이런 드라이브에는 쓰지 않으며, 아무것도 언마운트하지 않습니다. 그런 다음 명령은 계획에 나온 파일 시스템만 언마운트하고, 쓰기용으로 드라이브를 독점적으로 엽니다. macOS에서는 raw 디바이스(/dev/rdisk4)를 통해 쓰며, 두 번째 os flash는 이 디바이스를 동시에 열 수 없습니다.
7. 이미지를 씁니다. 그런 다음 드라이브를 다시 읽어 비교합니다.
8. .flock 파일을 씁니다. IRONFLOCKOS 파티션을 마운트하지 않고 그 루트 폴더에 씁니다. 설치 USB 스틱에는 installer.conf도 들어갑니다. --wifi-ssid를 사용하면 드라이브의 사본이 그 네트워크를 지정하며, .flock 파일 자체는 변경되지 않습니다.
9. macOS에서는 드라이브를 꺼냅니다(diskutil eject). 그래야 드라이브를 뺄 수 있습니다. 꺼내기가 실패해도 드라이브에는 이미 다 쓰여 있습니다. 명령이 경고하며, 드라이브를 빼기 전에 Finder에서 꺼내십시오.

root로 실행하면 명령은 캐시 폴더가 링크가 아닌 폴더이고, root 소유이며, 다른 누구도 쓸 수 없을 때만 사용합니다. 캐시 폴더가 없으면 모드 0700으로 만들고, 그 밖의 경우에는 그곳에서 무엇이든 읽거나 삭제하거나 다운로드하기 전에 중단합니다. 카탈로그의 이미지를 가져오기 전에, 카탈로그에 더 이상 없는 캐시의 이미지 파일과 그 부분 다운로드를 삭제합니다.

.flock 파일이 지정하는 하드웨어와 다른 하드웨어용 --image는 계획에 경고가 나온 뒤 쓰입니다. 그 디바이스는 앱을 실행하지 못합니다. IronFlockOS를 실행하는 디바이스에서는 계획이 os drives와 같은 경고를 합니다. --allow-internal을 사용하면 계획은 드라이브가 내부 디스크라고 경고합니다.

--yes는 질문에 예로 답합니다. 터미널이 없고(파이프, 스크립트) --yes도 없으면 명령은 묻지 않고 종료 코드 4로 끝납니다. --json도 아무것도 묻지 않으므로, 드라이브에 쓰려면 --yes가 필요합니다. --json을 사용하면 계획이 출력되지 않습니다. stderr에는 진행 상황 이벤트만 나오고, 경고는 결과에 들어갑니다. 질문과 확인과 출력과 JSON을 참조하십시오.

WiFi

디바이스는 .flock 파일이 지정하는 WiFi에 연결합니다. --wifi-ssid로 다른 네트워크를 지정할 수 있습니다. IronFlockOS는 암호 문구가 있는 WiFi에만 연결하므로, --wifi-ssid와 --wifi-password-file은 항상 함께 지정합니다. 암호 문구는 파일이나 파이프에서 가져오며, ps와 셸 기록에 나타나는 명령줄에서는 절대 받지 않습니다. 명령은 암호 문구를 어디에도 출력하지 않습니다. 드라이브에 있는 .flock 파일의 사본은 wlanssid와 password에 네트워크를 지정합니다.

참고: 암호 문구를 /dev/stdin으로 전달하면 stdin이 터미널이 아니므로 명령이 질문할 수 없습니다. --yes를 추가하십시오.

설치 USB 스틱

--installer를 사용하면 드라이브는 UEFI를 사용하는 PC(amd64-efi, arm64-efi)용 설치 USB 스틱이 됩니다. 설치 이미지는 ironflock os images --variant installer로 나열합니다. 스틱에는 해당 하드웨어용 이미지가 여러 개 들어 있습니다. 스틱의 installer.conf는 설치할 이미지(payload, 3단계에서처럼 고른 이미지)를 지정하며, 지정한 --installer-* 플래그를 담고 있습니다. PC가 스틱으로 시작하면 설치 프로그램은 다음을 수행합니다:

1. --installer-disk에 따라 디스크를 고릅니다: 가장 큰 디스크(기본값), 디스크 /dev/<name>, 또는 ID가 by-id:<id>인 디스크. USB 디스크에는 --installer-allow-usb yes를 지정했을 때만 씁니다.
2. --installer-confirm no가 아니면 쓰기 전에 PC의 콘솔에서 묻습니다.
3. 그 디스크에 이미지와 디바이스의 .flock 파일을 씁니다.
4. PC의 전원을 끄거나(기본값), --installer-after reboot를 지정했으면 재시작합니다.

스틱을 빼고 PC를 내부 디스크로 시작하십시오. 디바이스는 첫 부팅 때 등록됩니다.

경고: --installer-confirm no로 쓴 스틱은 그 스틱으로 시작하는 모든 PC의 디스크를 묻지 않고 지웁니다. 이런 스틱에는 표시를 해 두고 다른 머신에서 멀리 보관하십시오.

스틱 없이 실행 중인 머신의 Linux를 교체하려면 Linux를 IronFlockOS로 교체를 참조하십시오.

다운로드한 이미지 파일

--image-file은 미리 다운로드한 이미지 파일을 씁니다. 예를 들어 카탈로그의 이미지 파일을 다운로드할 수 없는 머신에서 사용합니다. 파일의 주소는 os images --json의 url에서 확인하십시오. 파일은 크기와 SHA-256이 카탈로그에 있는 해당 이미지의 값과 같을 때만 쓰입니다.

이때도 파일을 확인하려면 서명된 카탈로그가 필요합니다. 명령은 카탈로그를 가져오거나, 다운로드 서버에 도달할 수 없으면 같은 다운로드 베이스의 카탈로그가 마지막으로 검증되었을 때 보관한 사본을 사용합니다. 이 사본은 사용자별로 보관되므로, root로 실행하면 root의 사본을 사용합니다. 자체 서버도 사용할 수 있습니다. 다른 다운로드 베이스(--download-base 또는 IRONFLOCK_DL_BASE)를 지정하면 명령은 카탈로그를 <download base>/ironflockos/manifest.json에서, 이미지 파일을 <download base>/ironflockos/<version>/<file>에서 가져옵니다.

참고: 파일은 쓰는 동안 한 번 더 읽히며, 그 SHA-256은 쓰기가 끝난 뒤에야 다시 확인됩니다. 다른 사용자가 변경할 수 없는 곳에 파일을 보관하십시오.

가상 머신용 이미지 파일

--output <file>은 이미지와 디바이스의 파일을 드라이브 대신 일반 파일에 씁니다. 가상 머신이 자신의 디스크로 사용해 시작하는 raw 디스크 이미지입니다. 이미지, 그 검사, IRONFLOCKOS의 파일은 드라이브에 쓸 때와 같습니다. 드라이브를 찾거나 언마운트하거나 열지 않으므로 root 권한이 필요 없습니다. --image, --image-file, --installer와 그 플래그, --wifi-ssid는 드라이브에서와 똑같이 동작합니다.

• 크기 — 계획에 파일과 그 크기, 즉 압축을 푼 이미지의 크기가 나옵니다. 이미지를 아직 다운로드해야 하면 이 줄은 다운로드 뒤에 나옵니다.
• 질문 — 새 파일은 아무것도 지우지 않으므로 명령은 묻지 않습니다. 이미 있는 파일은 교체됩니다. 계획에 그 사실이 나오고, 명령이 먼저 묻습니다.
• 먼저 다른 이름으로 — 이미지는 같은 폴더의 새 파일 <file>.<number>.part에 들어갑니다. 이 파일은 이미지 전체를 담고, 다시 읽어 확인되고, IRONFLOCKOS 파티션에 디바이스의 파일이 들어간 뒤에야 <file>이라는 이름을 받습니다. 쓰기가 실패하거나 중단되면 .part 파일이 제거되며, 그 이름에는 아무것도 없거나 원래 있던 파일이 변경되지 않은 채 남습니다. kill -9나 전원 차단이 일어나면 .part 파일이 남을 수 있습니다.
• 비공개 — 이 파일에는 .flock 파일과 마찬가지로 디바이스의 시크릿이 들어 있습니다. 파일은 모드 0600을 받으며, 더 넓은 모드의 파일을 교체할 때도 마찬가지입니다.
• 스파스 파일 — 이미지에 0으로만 된 블록 전체(4 MiB 블록)가 있는 곳에서는, 홀을 지원하는 파일 시스템이면 파일에 홀이 생깁니다. 읽은 내용은 같고 공간은 덜 차지합니다.

# 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.

이미지에는 IRONFLOCKOS 파티션과, IronFlockOS가 번갈아 업데이트하는 두 시스템 슬롯 중 첫 번째 슬롯(슬롯 A)이 들어 있습니다. 첫 부팅 때 IronFlockOS는 슬롯 A와 같은 크기의 슬롯 B를 만들고, 디스크의 나머지 공간에 데이터 파티션 /data를 만듭니다. 가상 머신이 이 파일로 처음 시작하기 전에 파일을 늘리십시오. base는 최소 10 GiB, nvidia는 최소 18 GiB입니다. 늘어난 부분은 0이며, 파일 시스템은 이를 홀로 보관합니다. raw 디스크를 받는 하이퍼바이저는 파일을 그대로 사용합니다. 다른 형식이 필요하면 늘린 파일을 변환하십시오. 예: qemu-img convert -f raw -O qcow2 device.img device.qcow2.

amd64-efi와 arm64-efi의 이미지는 QEMU에서 시작되지만, Raspberry Pi(rpi-arm64)의 이미지는 시작되지 않습니다. KVM과 ovmf 패키지(Debian, Ubuntu)의 UEFI 펌웨어가 있는 Linux에서 amd64-efi는 다음과 같이 시작합니다:

# 파일을 늘리고, 펌웨어의 변수를 복사하고, 머신 시작
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은 첫 번째 시리얼 포트를 터미널에 연결합니다. GRUB과 커널이 이곳에 출력합니다. Ctrl-A X를 누르면 QEMU가 끝납니다.
• -device i6300esb는 워치독이며, IronFlockOS는 이를 통해 멈춘 머신을 재시작합니다.
• -netdev user는 머신에 호스트의 네트워크를 제공하며, 디바이스는 이 네트워크로 IronFlock에 도달합니다.
• KVM이 없으면(/dev/kvm이 없거나 호스트의 아키텍처가 다르면) -accel kvm을 빼고 -cpu max를 사용하십시오. 이 경우 QEMU가 머신을 에뮬레이션하므로 훨씬 느립니다.

arm64-efi는 qemu-system-aarch64 -machine virt와 qemu-efi-aarch64 패키지의 펌웨어(/usr/share/AAVMF/AAVMF_CODE.fd와 AAVMF_VARS.fd의 사본)로, 워치독 없이 시작합니다. Apple silicon Mac에서는 Homebrew의 QEMU가 -accel hvf -cpu host와 펌웨어 /opt/homebrew/share/qemu/edk2-aarch64-code.fd, 그리고 edk2-arm-vars.fd의 사본으로 시작합니다.

예시

# .flock 파일의 하드웨어용 기본 이미지를 USB 스틱에 쓰기
sudo ironflock os flash -c device.flock -d /dev/sdb
# PC에 NVIDIA 이미지를 설치하는 설치 USB 스틱 쓰기
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# WiFi "Workshop"에 연결하는 디바이스용 SD 카드 쓰기
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# Mac에서 스틱 쓰기
sudo ironflock os flash -c device.flock -d /dev/disk4

결과

계획과 진행 상황은 stderr에 나오며, 마지막 줄이 결과입니다. 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.

Mac에서 먼저 root 없이, 그다음 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.

--json을 사용한 경우. 여기서는 설치 USB 스틱입니다(--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":[]}

--output을 사용하면 결과에 drive 대신 output이 있습니다. 예: "output":{"file":"/home/anna/device.img","replaced":true}.

거부하는 경우

종료 코드 3, 아무것도 쓰지 않음:

• 드라이브가 os drives가 거부하는 드라이브인 경우. 오류 메시지에 이유가 나오며, --yes로도 달라지지 않습니다. 유일한 예외는 이 머신의 내부 디스크입니다. --drive가 내부 디스크를 지정하면 --allow-internal이 그 디스크에 쓰며, 이 플래그로 드라이브에 쓸 수 있게 되는 경우 오류 메시지가 이 플래그를 알려 줍니다. 이 플래그는 다른 거부를 해제하지 않으며, 질문에 답하지도 않습니다.
• 계획과 쓰기 사이에 드라이브가 바뀌었거나, 그 시점에 거부되는 경우. 오류 메시지가 무엇이 바뀌었는지 알려 줍니다.
• 드라이브를 열 때 사용 중인 경우: 계획에 없던 파일 시스템이 마운트되어 있거나, 파일 시스템이 언마운트되지 않거나, 프로그램이 드라이브를 잡고 있음.
• root로 실행되지 않는 경우(macOS에서는 드라이브의 raw 디바이스에 쓸 수 있는 사용자로도 실행되지 않는 경우). 오류 메시지가 sudo를 붙인 명령줄을 알려 줍니다.
• --output을 사용할 때: 무엇이든 읽거나 가져오기 전에, 그 이름이 일반 파일이 아니거나(디바이스, 폴더, 이름 있는 파이프, 또는 모든 심볼릭 링크) 그 폴더가 없는 경우. 새 파일을 받을 수 없는 폴더(권한 없음, 읽기 전용 파일 시스템)는 계획 뒤, 다운로드 전에 거부됩니다. 계획에서 새 파일이라고 했는데 이미지를 쓰는 동안 그 이름을 차지한 파일은 교체되지 않습니다.

종료 코드 2, 잘못된 명령줄:

• --drive도 --output도 없는 경우(--allow-internal이 있어도 마찬가지). --drive나 --allow-internal과 함께 쓴 --output, 이름이 없거나 -인 --output. -c의 .flock 파일이나 --image-file의 파일을 지정하는 --output.
• --installer 없이 쓴 --installer-* 플래그, 또는 설치 프로그램이 받지 않는 값.
• --wifi-password-file 없이 쓴 --wifi-ssid, 또는 그 반대.
• 어떤 하드웨어용인지 나와 있지 않은 .flock 파일. 이때는 --image로 이미지를 고르십시오.
• 카탈로그에 없는 이미지, 그 이미지를 담고 있지 않은 설치 USB 스틱, 또는 설치 USB 스틱이 없는 하드웨어.
• --host를 사용할 때의 --image-file과 --output. --host는 이미지 파일을 다른 머신에 복사하지 않으며, 파일을 가져오지도 않습니다. 이 명령은 --host 없이 여기서 실행하거나, 머신에서 직접 실행하십시오. .flock 파일과 암호 문구 파일은 함께 전달됩니다.

종료 코드 4: 질문에 아니요로 답했거나(Enter만 누르거나 Esc), 질문할 수 없는데 --yes가 지정되지 않음.

종료 코드 1, 명령이 실패함:

• .flock 파일이나 암호 문구 파일이 올바른 파일이 아니거나, 이미지 파일이 카탈로그의 파일이 아닌 경우.
• os images가 실패하는 이유로 카탈로그를 사용할 수 없는 경우.
• 다운로드, 쓰기 또는 다시 읽어 확인하는 단계가 실패하는 경우. 첫 블록 이후에 쓰기가 실패하면(I/O 오류, 이미지보다 작은 드라이브) 이제 드라이브에 이미지의 일부만 있어 아무것도 시작할 수 없다고 알려 줍니다. 다시 쓰십시오.
• 이미지를 드라이브에 쓰고 다시 읽어 확인했지만, .flock 파일을 IRONFLOCKOS에 쓸 수 없었던 경우. 이 파일이 없으면 디바이스가 등록되지 않습니다. 같은 명령으로 둘 다 다시 쓰십시오.
• --output을 사용할 때: 파일 시스템이 가득 찼거나, 디바이스의 파일을 이미지에 넣을 수 없거나, 이미지를 쓰는 동안 .part 파일의 항목이 교체된 경우. 이때 그 이름은 이전 상태 그대로입니다.

종료 코드 130: 이미지를 다운로드하거나 쓰거나 다시 읽는 동안 Ctrl-C를 누른 경우. 중단된 다운로드는 아무것도 쓰지 않았으며, 같은 명령으로 이어받습니다. 쓰기나 다시 읽기는 다음 블록에서 멈추며, 오류 메시지가 드라이브에 무엇이 남았는지 알려 줍니다. 마지막 블록까지 다시 읽은 뒤에는 명령이 마지막 짧은 단계를 마치고 0으로 끝납니다. Ctrl-C를 한 번 더 누르면 명령이 즉시 끝나며, --output을 사용했다면 .part 파일이 남을 수 있습니다.