262 lines
9.2 KiB
Markdown
262 lines
9.2 KiB
Markdown
# IncusOS Tools
|
|
|
|
Scripts for building IncusOS installation media and seed configurations.
|
|
|
|
## Overview
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| [`incusos-iso`](#incusos-iso) | Build customized IncusOS ISO/IMG images using the flasher-tool |
|
|
| [`incusos-seed`](#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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
openssl pkcs12 -export \
|
|
-inkey ~/.config/incus/client.key \
|
|
-in ~/.config/incus/client.crt \
|
|
-out ~/.config/incus/client.pfx
|
|
```
|
|
|
|
## Examples
|
|
|
|
See the [`examples/`](examples/) directory for sample seed configurations:
|
|
|
|
- [`incus-standalone.yaml`](examples/incus-standalone.yaml) -- Single Incus server with defaults
|
|
- [`incus-cluster-node.yaml`](examples/incus-cluster-node.yaml) -- Cluster node (no defaults)
|
|
- [`ops-center.yaml`](examples/ops-center.yaml) -- Operations Center
|
|
- [`network-static.yaml`](examples/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.
|