From af35d1fd718258d37ed34be59084e7c77072096c Mon Sep 17 00:00:00 2001 From: Michal Hecko Date: Mon, 14 Apr 2025 10:14:12 +0200 Subject: [PATCH 11/37] docs(livemode): add LiveMode documentation This commit introduces a high-level documentation of the livemode feature. The following is documented: - how the upgrade process differs from the standard one when using livemode - why is the feature useful, i.e., why would anyone use it - how to enable and use the feature - what configuration options are available, including an example of configuration Jira-ref: RHELMISC-9703 --- .github/workflows/codespell.yml | 2 +- .../experimental-features/index.rst | 1 + .../experimental-features/livemode.md | 86 +++++++++++++++++++ 3 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 docs/source/configuring-ipu/experimental-features/livemode.md diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index b8da5ebb..3e595e32 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -17,7 +17,7 @@ jobs: - uses: actions/checkout@v4 - uses: codespell-project/actions-codespell@v2 with: - ignore_words_list: ro,fo,couldn,repositor,zeor + ignore_words_list: ro,fo,couldn,repositor,zeor,bootup skip: "./repos/system_upgrade/common/actors/storagescanner/tests/files/mounts,\ ./repos/system_upgrade/common/actors/networkmanagerreadconfig/tests/files/nm_cfg_file_error,\ ./repos/system_upgrade/el8toel9/actors/xorgdrvfact/tests/files/journalctl-xorg-intel,\ diff --git a/docs/source/configuring-ipu/experimental-features/index.rst b/docs/source/configuring-ipu/experimental-features/index.rst index 7a26116e..37de2fed 100644 --- a/docs/source/configuring-ipu/experimental-features/index.rst +++ b/docs/source/configuring-ipu/experimental-features/index.rst @@ -13,6 +13,7 @@ are provided. :caption: Contents: :glob: + livemode .. Indices and tables diff --git a/docs/source/configuring-ipu/experimental-features/livemode.md b/docs/source/configuring-ipu/experimental-features/livemode.md new file mode 100644 index 00000000..44200e80 --- /dev/null +++ b/docs/source/configuring-ipu/experimental-features/livemode.md @@ -0,0 +1,86 @@ +# 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. -- 2.49.0