Feature: _install

Description

Features

This feature adds automatic installation capability to ISO images by:

• Installing a systemd service (gl-install.service) that runs on first boot
• Detecting the first suitable writable block device automatically
• Running the installation script (/opt/install/install.sh) non-interactively
• Powering off the system after successful installation

How It Works

Automatic Disk Detection

The gl-install script automatically finds the first suitable installation target by:

1. Checking for gl.install.target=/dev/sdX kernel parameter (manual override)
2. Auto-detecting the first non-removable, writable block device
3. Skipping: loop devices, CD-ROMs, RAM disks, read-only devices, removable media (USB, CD)

For typical single-disk systems, this selects /dev/sda or /dev/vda (virtio disk in VMs).

Installation Process

On first boot:

1. The gl-install.service starts after reaching default.target
2. The /usr/local/sbin/gl-install script runs and detects the target disk
3. The installation script partitions the disk (GPT with EFI and ROOT partitions)
4. Copies the live root filesystem to the ROOT partition
5. Installs the bootloader (syslinux for BIOS, systemd-boot for UEFI)
6. Powers off the system

Service Conditions

The installation service only runs when:

• /opt/install/install.sh exists (ISO has installation script)
• /iso-installed does not exist (prevents re-installation on subsequent boots)

Usage

Building Auto-Install ISOs

Create a flavor that includes both _iso and _install:

# features/_flavor/metal-server_prod_iso_install.yaml
type: element
features:
  include:
    - _iso
    - _install
    - metal
    - server

Build the ISO:

./build metal-server_prod_iso_install

Manual Target Disk Override

To specify a different target disk, pass a kernel parameter at boot:

UEFI (systemd-boot):

1. At the boot menu, press e to edit the boot entry
2. Append gl.install.target=/dev/nvme0n1 to the kernel command line
3. Press Enter to boot

Legacy BIOS (syslinux):

1. At the boot menu, press Tab to edit the boot command
2. Append gl.install.target=/dev/nvme0n1 to the command line
3. Press Enter to boot

Testing

Test auto-install ISOs using QEMU:

./test .build/metal-server_prod_iso_install-amd64-*.iso

The test framework automatically detects the _install feature (via the .requirements file) and runs a two-stage test:

1. Stage 1: Boot ISO, install to /dev/vda, power off
2. Stage 2: Boot from installed disk, configure SSH, run tests

Requirements File

This feature sets install=true in the image's .requirements file, enabling automatic detection by test frameworks and deployment tools.

Components

Files Installed

• /usr/local/sbin/gl-install - Auto-install wrapper script
• /etc/systemd/system/gl-install.service - Systemd service unit

Service Configuration

[Unit]
Description=Garden Linux Auto-Install
ConditionPathExists=/opt/install/install.sh
ConditionPathExists=!/iso-installed
After=default.target
Requires=default.target

[Service]
Type=idle
ExecStart=/usr/local/sbin/gl-install
StandardOutput=journal+console
StandardError=journal+console

[Install]
WantedBy=default.target

Use Cases

• Automated provisioning: Deploy Garden Linux to multiple systems without manual interaction
• VM templates: Create auto-installing ISO images for VM deployment
• Test automation: Automated testing of installation process in CI/CD pipelines
• Batch installations: Install to multiple physical servers using the same ISO

Related Features

• _iso - Required; provides the ISO image and installation script
• _fwcfg - Enables QEMU fw_cfg for test automation (optional)

Comparison with Interactive Installation

Method	Description	Use Case
Interactive (_iso only)	Boot ISO, manually run /opt/install/install.sh, select disk	Development, manual deployments, disk verification
Automatic (_iso + _install)	ISO automatically installs to first disk on boot, then powers off	Automation, CI/CD, batch provisioning, VM templates

Unit testing

This feature does not support unit tests.

Meta

type	flag
artifact	None (modifies ISO from _iso feature)
included_features	_iso (required)
excluded_features	None