Ubuntu autoinstall

ubuntu-autoinstall

Autoinstall is the configuration format for Ubuntu Server's Subiquity installer. A version: 1 document tells the installer how to partition, install, and configure the system unattended. This skill is authoring-led (produce a correct autoinstall config from a description) with a strong validation/debug path, aimed at unattended on-prem / air-gapped Ubuntu Server LTS installs.

Autoinstall nests the other two domains:

• its network: key is netplan v2 → use the ubuntu-netplan skill;
• its user-data: key is cloud-config for the installed system → use the ubuntu-cloud-init skill;
• and the config is itself delivered via cloud-init NoCloud.

See The two delegation boundaries and Delivery.

Authoring workflow

1. Pick the delivery method (Delivery, below). Air-gapped → usually a NoCloud seed on the ISO/USB or an HTTP seed.
2. Write the version: 1 document. version is the only schema-required key, but identity is required at runtime unless user-data: is present.
3. Set the air-gapped essentials — local mirror, proxy, offline fallback (see the Air-gapped essentials section below for the exact keys).
4. Author network: as netplan v2 (ubuntu-netplan skill) and any installed-system first-boot config under user-data: (ubuntu-cloud-init skill).
5. Validate with the subiquity repo's validate-autoinstall-user-data.py (see Validation — the script ships in the installer source, not in this skill).
6. Boot with the autoinstall kernel keyword to skip the disk-wipe confirmation for true zero-touch.

The two delegation boundaries (critical)

#cloud-config
# (1) top-level cloud-config here configures the EPHEMERAL installer environment
autoinstall:                  # processed by Subiquity → configures the TARGET system
  version: 1
  network:                    # (2) netplan v2  → ubuntu-netplan skill
    version: 2
    ethernets: { ... }
  identity: { ... }
  user-data:                  # (3) cloud-config → ubuntu-cloud-init skill
    # runs on the INSTALLED system's FIRST BOOT (not at install time)
    packages: [ ... ]

• network: is netplan v2 only. Default if omitted is DHCPv4 on en*/eth*. match: inside ethernets accepts only name/macaddress/driver. (A rarely-used double-wrapped network: {network: {...}} form also validates; prefer the plain form.)
• user-data: is cloud-config for the installed system, merged with the installer-generated user-data. Timing matters: users from identity are created during install; users defined in user-data are created on first boot. Supplying user-data makes identity optional — but then ensure a login path exists. Don't define the same user in both.

Delivery & the NoCloud seed

Autoinstall config reaches the installer in two families:

• Via cloud-init #cloud-config user-data — requires the #cloud-config first line and the config nested under a top-level autoinstall: key.
• Directly on the install media as a file named autoinstall.yaml — here the autoinstall: wrapper is optional (a bare version: 1 ... works). This wrapper acceptance for on-media files arrived in 24.04.

Precedence — the installer uses the FIRST that exists:

1. --autoinstall <path> CLI arg (empty string explicitly disables autoinstall)
2. kernel cmdline subiquity.autoinstallpath=...
3. autoinstall.yaml at the root of the install system
4. cloud-config-supplied run/subiquity/cloud.autoinstall.yaml
5. cdrom/autoinstall.yaml baked into the ISO

So kernel cmdline and on-media files outrank cloud-config.

NoCloud seeding (the on-prem workhorse — see the ubuntu-cloud-init skill for full NoCloud detail):

• HTTP seed: kernel cmdline autoinstall ds=nocloud-net;s=http://SERVER:PORT/, serving user-data + meta-data (+ optional network-config) at that base URL.
• Volume seed (USB/ISO): build with cloud-localds seed.iso user-data meta-data; cloud-init finds it by the cidata/CIDATA filesystem label. meta-data must exist (may be empty: touch meta-data).
• The bare autoinstall kernel keyword is separate from ds= — it suppresses the interactive "Continue with autoinstall?" disk-wipe confirmation. True zero-touch needs both the config delivery and autoinstall on the cmdline.
• Quote the whole kernel -append '... ds=nocloud-net;s=...' — ; is a shell metacharacter (and ends a GRUB statement).

Full delivery/seeding detail (precedence source, ISO remastering, the on-media "only the autoinstall key" rule) is in references/delivery-and-seeding.md.

Top-level schema (version 1) — quick reference

Only version is schema-required; unknown keys produce a warning in v1 (will be fatal in a future version). Common keys:

Key	Purpose
version	Must be 1. Required.
identity	Initial user {realname, username, hostname, password}. Required at runtime unless user-data: present.
storage	Disk layout — layout: {name: lvm|direct|zfs|hybrid} or a curtin action list.
network	netplan v2 (→ ubuntu-netplan skill).
ssh	{install-server, authorized-keys, allow-pw}.
apt	Mirror selection, proxy, components, fallback (air-gapped core).
proxy	HTTP proxy for install + target apt/snapd.
packages / snaps	Extra packages / snaps to install.
user-data	cloud-config for the installed system (→ ubuntu-cloud-init skill).
late-commands	Commands after install (target mounted at /target).
early-commands	Commands before probing (config is re-read after).
interactive-sections	Sections to still prompt for; must be a list (['*'], not '*').
updates	security (default) or all.
refresh-installer	{update: bool, channel} — installer self-update (set false air-gapped).
kernel	{package} or {flavor}.
timezone, locale, keyboard, source, drivers, codecs, oem, reporting, error-commands	see references/schema.md.
kernel-crash-dumps, zdevs	24.10+ only — not in 24.04.

Full per-key reference (storage layouts, apt mirror-selection details, identity, ssh, command timing) is in references/schema.md.

Air-gapped essentials

refresh-installer:
  update: false                      # don't try to self-update from the snap store
proxy: http://proxy.internal:3128    # NOT applied to the geoip lookup
apt:
  geoip: false                       # disable geoip.ubuntu.com lookup (10s hang otherwise)
  preserve_sources_list: false
  mirror-selection:
    primary:
      - uri: "http://mirror.internal/ubuntu"
        arches: [amd64]
  fallback: abort                    # set explicitly; don't silently go offline-from-ISO
updates: security

• Wrapping primary inside mirror-selection enables Subiquity's mirror probing (picks the first usable). A bare primary: list uses legacy curtin behavior.
• apt.fallback ∈ abort | offline-install | continue-anyway. The docs disagree on the default — always set it explicitly. offline-install falls back to the ISO's seed; continue-anyway is not recommended.
• Snaps requiring the store fail offline — only ship snaps seeded on the ISO, or omit snaps:. source.id: ubuntu-server-minimal reduces footprint.

storage (quick)

storage:
  layout:
    name: lvm                  # lvm | direct | zfs | hybrid
    password: LUKS_PASSPHRASE  # LVM + LUKS
    sizing-policy: all         # use whole VG ('scaled' default leaves snapshot room)

Pick a disk with match: {ssd: true} / {serial: ...} / {size: largest}. For advanced partitioning use a curtin config: action list (when layout is present, config is ignored). See references/schema.md.

Validation & debugging

# validate-autoinstall-user-data.py ships in the subiquity SOURCE repo — it is NOT
# bundled in this skill. Get it with: git clone https://github.com/canonical/subiquity
# && cd subiquity && make install_deps. Run from that checkout, NEVER as sudo:
python3 scripts/validate-autoinstall-user-data.py user-data            # #cloud-config-wrapped
python3 scripts/validate-autoinstall-user-data.py --no-expect-cloudconfig autoinstall.yaml
cloud-init schema -c user-data                                         # validate the cloud-config body

Install logs live in /var/log/installer/; the delivered autoinstall (with password hash) is saved to /var/log/installer/autoinstall-user-data. Full validation workflow, the JSON schema location, and common pitfalls are in references/validation-and-debugging.md.

Common pitfalls

• Missing #cloud-config header, or a misspelled autoinstall: key → the installer goes interactive instead of crashing.
• In the on-media autoinstall.yaml, no other top-level keys may sit beside autoinstall: — it's fatal. (The #cloud-config delivery is the opposite: top-level cloud-config configures the installer env.)
• late-commands run in the installer environment; the target is at /target. Use curtin in-target -- <cmd> to run inside the installed system.
• interactive-sections: '*' (string) fails schema — use ['*']. If any interactive section is set, reporting is ignored.
• Quote the password hash and the kernel -append string.
• Don't pin a kernel: together with oem.install: true (conflicting requirements).

Reference files

• references/schema.md — full top-level key reference: storage layouts & curtin actions, apt mirror-selection, identity/ssh, command timing, all keys. (Has a TOC.)
• references/delivery-and-seeding.md — delivery precedence, NoCloud seeds, ISO/USB, HTTP serving, zero-touch, the on-media rules.
• references/validation-and-debugging.md — the validator script, JSON schema, logs, pitfalls, and 24.04-vs-26.04 version notes.
• references/examples.md — minimal config + a complete air-gapped server install.