Docs: reciso

Documentation

reciso

Create bootable UEFI ISOs from kernel, initramfs, and EROFS rootfs.

Overview

reciso builds UEFI bootable media with systemd-boot, and can include prebuilt UKIs or build them inline. By default the rootfs and live overlay images are appended to the ISO as GPT partitions, which the live initramfs mounts directly; --live-payload-layout iso-files keeps them as files under live/ instead. A .sha512 checksum is written next to the ISO unless --no-checksum.

Usage

Options as printed by reciso --help:

Text
Create bootable UEFI ISOs from kernel + initramfs + rootfs

Usage: reciso [OPTIONS] --kernel <KERNEL> --initrd <INITRD> --rootfs <ROOTFS> --label <LABEL> --output <OUTPUT> --build-uki <BUILD_UKIS>

Options:
  -k, --kernel <KERNEL>
          Path to kernel image (vmlinuz)

  -i, --initrd <INITRD>
          Path to initramfs image

  -r, --rootfs <ROOTFS>
          Path to rootfs image (EROFS)

  -l, --label <LABEL>
          ISO volume label

  -o, --output <OUTPUT>
          Output ISO path

      --build-uki <BUILD_UKIS>
          A boot entry's UKI, built inline (at least one). Format: "name:extra_cmdline:filename" Example: "Emergency:emergency:myos-emergency.efi"

      --extra-file <EXTRA_FILES>
          Add an extra file to the ISO. Format: "src:dst" Example: "/tmp/initramfs-installed.img:boot/initramfs-installed.img"

      --overlay-image <OVERLAY_IMAGE>
          Live overlay payload image (EROFS) to include

      --os-name <OS_NAME>
          OS name for the boot menu (e.g., "LevitateOS")

      --os-id <OS_ID>
          OS identifier (e.g., "levitateos")

      --os-version <OS_VERSION>
          OS version (e.g., "1.0")

      --no-checksum
          Skip checksum generation

      --live-payload-layout <LAYOUT>
          Layout for live payloads (only `iso-files`, the default)

          Possible values:
          - iso-files: Payloads are files under `live/` in the ISO filesystem
          
          [default: iso-files]

      --systemd-boot <SYSTEMD_BOOT>
          systemd-boot UEFI binary (default: the build host's)
          
          [default: /usr/lib/systemd/boot/efi/systemd-bootx64.efi]

  -q, --quiet
          Quiet mode - only print errors

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

EXAMPLES:
    # Boot entries, one UKI each (format: name:extra_cmdline:filename)
    reciso -k vmlinuz -i initramfs.img -r rootfs.erofs -l MYISO --build-uki 'Normal::myos.efi' --build-uki 'Emergency:emergency:myos-emergency.efi' --os-name MyOS --os-id myos --os-version 1.0 -o output.iso

    # With live overlay image (EROFS)
    reciso -k vmlinuz -i initramfs.img -r rootfs.erofs -l MYISO --build-uki 'Normal::myos.efi' --overlay-image live-overlay.erofs -o output.iso

REQUIREMENTS:
    - systemd-boot (dnf install systemd-boot)
    - xorriso (dnf install xorriso)
    - mtools (dnf install mtools)
    - ukify (dnf install systemd-ukify)

Requirements

  • systemd-boot
  • xorriso
  • mtools
  • ukify (only when building UKIs inline)

See Also