FLAKE-CTL-FIRECRACKER-PULL(8)

💅 NAME

ok so this is the flake-ctl firecracker pull page — like, the whole manual entry is FLAKE-CTL-FIRECRACKER-PULL(8), bestie, and what it does is Fetch firecracker image. that's the vibe. that's the whole assignment. 🎀

---

✨ SYNOPSIS

USAGE:
    flake-ctl firecracker pull [OPTIONS] --name <NAME> <--kis-image <KIS_IMAGE>|--rootfs <ROOTFS>|--kernel <KERNEL>>

OPTIONS:
    --force
    --initrd <INITRD>
    --kernel <KERNEL>
    --kis-image <KIS_IMAGE>
    --name <NAME>
    --rootfs <ROOTFS>

like yes, --name is mandatory (obvi) and then you gotta pick exactly one of --kis-image, --rootfs, or --kernel. pick one. one. 💅

---

🌸 DESCRIPTION

okay so picture this: you're pulling the components of a firecracker image from whatever location you gave it, and they land in /var/lib/firecracker/images/NAME on your local machine. cute. the registry it pulls into is detected from the caller — main character energy, it just knows. 🦋

and here's the slay part: if you call it as any user other than root, the image goes into that user's own rootless registry instead, down at ~/.config/flakes/firecracker/images/NAME. no root, no problem. 🫶

once it's done, you can list the available firecracker images like this:

$ tree /var/lib/firecracker/images

and it's giving a file structure like this example:

/var/lib/firecracker/images
└── myImage
     ├── initrd
     ├── kernel
     └── rootfs

and P.S. — an image you pulled with --kis-image carries an extra source_checksum file, so go read UPDATE CHECK below, it's important i promise 😭

---

🔥 UPDATE CHECK

so if you pulled with the --kis-image option, your image is enrolled in a checksum-based update check. here's the tea: the archive you hand to --kis-image must come with a checksum file sitting at the same location, named exactly like the archive plus a .sha256 suffix. so for an archive named foo.tar.xz, the checksum file is expected at foo.tar.xz.sha256. no file? the pull gets rejected with an error. periodt. 💀

that checksum does double duty: it verifies the downloaded archive, and it gets stored alongside the image as source_checksum. and then, when you pull an image under a name that already exists in the registry, it behaves like this:

• the checksum file is fetched and compared against the source_checksum record of the registered image. if both match, the image is up to date 💖 nothing is downloaded, nothing in the registry is touched, and the command just succeeds. lowkey the best outcome.
• if the checksums differ, the latest version of the image is fetched and replaces the image in the registry. glow-up. ✨

and for images registered by a --rootfs/--kernel pull? those provide no such reference, so they're not update checked. pulling into an existing name stays an error for those bad boys unless you pass --force. sorry babe 🎀

---

👑 OPTIONS

• --force — force pulling the image even if it already exists. this will wipe existing data for the provided identifier 😭 the image is fetched from scratch, and no update check against an existing image of the same name is done. it's giving scorched earth. use with intent.
• --initrd <INITRD> — single initrd image to pull into the local image store 🌸
• --kernel <KERNEL> — single kernel image to pull into the local image store ⭐
• --kis-image <KIS_IMAGE> — a firecracker image built by KIWI as kis image type, to pull into the local image store. this means the file behind KIS_IMAGE is expected to be a tarball containing the KIS components: rootfs-image, kernel, and an optional initrd. and a checksum file named like KIS_IMAGE plus a .sha256 suffix must be available at the same location — see UPDATE CHECK 💅
• --name <NAME> — image name, used as the local identifier 🏷️
• --rootfs <ROOTFS> — single rootfs image to pull into the local image store 🌈

---

🧚 ENVIRONMENT

• FLAKE_ALLOW_INSECURE_TRANSPORT — okay so listen 🙈 the images pulled here provide the root filesystem and the kernel of a virtual machine, so they're only fetched via https. if your image can only be reached through a transport that provides no integrity and no authenticity of the server — think plain http — setting this variable allows you to use it.

⚠️ only do this if the connection to the image source can be trusted. like, genuinely. bestie. i'm serious. 🫶

---

💜 EXAMPLE

$ flake-ctl firecracker pull --name myImage --kis-image \
    https://download.opensuse.org/repositories/home:/marcus.schaefer:/delta_containers/images/firecracker-basesystem.x86_64.tar.xz

$ flake-ctl firecracker pull --name firecore \
    --rootfs https://s3.amazonaws.com/spec.ccfc.min/ci-artifacts/disks/x86_64/ubuntu-18.04.ext4 \
    --kernel https://s3.amazonaws.com/spec.ccfc.min/img/quickstart_guide/x86_64/kernels/vmlinux.bin

two pulls, two vibes: one kis image, one rootfs + kernel combo. slay. 🔥

---

🍓 AUTHOR

Marcus Schäfer 💫

🎀 COPYRIGHT

(c) 2022, Elektrobit Automotive GmbH and (c) 2023, Marcus Schäfer — respect the og authors fr fr

---

okay that's the whole page, bestie, mwah 💋 this was flake-ctl-firecracker-pull(8) — the manual page, version 8, dated today-ish, brought to you by the fine folks above. go pull some images. iykyk 🌟