LiveMode

LiveMode is an experimental feature that partially replaces leapp’s custom upgrade environment with a bootable squashfs image of the target system. Intuitively, this squashfs-based mechanism is similar to using a live CD (hence the name LiveMode) from which the DNF transaction and other post-reboot steps will be applied. Such an upgrade environment closely resembles an ordinary Linux installation, making developing desired functionality (e.g. supporting network-based storage) much easier.

Technical details

During an upgrade, prior to rebooting, leapp constructs a minimal target system container in order to obtain a version of the DNF stack expected by the new packages installed during the upgrade. After the container is created, the new DNF stack is used to download packages that will be installed during the upgrade. Having all necessary packages, leapp checks the RPM transaction to be performed during the upgrade. Finally, the upgrade environment is created - an initramfs containing custom dracut modules that ultimately execute leapp very early in the boot process. Such an upgrade environment guarantees isolation from other system services as there is essentially only the upgrade process running. However, the downside of using such an approach is that the bootup process of the upgrade environment is non-standard, meaning that almost none of the classical system initialisation services (e.g., LVM autoactivation) are running. Developing advanced features such as support for network-based storage, is, therefore demanding as only a little of the usual initialisation is present and executed during bootup.

The LiveMode feature obtains a similar isolation level of the upgrade process in a different way. Instead of using an initramfs image that executes leapp early, the system boots into a read-only squashfs system built from the target system container build previously to check the upgrade RPM transaction. Since leapp controls the creation of the target system container, it is also in control of what will be running alongside the upgrade process, limiting the possibility of arbitrary user-defined services interfering with the upgrade. The upgrade environment boots into the multi-user.target target and leapp is started as an ordinary systemd service. However, the squashfs image needs to be stored on the disk, and, hence, the using feature requires about 700mb of additional disk space.

Using the feature

It is possible to use the LiveMode feature by having set LEAPP_UNSUPPORTED=1 and running leapp as leapp upgrade --enable-experimental-feature livemode.

LEAPP_UNSUPPORTED=1 leapp upgrade --enable-experimental-feature livemode

Configuration

The feature offers an extensive list of configuration options that can be set by creating a YAML file in /etc/leapp/actor_conf.d/ with the extension .yaml. The content of the configuration file must be a mapping defining the livemode key with a value that is a mapping with (some) of the following keys:

Configuration field	Value type	Default	Semantics
`squashfs_image_path`	`str`	`/var/lib/leapp/live-upgrade.img`	Location where the squashfs image of the minimal target system will be placed.
`additional_packages`	`List[str]`	`[]`	Additional packages to be installed into the squashfs image.
`autostart_upgrade_after_reboot`	`bool`	`True`	If set to True, the upgrade will start automatically after the reboot. Otherwise a manual trigger is required.
`setup_network_manager`	`bool`	`False`	Try enabling Network Manager in the squashfs image.
`dracut_network`	`str`	`''`	Dracut network arguments, required if the `url_to_load_squashfs_from` option is set.
`url_to_load_squashfs_image_from`	`str`	`''`	URL pointing to the squashfs image that should be used for the upgrade environment.
`setup_passwordless_root`	`bool`	`False`	If set to True, the root account of the squashfs image will have empty password. Use with caution.
`setup_opensshd_using_auth_keys`	`str`	`''`	If set to a non-empty string, openssh daemon will be setup within the squashfs image using the provided authorized keys file.
`capture_strace_info_into`	`str`	`''`	If set to a non-empty string, leapp will be executed under strace and results will be stored within the provided file path.

Configuration example

Consider the file /etc/leapp/actor_conf.d/livemode.yaml with the following contents.

livemode:
  additional_packages : [ vim ]
  autostart_upgrade_after_reboot : false
  setup_network_manager : true
  setup_opensshd_using_auth_keys : /root/.ssh/authorized_keys

The configuration results in the following actions:

Leapp will install the vim package into the upgrade environment.
The upgrade will not be started automatically after reboot. Instead, user needs to resume the upgrade manually. Therefore, it is possible to manually inspect the system and verify that everything is in order, e.g., all of the necessary storage is mounted.
Leapp will attempt to enable NetworkManager inside the upgrade environment using source system’s network profiles. This attempt is best-effort, meaning that there is no guarantee that the network will be functional.
Leapp will enable the opensshd service. If a network access is established successfully, it will be possible to login using ssh into the upgrade environment using the root account and interact with the system.