Chapter 3. Preparing for the upgrade

Procedure

1. Optional: Unmount non-system OS file systems that are not required for the upgrade and comment them out from the /etc/fstab file. For example, this includes file systems containing only data files unrelated to the system itself. This can reduce the amount of time needed for the upgrade process and prevent potential issues related to third-party applications that are not migrated properly during the upgrade by custom or third-party actors.

2. If you are upgrading by using RHSM, verify that the system is registered to an account with Simple Content Access (SCA) enabled:

   # subscription-manager status
   +-------------------------------------------+
      System Status Details
   +-------------------------------------------+
   Overall Status: Disabled
   Content Access Mode is set to Simple Content Access. This host has access to content, regardless of subscription status.
   System Purpose Status: Disabled

3. Ensure you have appropriate repositories enabled. The following command enables the Base and AppStream repositories for the 64-bit Intel and AMD architectures; for other architectures, see RHEL 9 repositories.

   # subscription-manager repos --enable rhel-9-for-x86_64-baseos-rpms --enable rhel-9-for-x86_64-appstream-rpms

   Note

   Optional: Enable the CodeReady Linux Builder (also known as Optional) or Supplementary repositories. For more information about the content of these repositories, see the Package manifest.

4. Set the system release version to the source OS version, for example:

   # subscription-manager release --set <source_os_version>

   Replace <source_os_version> with the source OS version, for example 9.6.

   1. If you are upgrading by using Red Hat Update Infrastructure (RHUI) on a public cloud, set the expected system release version manually:

      # rhui-set-release --set 9.7

      Important

      If the rhui-set-release command is not available on your system, you can set the expected system release version by updating the /etc/dnf/vars/release file:

      # echo "9.7" > /etc/dnf/vars/releasever

5. If you use the dnf versionlock plugin to lock packages to a specific version, clear the lock by running:

   # dnf versionlock clear

6. If you are upgrading by using Red Hat Update Infrastructure (RHUI) on a public cloud, enable required RHUI repositories and install required RHUI packages to ensure your system is ready for upgrade:

   1. For AWS:

      # dnf config-manager --set-enabled rhui-client-config-server-9
      # dnf -y install leapp-rhui-aws

   2. For Microsoft Azure:

      # dnf config-manager --set-enabled rhui-microsoft-azure-rhel9
      # dnf -y install rhui-azure-rhel8 leapp-rhui-azure

   3. For Google Cloud, follow the Leapp RHUI packages for Google Cloud Knowledgebase article.

7. Ensure that you have up-to-date leapp and leapp-repository packages:

   1. RHEL 9.6: version 0.19.0 of the leapp package and version 0.22.0 of the leapp-repository package.

   2. RHEL 9.7: version 0.20.0 of the leapp package and version 0.23.0 of the leapp-repository package.

      The leapp-repository package contains the leapp-upgrade-el9toel10 RPM package.

      Note

      Disconnected systems only:download the following packages from the Red Hat Customer Portal:

      • leapp
      • leapp-deps
      • python3-leapp
      • leapp-upgrade-el9toel10
      • leapp-upgrade-el9toel10-deps

      • leapp-upgrade-el9toel10-fapolicyd

        • Include only if you installed the fapolicyd RPM package on your system.

8. Install the Leapp utility:

   # dnf install leapp-upgrade

9. Update all packages to the latest RHEL 9 version and reboot:

   # dnf update
   # reboot

10. Optional: Review, remediate, and then remove the rpmnew and rpmsave files.

11. If you use a configuration management system, ensure that it does not interfere with the in-place upgrade process:

    • If your configuration management system has a client-server architecture, such as Puppet, Salt, or Chef, disable the system before running the leapp preupgrade command. Do not enable the configuration management system until after the upgrade is complete to prevent issues during the upgrade.

    • If your configuration management system has agentless architecture, do not execute the configuration and deployment file. For example, if your system has Ansible, do not execute an Ansible playbook during the upgrade.

      Warning

      Automation of the pre-upgrade and upgrade process by using a configuration management system is not supported by Red Hat. For more information, see Using configuration management systems to automate parts of the Leapp pre-upgrade and upgrade process on Red Hat Enterprise Linux.

12. If you are upgrading by using an ISO image, verify that the ISO image contains the target OS version, for example, RHEL 10.0, and is saved to a persistent local mount point to ensure that the Leapp utility can access the image throughout the upgrade process.

Procedure

1. Import a subscription manifest with RHEL 9 repositories into Satellite Server. For more information, see the Managing Red Hat Subscriptions chapter in the Managing Content Guide for the particular version of Red Hat Satellite.

2. Enable and synchronize all required RHEL 9 and RHEL 10 repositories on the Satellite Server with the latest updates for the source and target OS versions. Required repositories must be available in the content view and enabled in the associated activation key.

   Note

   For RHEL 10 repositories, enable the target OS version, for example, RHEL 10.0, of each repository. If you enable only the RHEL 10 version of the repositories, the in-place upgrade is inhibited.

   For example, for the Intel architecture without an Extended Update Support (EUS) subscription, enable at minimum the following repositories:

   • Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)

     rhel-9-for-x86_64-appstream-rpms

     x86_64 <source_os_version>

   • Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)

     rhel-9-for-x86_64-baseos-rpms

     x86_64 <source_os_version>

   • Red Hat Enterprise Linux 10 for x86_64 - AppStream (RPMs)

     rhel-10-for-x86_64-appstream-rpms

     x86_64 <target_os_version>

   • Red Hat Enterprise Linux 10 for x86_64 - BaseOS (RPMs)

     rhel-10-for-x86_64-baseos-rpms

     x86_64 <target_os_version>

     Replace <source_os_version> and <target_os_version> with the source OS version and target OS version respectively, for example, 9.6 and 10.0.

     For other architectures, see RHEL 9 repositories and RHEL 10 repositories.

     For more information, see the Importing Content chapter in the Managing Content Guide for the particular version of Red Hat Satellite.

3. Attach the content host to a content view containing the required RHEL 9 and RHEL 10 repositories.

   For more information, see the Managing Content Views chapter in the Managing Content Guide for the particular version of Red Hat Satellite.

Verification

1. Verify that the correct RHEL 9 and RHEL 10 repositories have been added to the correct content view on Satellite Server.

   1. In the Satellite web UI, navigate to Content > Lifecycle > Content Views and click the name of the content view.

   2. Click the Repositories tab and verify that the repositories appear as expected.

      Note

      You can also verify that the repositories have been added to the content view by using the following commands:

      # hammer repository list --search 'content_label ~ rhel-9' --content-view <content_view_name> --organization <organization> --lifecycle-environment <lifecycle_environment>
      # hammer repository list --search 'content_label ~ rhel-10' --content-view <content_view_name> --organization <organization> --lifecycle-environment <lifecycle_environment>

      Replace <content_view_name> with the name of the content view, <organization> with the organization, and <lifecycle_environement> with the name of the lifecycle environment..

2. Verify that the correct RHEL 10 repositories are enabled in the activation key associated with the content view:

   1. In Satellite web UI navigate to Content > Lifecycle > Activation Keys and click the name of the activation key.
   2. Click the Repository Sets tab and verify that the statuses of the required repositories are Enabled.

3. Verify that all expected RHEL 9 repositories are enabled in the host. For example:

   # subscription-manager repos --list-enabled | grep "^Repo ID"
   Repo ID:   rhel-9-for-x86_64-baseos-rpms
   Repo ID:   rhel-9-for-x86_64-appstream-rpms

Procedure

1. If you want to modify LiveMode’s default specifications, create a YAML file in the /etc/leapp/actor_conf.d/ file, for example livemode.yaml.

2. Enter the desired LiveMode configuration into the YAML file.

   Expand

   Table 3.1. LiveMode configuration

   Configuration field	Value type	Default	Description
   additional_packages	List[str]	[]	Additional packages to be installed into the upgrade image.
   autostart_upgrade_after_reboot	bool	True	If set to True, the upgrade starts automatically after the reboot. Otherwise, a manual trigger is required.
   capture_strace_info_into	str	''	If set to a non-empty string, leapp is executed under strace and results are stored within the provided file path.
   dracut_network	str	''	Dracut network arguments. Required if the `url_to_load_squashfs_`from option is set to a non-empty string.
   setup_network_manager	bool	False	If set to False, the Leapp tool enables Network Manager in the upgrade image.
   setup_opensshd_using_auth_keys	str	''	If set to a non-empty string, openssh daemon is set up within the upgrade image using the provided authorized keys file.
   setup_passwordless_root	bool	False	If set to True, the root account of the upgrade image has an empty password. Use with caution.
   squashfs_image_path	str	/var/lib/leapp/live-upgrade.img	Desired location of the upgrade image of the minimal target system.
   url_to_load_squashfs_image_from	str	''	URL of the desired upgrade image.

   Show more

   The following is an example of a /etc/leapp/actor_conf.d/livemode.yaml file:

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

   The example file results in the following actions:

   • The Leapp utility installs the vim package into the upgrade environment.
   • The upgrade does not start automatically after reboot. You must manually restart it. This allows you to manually inspect the system and verify that the upgrade finished as expected and the system is ready for use before starting.
   • The Leapp utility attempts to enable NetworkManager inside the upgrade environment by using the source system’s network profiles.
   • The Leapp utility enables the opensshd service. If the system establishes network access successfully, you can use SSH to log in to the upgrade environment by using the root account and interact with the system.