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
01 A disk with nothing to run yet
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
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
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
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
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
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
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 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.
| Task | Summary | When |
|---|---|---|
setup-run-system | Setup system for run mode | always |
setup-ubuntu-save | Setup ubuntu-save snap folders | gadget has an install-device hook |
hook install-device | gadget has the hook | |
restart-system-to-run-mode | Ensure next boot to run mode | always |
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
| Key | Value at install |
|---|---|
mode | run |
recovery_system | the install label; cleared by mark-seeded on the first run boot |
current_recovery_systems | the install label |
good_recovery_systems | the install label |
current_kernels | the installed kernel's file name |
gadget | the installed gadget's file name |
model, grade, model_sign_key_id, classic | from the model |
current_trusted_boot_assets, current_trusted_recovery_boot_assets | hashes of the bootloader assets |
current_kernel_command_lines | filled 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-devicehook; - if the kernel has an
fde-setuphook, the initramfs hasfde-setuptoo; - 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".
| Step | Runs | Notes |
|---|---|---|
setup-storage-encryption | task 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-key | synchronous | must come after the encryption step |
finish | task 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 |
preseed | task install-preseed | needs 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
- How installation works: the steps of an install and the install-device hook. It describes the initramfs install as the rule; the code still uses the snapd change for older bases and for gadgets with the hook.
- Debug install mode: holding installation open with an install-device hook to look around.
- Integrate TPM-FDE into a custom installer: the installer API with JSON examples.
- Supported snap hooks: install-device among the other hooks.
- Calculate partition sizes: how
min-sizeandsizedecide partition sizes at install.
Roads from here
SNAPCTL · the snap's API into snapd
- snapctl: services, refresh and changes — snapctl reboot inside install-device
HOOKS · code snapd runs inside a snap
- Hooks: device setup — the install-device hook
UBUNTU CORE · boot
- From power-on to snapd — the first boot of the system install just made
- Run, install, recover, factory reset — what the initramfs does in install mode and when it installs by itself
- Ubuntu Core: how a device boots and recovers — back to the Ubuntu Core overview
UBUNTU CORE · install and recovery
- ubuntu-seed and first boot — the seeding that runs before the install change starts
- Model, gadget and kernel — the gadget layout and roles that install follows
- Recovery systems — the recovery system install leaves behind
UBUNTU CORE · full disk encryption
- What is encrypted and who decides — whether the new partitions are encrypted and with what
- Sealed keys, boot chains and resealing — the keys sealed at the end of install