leapp-repository/SOURCES/0011-docs-livemode-add-LiveMode-documentation.patch

From af35d1fd718258d37ed34be59084e7c77072096c Mon Sep 17 00:00:00 2001
From: Michal Hecko <mhecko@redhat.com>
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