Last updated: 2026-02-23

genpack-install CLI Reference

Overview

genpack-install is a tool for deploying SquashFS system images generated by genpack to physical disks, ISO images, and ZIP archives.

• GitHub: wbrxcorp/genpack-install

genpack-install [options] [system_image]

Root privileges are required.

Options

Positional Arguments

Required in self-update mode. Optional in --disk, --cdrom, and --zip modes — when omitted, the currently installed system image is used.

Named Options

Operation Modes

genpack-install has 4 operation modes depending on the combination of arguments.

Self-Update (arguments only, no mode options)

genpack-install <system_image>

Atomically updates the system image of a running system. This mode is used when none of --disk, --cdrom, or --zip are specified.

Update procedure:

1. Locate the current system image path (boot partition’s system.img or data partition’s system)
2. Validate the new system image
3. Update boot files (kernel, initramfs, bootloader)
4. Atomic rename swap:
   • Remove existing system.old (if present)
   • Copy new image as system.new
   • Rename current image to system.cur (preserved for rollback)
   • Rename system.new to the original image path
   • Execute sync

On failure, automatic recovery from system.cur is attempted.

Disk Installation (--disk)

genpack-install --disk=<device path> [options] [system_image]
genpack-install --disk=list

Installs a system image to a physical disk.

Specifying --disk=list shows a list of installable disks. Read-only devices, mounted devices, and devices smaller than 4GiB are excluded.

Partitioning:

• Automatic MBR/GPT selection: MBR is chosen if the disk is 2TiB or smaller with 512-byte logical sectors; GPT is used otherwise
• --gpt: Force GPT regardless of conditions
• --superfloppy: No partition table; formats the entire disk as FAT32 (images under 4GiB only)

Normal mode (with partitioning) layout:

1. Boot partition (FAT32): Stores kernel, initramfs, bootloader, and system images under 4GiB
2. Data partition (Btrfs): Stores system images 4GiB or larger. Labeled data-{boot partition UUID}

Specifying --no-esp prevents the boot partition from being marked as ESP (EFI System Partition). Use this when certain bootloaders dislike the ESP flag (only effective with MBR).

A confirmation prompt is shown before installation. Use -y to skip.

ISO Image Creation (--cdrom)

genpack-install --cdrom=<output path> [--label=<label>] [system_image]

Creates a bootable ISO9660 image. Requires xorriso (libisoburn) to be installed.

• BIOS boot: El Torito (if eltorito-bios.img exists)
• EFI boot: Appended EFI partition (if eltorito-efi.img exists)
• When both images exist, a dual-boot ISO is generated

When --label is omitted, the volume label defaults to GENPACK.

ZIP Archive Creation (--zip)

genpack-install --zip=<output path> [system_image]

Creates a ZIP archive containing the system image and boot files.

Files included in the ZIP:

• system.img — System image
• system.cfg — System configuration (when --system-cfg is specified)
• system.ini — System configuration (when --system-ini is specified)
• Raspberry Pi boot files (for Raspberry Pi images)

Bootloader

genpack-install uses GRUB as the bootloader. Bootloader files are searched in the following order:

1. /usr/lib/genpack-install/ inside the system image
2. /usr/local/lib/genpack-install/ on the host
3. /usr/lib/genpack-install/ on the host

Installed files:

• EFI bootloader: boot*.efi files are copied to efi/boot/
• BIOS bootloader: Installed when boot.img, core.img, and grub.cfg exist and grub-bios-setup is available

Supported architectures:

Raspberry Pi support:

When the system image contains boot/bootcode.bin, it is treated as a Raspberry Pi image. All files under the boot/ directory are copied to the boot partition, and the root= parameter in cmdline.txt is rewritten to root=systemimg:auto.

grub.cfg system.img search logic:

1. If system.img exists on the boot partition, use it
2. Otherwise, search for a partition labeled data-{boot partition UUID}
3. Then search for label d-{boot partition UUID}
4. As a last resort, infer from boot partition number (partition 1 → try partition 2)

Partition Layout

Boot Partition (FAT32)

• Bootloader (GRUB EFI files, BIOS images)
• Kernel (boot/kernel) and initramfs (boot/initramfs)
• grub.cfg
• system.cfg / system.ini (when specified)
• System images under 4GiB: Stored as system.img

Boot partition size is max(4, image_size_gib * 3 + 1) GiB when the system image is under 4GiB, or 1 GiB when 4GiB or larger.

Data Partition (Btrfs)

• Not created when --superfloppy is used
• Label: data-{boot partition UUID}
• System images 4GiB or larger: Stored as system

System Image Validation

genpack-install validates system images before installation:

1. A .genpack/ directory must exist
2. One of the following must be satisfied:
   • boot/kernel and boot/initramfs exist (standard images)
   • boot/bootcode.bin exists (Raspberry Pi images)

Upon passing validation, the contents of .genpack/artifact and .genpack/variant are displayed.