Install mode

device lifecycle for Ubuntu Core developers for snapd developers

In install mode a seeded temporary system creates the ubuntu-boot and ubuntu-save and ubuntu-data partitions from the gadget and writes the model and the first modeenv and makes the kernel bootable and then points the bootloader at run mode. The work is the change Install the system. An installer can instead drive the same steps through the systems API.

On the map: ubuntu core install and recovery

▶ Watch this deck — 8 scenes, ~6 min

01 A disk with nothing to run yet

ON THE FACTORY BENCH ubuntu-seedrecovery system 20260301three partitions missing install modea temporary system, seeded from 20260301 ubuntu-bootubuntu-saveubuntu-datacreated from the gadget next boot: run run systemgone after the restart
A disk with only ubuntu-seed filled; a temporary install-mode system seeded from it creates ubuntu-boot, ubuntu-save and ubuntu-data, sets the next boot to run mode and is gone after the restart

Install mode is a temporary system seeded from a recovery system on ubuntu-seed. It creates ubuntu-boot, ubuntu-save and ubuntu-data from the gadget, makes them bootable and sets the next boot to run mode.

Your gateway is on the factory bench with a freshly written image. There's a seed on the disk, and nothing to run. The first power-on has to fix that. The device boots into install mode: a temporary system that runs from memory, seeded from the recovery system on the seed partition. It has one job. It reads the gadget and creates the three partitions that are missing: boot, save and data. It fills them, makes them bootable, and tells the bootloader that the next boot is run mode. Then it restarts, and the temporary system is gone.

02 Who does the installing for Ubuntu Core developers for snapd developers

TWO INSTALLERS, ONE RESULT install mode requested the initramfs installs, then carries on into run modeno extra reboot · the default on bases newer than core24 snapd change: Install the systemruns in the temporary system, then a reboot snapd installs if any of these holds:the gadget has an install-device hookthe kernel has fde-setup and the initramfs does notbase core20, core22, core22-desktop or core24, and no preseed.tgz in the seed acme-gatewaycore24 + install-device hook
Install mode forks: the initramfs installs and continues into run mode, or the snapd change Install the system runs and reboots; three conditions send a device to snapd, and acme-gateway takes that route

The initramfs installs and continues into run mode unless the gadget has an install-device hook, the kernel's fde-setup hook is missing from the initramfs, or the base is core20, core22, core22-desktop or core24 without preseed.tgz in the seed.

Which program does the installing? There are two. On bases newer than core24, the initramfs installs everything and carries straight on into run mode, without an extra reboot. The other way is a change inside snapd, in the temporary system, with a reboot at the end. A device takes the snapd route if its gadget has an install-device hook, which can't run in the initramfs. Or if its kernel has an fde-setup hook the initramfs lacks. Or if its base is core20, core22 or core24 and the seed has no preseed tarball. Our gateway has an install-device hook, so snapd it is.

03 The install change for Ubuntu Core developers for snapd developers

INSTALL THE SYSTEM seeded, in install modechange: Install the system setup-run-systemSetup system for run mode restart-system-to-run-modeEnsure next boot to run mode only when the gadget has an install-device hook:setup-ubuntu-saveinstall-device hook $ snap changeslists it while install mode runssetup-run-system: make the partitions, then make them bootable (next two scenes)
The change Install the system: setup-run-system then restart-system-to-run-mode, with setup-ubuntu-save and the install-device hook inserted between them when the gadget has the hook

The change "Install the system" runs setup-run-system then restart-system-to-run-mode. A gadget install-device hook adds setup-ubuntu-save and the hook task between them.

The temporary system has finished seeding. Snapd sees that it's in install mode and creates one change: Install the system. By default it has two tasks. setup-run-system does nearly all the work, and restart-system-to-run-mode ends it. If the gadget has an install-device hook, two more tasks go in between: one makes the save partition's snap folders available, then the hook itself runs. There's no special machinery here. It's tasks in a change, in a snapd that happens to run from memory, and while install mode lasts, snap changes lists it. The next two scenes open up setup-run-system.

04 Making the partitions for Ubuntu Core developers for snapd developers

FROM GADGET TO DISK ubuntu-seed gadget: structures and rolesencrypt this device?see: what is encrypted partition table matches the gadget?leftovers of an earlier attempt removed encrypt, if neededmake filesystemwrite contentmountfor each new partitionubuntu-bootubuntu-saveubuntu-datasystem-bootsystem-savesystem-datathe only roles install may create disk-mapping.jsondisk-mapping.jsonwhere each structure landed, for later gadget updates encrypted: save's key is kept inside data; both carry one 32-byte marker
setup-run-system checks encryption, checks the partition table against the gadget, removes leftover partitions, then encrypts, formats, fills and mounts ubuntu-boot, ubuntu-save and ubuntu-data, saves disk-mapping.json and pairs save with data

install.Run removes partitions and sealed keys from earlier attempts, then creates only system-boot, system-save and system-data: encrypt, make the filesystem, write content, mount. disk-mapping.json is saved to ubuntu-data and ubuntu-save.

setup-run-system starts with the disk, and it assumes it may have been here before. First it decides whether to encrypt; the encryption decks tell that story. Then it checks the partition table against the gadget, and removes partitions left by an interrupted attempt. Now, for each partition it may create, and that's only boot, save and data: encrypt if needed, make the filesystem, write the content, mount. It records where everything landed in disk-mapping.json, on data and save, for later gadget refreshes. On an encrypted device, save's key is kept inside data, and both share a random marker.

05 Making it bootable for Ubuntu Core developers for snapd developers

WHAT THE NEXT BOOT WILL READ ubuntu-boot ubuntu-data ubuntu-seed device/modelwritten once: must not exist core24pc-kernelpccopied from the seed modeenvmode=runrecovery_system=20260301current_recovery_systems=20260301good_recovery_systems=20260301current_kernels=pc-kernel_2901.snapmodel=acme/acme-gatewaygrade=secured kernel extracted and enabledboot config + command line keys sealed, if the device is encryptedsee: sealed keys bootloader environmentsnapd_good_recovery_systems=20260301
Install writes the model to ubuntu-boot, copies core24, pc-kernel and pc to ubuntu-data, writes the first modeenv, enables the kernel and boot config on ubuntu-boot, seals keys, and records 20260301 as a good recovery system in the seed bootloader environment

Install writes the model to ubuntu-boot/device/model, copies the base, kernel and gadget snaps to ubuntu-data, writes the first modeenv with the install label as current and good recovery system, enables the kernel, seals the keys and marks the system recovery capable.

The partitions exist, but nothing on them says how to boot. The model goes onto the boot partition, and only once: if a model file is already there, install fails rather than overwrite it. The base, kernel and gadget snaps are copied from the seed into data. Then the first modeenv: mode run, and the label we installed from, in both lists, current and good, because it's the one system known to work. The kernel is enabled on the boot partition, with the managed boot config and command line. Encrypted? Then the keys get sealed. Last, the label goes into the seed's bootloader environment as a good recovery system.

06 How install ends for Ubuntu Core developers for snapd developers

THE LAST TWO TASKS install-device hook (gadget)factory work; see the hook deck restart-system-to-run-mode$ snapctl reboot --haltor --poweroff; nothing reboots nowit sets how the last task ends apply preseed.tgz, if the seed has onecarry the hostname over snapd_recovery_mode=runubuntu-seed: bootloader environment save timings and install logsto ubuntu-data restarthaltpoweroffdefault
The install-device hook can call snapctl reboot --halt, which only sets how restart-system-to-run-mode ends; that task applies preseed.tgz, carries the hostname, sets snapd_recovery_mode=run on ubuntu-seed, saves logs and restarts, halts or powers off

snapctl reboot --halt or --poweroff inside install-device only sets how restart-system-to-run-mode ends. That task applies preseed.tgz, sets snapd_recovery_mode=run in the seed bootloader environment and saves the install logs.

Everything is on disk. Two things are left: let the gadget have its say, and leave install mode. The install-device hook is the gadget's turn; its own deck covers it. One detail matters here. Inside that hook, snapctl reboot doesn't reboot anything. It tells the final task how to end: halt or power off instead of restart. Handy on a production line, where you want units off for boxing. The final task applies the preseed tarball if there is one, carries the hostname over, and sets the recovery mode variable to run, on the seed partition. It saves the install logs to data, then restarts, halts or powers off.

07 When an installer drives for Ubuntu Core developers for snapd developers

THE SAME INSTALL, STEP BY STEP POST /v2/systems/<label> {"action": "install", "step": …}installerpartitions the disk itselfsnapd 1 setup-storage-encryptionencrypted deviceskeys held in memory only: a snapd restart loses them 2 generate-recovery-keyanswered at once, no change 3 finish + on-volumeswrite contentcopy the seed to the targetmake it bootable 4 preseed + target-rootoptional model says storage-safety: encrypted, and step 1 was skipped: finish fails
An installer that partitions the disk itself calls snapd's systems API in four steps: setup-storage-encryption, generate-recovery-key, finish with on-volumes, and an optional preseed; finish fails if encryption is required but was not set up

POST /v2/systems/<label> with action: install and step: setup-storage-encryption, generate-recovery-key, finish (with on-volumes) and preseed (with target-root). Encryption data from the first step is held only in memory.

Not every device installs itself. A desktop installer wants to ask first: which disk, what passphrase. So snapd offers the install as separate steps over its API. The installer partitions the disk itself, then calls snapd. Step one sets up encryption and returns the encrypted devices. Its secrets stay in memory on purpose, so if snapd restarts midway, you start over. Step two hands back a recovery key. Step three is finish. Given the volumes, snapd writes the content, copies the recovery system to the target's seed and makes it bootable. An optional step preseeds the result. If the model demands encryption and step one was skipped, finish refuses.

08 Where to go from here

ROADS Install mode From power-on to snapdthe first run boot What is encryptedand who decidesSealed keysthe keys sealed at install ubuntu-seed and first bootthe seeding before installModel, gadget and kernelthe layout install follows Hooks: device setupthe install-device hooksnapctl lifecycle commandssnapctl reboot Boot modesinstall mode in the initramfs Recovery systemsthe label you installed from
Roads from install mode: the boot path, what is encrypted, sealed keys, the seed, the model and gadget, the install-device hook, snapctl reboot, the boot modes and recovery systems

Roads to the first run boot, encryption, the seed, the model and gadget, the install-device hook, snapctl reboot, the modes and recovery systems.

The gateway restarts, and for the first time there's a run system to boot. Follow it into the boot path deck to watch that first run boot. If you came for encryption, the two encryption decks pick up where scenes four and five stopped short. The seed deck covers the seeding that came before, and the model deck the gadget layout that install followed. The hook and snapctl decks cover the install-device hook and snapctl reboot. The modes deck shows install mode from the initramfs side, including installing by itself. And the label you installed from stays on the seed as your first recovery system.

Read more

for Ubuntu Core developers for snapd developers for administrators

The install change

Change: "Install the system", created after seeding when the mode is install.

TaskSummaryWhen
setup-run-systemSetup system for run modealways
setup-ubuntu-saveSetup ubuntu-save snap foldersgadget has an install-device hook
hook install-devicegadget has the hook
restart-system-to-run-modeEnsure next boot to run modealways

for Ubuntu Core developers for snapd developers

setup-run-system, in order

1. Check encryption support. 2. Validate the gadget and its content against the kernel. 3. Create the partitions: check the partition table against the gadget, remove partitions from an earlier attempt, delete stale *.sealed-key files on ubuntu-seed, then for each of system-boot, system-save and system-data: encrypt if needed, make the filesystem, write content, mount. Save disk-mapping.json to ubuntu-data and ubuntu-save. 4. If encrypting: generate the ubuntu-save key and store it inside ubuntu-data; write the same random 32-byte marker to both. 5. Write the model to ubuntu-boot/device/model (the file must not exist yet), carry the clock over, configure cloud-init for the target. 6. Make the system runnable: copy base, kernel, gadget and kernel-modules components to ubuntu-data; write modeenv; extract and enable the kernel on ubuntu-boot; install the managed boot config and the kernel command line; seal the keys; add the label to snapd_good_recovery_systems in the bootloader environment.

Pre-UC20 models are refused.

for Ubuntu Core developers for snapd developers

The first modeenv

KeyValue at install
moderun
recovery_systemthe install label; cleared by mark-seeded on the first run boot
current_recovery_systemsthe install label
good_recovery_systemsthe install label
current_kernelsthe installed kernel's file name
gadgetthe installed gadget's file name
model, grade, model_sign_key_id, classicfrom the model
current_trusted_boot_assets, current_trusted_recovery_boot_assetshashes of the bootloader assets
current_kernel_command_linesfilled in once the boot config is installed

for Ubuntu Core developers for snapd developers

restart-system-to-run-mode, in order

1. Apply preseed.tgz if the seed has one. The seed's model must be the running model, the preseed assertion's signer must be in the model's preseed-authority, and label, model, brand, series, digest and snap list must match. 2. Run daemon-reload if there was an install-device hook. 3. Copy the install-mode hostname. 4. Set snapd_recovery_mode=run in the bootloader environment on ubuntu-seed. 5. Write timings and install logs to ubuntu-data. 6. Restart, halt or power off.

snapctl reboot is valid only inside install-device and needs exactly one of --halt or --poweroff. Errors: "cannot use reboot command outside of gadget install-device hook", "either --halt or --poweroff must be specified", "cannot specify both --halt and --poweroff".

for Ubuntu Core developers for snapd developers

Where the install runs

The initramfs installs and continues into run mode when all of these hold:

  • the gadget has no install-device hook;
  • if the kernel has an fde-setup hook, the initramfs has fde-setup too;
  • the base is newer than core24, or the base is core20, core22, core22-desktop or core24 and the seed has preseed.tgz.

Otherwise the change above runs in the seeded install system and the device restarts at the end. See Run, install, recover, factory reset.

for Ubuntu Core developers for snapd developers

The installer API

POST /v2/systems/<label> with "action": "install" and a "step".

StepRunsNotes
setup-storage-encryptiontask install-setup-storage-encryption, change "Setup storage encryption for installing system \"<label>\""returns the encrypted devices as change data; passphrase or PIN data and the resulting keys are kept only in memory, so a snapd restart between steps loses them
generate-recovery-keysynchronousmust come after the encryption step
finishtask install-finish, change "Finish setup of run system for \"<label>\""takes on-volumes from the installer and merges them with the gadget; writes content; copies the seed system to the target, honouring optional-install; makes seed, recovery system and run system bootable. Fails if the model has storage-safety: encrypted and the encryption step was skipped
preseedtask install-preseedneeds target-root

Most actions need root. generate-recovery-key, reprovision and fix-encryption-support are also open to snaps with the snap-fde-control interface, or through polkit.

Volumes in the gadget may be marked partial (size, filesystem, schema, structure) to leave those decisions to the installer; see Model, gadget and kernel.

Further reading

Roads from here

SNAPCTL · the snap's API into snapd

HOOKS · code snapd runs inside a snap

UBUNTU CORE · boot

UBUNTU CORE · install and recovery

UBUNTU CORE · full disk encryption