4.3 KiB

Raw Blame History

IncusOS ISO Download & Customization Methods

Note: This document was the original research note that started this repository. For the actual automation scripts, see ../incusos/README.md.

To automate the generation and download of customized IncusOS ISO files, you have two technical paths: using the official flasher-tool (the recommended CLI method for automation) or scripting the REST API used by the web customizer.

Method 1: The flasher-tool (Recommended for Scripts)

The Incus team provides a dedicated command-line utility specifically for automated image generation. It connects to the Linux Containers CDN to fetch the latest builds and applies your customizations locally.

Installation:

go install github.com/lxc/incus-os/incus-osd/cmd/flasher-tool@latest

Sample Automation Script:

This script generates a customized ISO for an x86_64 cluster node with your local client certificate already trusted.

#!/bin/bash
# automated-incusos-build.sh

# 1. Fetch your local Incus client certificate
CLIENT_CERT=$(incus remote get-client-certificate)

# 2. Define your customized seed in JSON format
# This example preps a node to join a cluster (apply_defaults: false)
cat <<EOF > cluster-node-seed.json
{
  "apply_defaults": false,
  "preseed": {
    "certificates": []
  }
}
EOF

# 3. Run the flasher tool to build the ISO
# -f: format (iso or img)
# -s: path to your seed file
# -o: output filename
flasher-tool -f iso -s cluster-node-seed.json -o my-custom-node.iso

Method 2: Scripting the Web Customizer API

If you prefer to use the web backend directly via curl, you must POST a configuration payload to the generator endpoint. The web customizer is an SPA that communicates with a backend to stream a compressed image.

Technical Logic:

The backend accepts a JSON object that mimics the "Seed" structures. One critical detail is that the web customizer streams gzipped data which the browser typically decompresses on the fly; when using curl, you must ensure you handle the output stream correctly.

Sample curl Download Script:

#!/bin/bash

# Configuration
ARCH="x86_64"           # x86_64 or aarch64
APP="incus"             # incus, operations-center, or migration-manager
USAGE="install"         # install (on disk) or live (run from media)
CERT=$(incus remote get-client-certificate | sed ':a;N;$!ba;s/\n/\\n/g')

# Generate the JSON payload for the web customizer
PAYLOAD=$(cat <<EOF
{
  "format": "iso",
  "architecture": "$ARCH",
  "usage": "$USAGE",
  "applications": ["$APP"],
  "incus": {
    "apply_defaults": true,
    "preseed": {
      "certificates": []
    }
  }
}
EOF
)

# POST to the customizer backend (Note: The URL may vary by build/release)
curl -X POST https://incusos-customizer.linuxcontainers.org/api/generate \
     -H "Content-Type: application/json" \
     -d "$PAYLOAD" \
     --output incus-os-latest.iso

Key Reference for Customization Settings

When scripting either tool, use these field values to generate the "flavors" you need for your lab:

Selection	Value Options	Description
Architecture	x86_64, aarch64	Target CPU type.
Applications	incus, operations-center, migration-manager	Can be an array for multiple apps.
Defaults	true or false	Set to false for cluster nodes to avoid conflicts.
Security	missing_tpm: true	Use if hardware/VM lacks a TPM 2.0 module.

Advanced Automation Tip: Using a "Pristine" Image

If you find downloading multiple 500MB+ files is too slow, you can download one Pristine ISO (unconfigured) from the image server and provide the unique configuration via a small external partition labeled SEED_DATA.

Download the base image once.
Create a tiny (10MB) FAT image.
Label that tiny image SEED_DATA and place your unique incus.yaml and network.yaml inside it.
Mount both the ISO and the SEED_DATA disk to your VM. IncusOS will automatically merge them at boot.

4.3 KiB Raw Blame History