111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# 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`](../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:**
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
#!/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:**
|
|
|
|
```bash
|
|
#!/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.
|