incus-contrib/incusos

IncusOS Tools

Scripts for building IncusOS installation media and seed configurations.

Overview

Script	Purpose
incusos-iso	Build customized IncusOS ISO/IMG images using the flasher-tool
incusos-seed	Generate seed archives (tar or FAT) for installation customization

Both scripts support automatic client certificate injection from the local Incus installation, so the freshly installed system is immediately manageable.

Prerequisites

• Go 1.21+ -- for installing the flasher-tool
• flasher-tool -- the official IncusOS image builder

go install github.com/lxc/incus-os/incus-osd/cmd/flasher-tool@latest
export PATH="${GOPATH:-$HOME/go}/bin:$PATH"

Optional:

• incus -- for automatic client certificate detection
• mtools / dosfstools -- for creating FAT seed images
• jq or python3 -- for parsing the CDN index (cross-architecture builds)
• curl -- for downloading images

incusos-iso

Wrapper around the official flasher-tool that adds:

• Cross-architecture builds -- build aarch64 images on x86_64 and vice versa
• Automatic seed generation -- no need to manually create seed files
• Client certificate injection -- auto-detects your local Incus certificate
• Batch mode -- generate all common ISO variants in one command
• Sensible defaults -- minimal flags needed for common use cases

Quick Start

# Build a default IncusOS ISO for the current architecture
./incusos-iso

# Incus with default configuration (ZFS pool, bridge, port 8443)
./incusos-iso --defaults

# Operations Center for aarch64
./incusos-iso --arch aarch64 --app operations-center --defaults

# Build a USB image instead of ISO
./incusos-iso --format img --defaults

# Generate all variants (2 arches x 2 apps x 2 default modes = 8 images)
./incusos-iso --batch

# Preview what would be built
./incusos-iso --batch --dry-run

Options Reference

-a, --arch ARCH          x86_64 or aarch64 (default: auto-detect)
-A, --app APP            incus or operations-center (default: incus)
-d, --defaults           Apply default config (ZFS pool, bridge, port 8443)
-c, --cert FILE          Client certificate PEM file (default: auto-detect)
    --no-cert            Skip certificate injection
-F, --format FORMAT      iso or img (default: iso)
-o, --output FILE        Output filename (default: auto-generated)
-C, --channel CHANNEL    stable or testing (default: stable)
-s, --seed FILE          Use pre-built seed tar (skip seed generation)
-i, --image FILE         Use local base image (skip CDN download)
-b, --batch              Generate all common variants
    --batch-arches LIST  Architectures for batch (default: x86_64,aarch64)
    --batch-apps LIST    Apps for batch (default: incus,operations-center)
    --output-dir DIR     Output directory for batch (default: .)
    --disk-target ID     Target disk pattern (e.g. "virtio-*")
    --force-install      Overwrite existing installation
    --force-reboot       Auto-reboot after installation
    --missing-tpm        Allow install without TPM 2.0
    --missing-secureboot Allow install without Secure Boot
    --hostname NAME      Set system hostname
    --dry-run            Show what would happen
-q, --quiet              Suppress info output
-h, --help               Full help text
-V, --version            Show version

Output Naming Convention

Auto-generated filenames follow the pattern:

incusos-{app}-{defaults|bare}-{arch}.{iso|img}

Examples:

• incusos-incus-defaults-x86_64.iso
• incusos-ops-center-bare-aarch64.iso
• incusos-incus-defaults-x86_64.img

Batch Mode Matrix

With --batch, the following variants are generated:

#	Architecture	Application	Defaults	Filename
1	x86_64	Incus	yes	incusos-incus-defaults-x86_64.iso
2	x86_64	Incus	no	incusos-incus-bare-x86_64.iso
3	x86_64	Ops Center	yes	incusos-ops-center-defaults-x86_64.iso
4	x86_64	Ops Center	no	incusos-ops-center-bare-x86_64.iso
5	aarch64	Incus	yes	incusos-incus-defaults-aarch64.iso
6	aarch64	Incus	no	incusos-incus-bare-aarch64.iso
7	aarch64	Ops Center	yes	incusos-ops-center-defaults-aarch64.iso
8	aarch64	Ops Center	no	incusos-ops-center-bare-aarch64.iso

Customize with --batch-arches and --batch-apps:

# Only x86_64 Incus variants
./incusos-iso --batch --batch-arches x86_64 --batch-apps incus

incusos-seed

Generates IncusOS seed archives containing the YAML configuration files that customize an IncusOS installation. Output can be:

• tar archive (default) -- for use with flasher-tool --seed
• FAT image -- for use as an external SEED_DATA partition/disk

Quick Start

# Standalone Incus with defaults and auto-detected certificate
./incusos-seed --defaults

# Operations Center seed
./incusos-seed --app operations-center --defaults --cert ~/.config/incus/client.crt

# Cluster node (no defaults) targeting virtio disks
./incusos-seed --disk-target 'virtio-*' --force-install --force-reboot

# FAT image for external boot media
./incusos-seed --format fat --defaults --output seed.img

# Preview generated YAML without creating files
./incusos-seed --defaults --dry-run

Options Reference

-A, --app APP            incus or operations-center (default: incus)
-d, --defaults           Apply default configuration
-c, --cert FILE          Client certificate PEM file (default: auto-detect)
    --no-cert            Skip certificate injection
-o, --output FILE        Output file (default: incusos-seed.tar)
-f, --format FORMAT      tar or fat (default: tar)
    --fat-size SIZE      FAT image size in MiB (default: 10)
    --disk-target ID     Target disk pattern
    --force-install      Overwrite existing installation
    --force-reboot       Auto-reboot after installation
    --missing-tpm        Allow install without TPM 2.0
    --missing-secureboot Allow install without Secure Boot
    --hostname NAME      Set hostname
    --domain NAME        Set domain
    --dns SERVERS        Comma-separated DNS servers
    --channel CHANNEL    stable or testing (default: stable)
    --auto-reboot        Auto-reboot for updates
    --dry-run            Preview YAML output
-q, --quiet              Suppress info output
-h, --help               Full help text
-V, --version            Show version

Seed Files Reference

The following YAML files are generated inside the archive:

File	Always	Description
install.yaml	yes	Installation target, security, reboot settings
applications.yaml	yes	Application selection
incus.yaml	when app=incus	Incus preseed (defaults, certificates)
operations-center.yaml	when app=ops-center	Operations Center config
network.yaml	when network opts set	Hostname, DNS, static IP
update.yaml	when non-default	Update channel, auto-reboot

Using the FAT Image (SEED_DATA)

The FAT output format creates a small disk image labeled SEED_DATA that can be attached to a VM as a secondary disk. IncusOS detects this label at boot and reads the seed configuration from it.

This is useful for the "pristine image" workflow:

1. Download one uncustomized IncusOS ISO
2. Generate per-node seed images with incusos-seed --format fat
3. Boot each VM with both the ISO and the node-specific seed image

# Generate seeds for three cluster nodes
for i in 1 2 3; do
    ./incusos-seed --format fat \
        --hostname "node-${i}" \
        --disk-target 'virtio-*' \
        --force-install \
        --output "seed-node-${i}.img"
done

Client Certificate Auto-Detection

Both scripts automatically look for a client certificate in this order:

1. incus remote get-client-certificate (if the incus CLI is installed)
2. ~/.config/incus/client.crt
3. ~/snap/incus/common/config/client.crt
4. ~/.config/lxc/client.crt

Override with --cert FILE or disable with --no-cert.

After Installation

With an injected certificate, the remote is already trusted:

incus remote add my-server <ip-address>
incus remote list

For web UI access, export a PKCS#12 bundle and import it into your browser:

openssl pkcs12 -export \
    -inkey ~/.config/incus/client.key \
    -in ~/.config/incus/client.crt \
    -out ~/.config/incus/client.pfx

Examples

See the examples/ directory for sample seed configurations:

• incus-standalone.yaml -- Single Incus server with defaults
• incus-cluster-node.yaml -- Cluster node (no defaults)
• ops-center.yaml -- Operations Center
• network-static.yaml -- Static network configuration

Security Notes

• TPM 2.0 and Secure Boot are required by default. Use --missing-tpm and --missing-secureboot only for lab environments or VMs that lack these features.
• All storage pools are automatically encrypted by IncusOS.
• Retrieve encryption recovery keys after installation with: incus admin os system security show
• Keep recovery keys safe -- they are needed if TPM state changes.