How installation works

The Ubuntu Core install image is composed from the kernel, gadget, base, snapd and app snaps (see Snaps in Ubuntu Core for further details). The resultant image typically contains the following:

Core install image partition

Any device booting an Ubuntu Core installation image will create or use the partitions defined by its Storage layout and proceed through the following installation steps.

The first three (1-3) are also described in the recovery mode boot process:

  1. Boot through the bootloader, its assets, and boot configuration in ubuntu-seed.

  2. Bootloader loads the kernel from a designated recovery system with option snapd_recovery_mode=install.

  3. Kernel initialises the system and loads the initramfs. The initramfs contains a reduced set of essential tools that are used to install the system by:

    • creating all missing partitions.

    • (optionally) encrypting ubuntu-data and ubuntu-save if supported and not disabled.

    • sealing the disk keys through hardware support.

    • setting up the run system in ubuntu-data.

    • setting boot configuration and the kernel option snapd_recovery_mode=run in ubuntu-boot.

  4. The initramfs then boots into userspace to complete the installation.

  5. Snapd bootstraps itself and proceeds to seed, install, and activate all the snaps marked for run mode use in the recovery system.

  6. Finally, it sets the system option system.seed.loaded=true.

Until the system is rebooted, the kernel command line will include snapd_recovery_mode=install as an argument despite the system being fully installed and operational. The system.seed.loaded system option is the true marker that installation is complete.

Note

Until Ubuntu Core 24, the system was installed from a tmpfs in userspace instead of from the initramfs, and the device was rebooted to finalise installation. Here, the snapd kernel option was set to run.

The install-device hook

A gadget can optionally define an install-device hook . This is invoked from install mode before rebooting into run mode, between steps 4 and 5 above, and also after a factory reset, to perform early hardware and firmware configuration.

The snapctl system-mode command can be run during execution of the hook to detect which mode the install-device hook has been executed under.

All partitions are created and mounted when the install-device hook runs.

If applicable, precautions should be taken to ensure that any sensitive configuration is idempotent and/or only done once for the lifetime of the device.

The install-device hook can also stop the subsequent reboot from booting into run mode (step 5, above) with the snapctl reboot command and either --halt or --poweroff arguments:

snapctl reboot --halt|--poweroff

Either reboot command will only take effect after the hook has finished.

Factory image hint

A Ubuntu Core image can be built to include a hint that an image is intended to be used, or first booted, in the device factory. This hint can then be used to govern whether factory-only resources are accessible, for instance, but no security-related decisions should be made based solely on its inclusion as it could be possible for the hint to be set again in the field.

The factory image hint is set by adding --factory-image to the ubuntu-image command when building the image:

ubuntu-image snap my-model.model --factory-image

See Building the image for details on how images are built.

The factory image hint is cleared directly before rebooting into run mode.

For the current boot, the state of the factory image hint can be viewed by invoking snapctl system-mode and checking whether factory: true is included in its YAML output. See The snapctl tool for more information.