RHEL 9 to Rocky Linux from CIQ

Applies to: RHEL 9.x on x86_64 and aarch64

Overview

migrate2rlc converts a Red Hat Enterprise Linux 9 system to Rocky Linux from CIQ (RLC) in place. The script swaps RHEL release packages for their Rocky equivalents, runs a distro-sync to align all installed packages, then enrolls the system in CIQ Depot for ongoing updates and the CIQ kernel.

Prerequisites

• Root or sudo access on the target system
• Active CIQ Depot credentials (username and token)
• Network connectivity to depot.ciq.com and Rocky Linux mirrors
• Working DNS resolution
• Clean RPM database (run rpm --rebuilddb if in doubt)
• FIPS mode must be disabled before migration. Run fips-mode-setup --disable and reboot before starting. The script cannot safely swap crypto packages while FIPS enforcement is active.
• RHEL subscription-manager: detaching the system before migration is recommended. The script handles this automatically, but pre-detaching avoids edge cases with stale entitlement certificates.
• Cloud instances (AWS, Azure, GCP): RHUI packages will be detected and removed during migration. No manual action is needed, but be aware that cloud-specific RHEL repos will no longer be available after migration.

Migration Command

sudo bash migrate2rlc.sh -r -t rlc-pro -u USERNAME -p TOKEN

The -r flag triggers a reboot after migration completes. Replace USERNAME and TOKEN with your CIQ Depot credentials.

Available Tiers

• rlc-pro : RLC Pro (CIQ kernel, security updates, depot access)
• rlc-plus : RLC Plus (extended support, additional packages)
• rlc-96-lts : RLC LTS 9.6 (long-term support, version-pinned to 9.6)

Note: rlc-96-lts requires the system to be running Rocky 9.6 packages. Systems on 9.7 or later cannot use this tier. The script validates the minor version and exits with a clear message if the version is too new.

What Happens During Migration

• subscription-manager is detached and disabled to prevent conflicts
• RHEL release packages (redhat-release, redhat-logos) are swapped for Rocky equivalents (rocky-release, rocky-logos)
• RHUI packages are detected and removed on cloud instances
• Red Hat GPG keys are replaced with Rocky Linux and CIQ GPG keys
• A full distro-sync aligns all packages to Rocky Linux versions
• The CIQ Depot CLI is installed and the system is enrolled in the selected tier
• The rlc-pro-release package is installed (for rlc-pro tier), or rlc-lts96-release (for rlc-96-lts tier)
• The CIQ kernel is installed and GRUB is updated to boot it by default
• A systemd oneshot service is configured for post-reboot recovery, which re-enables third-party repos and validates service health

RHEL 9 Specific Notes

FIPS mode: Must be disabled before migration. RHEL 9 uses openssl-fips-provider which conflicts with Rocky's version during the distro-sync. Run fips-mode-setup --disable, reboot, then migrate. You can re-enable FIPS after migration if needed.

subscription-manager deregistration: The script calls subscription-manager remove --all and subscription-manager unregister before starting the package swap. If these commands fail (expired subscription, offline system), the script continues.

RHUI packages: On cloud instances, packages like rh-amazon-rhui-client or rhui-azure-rhel9 are removed automatically. The script detects these by pattern matching and handles them without manual intervention.

rlc-pro-release package: On EL9, the rlc-pro-release package is installed for the rlc-pro tier. This package sets the content of /etc/redhat-release and should not be modified manually.

CIQ kernel naming: On x86_64, CIQ kernel versions use a .ciq. infix (for example, 5.14.0-611.36.1.el9_7.ciq.3). On aarch64, the suffix is _ciq (for example, 5.14.0-611.36.1+2.1.el9_7_ciq).

openssl-fips-provider-so: On RHEL 9 (and Oracle Linux 9), the openssl-fips-provider-so package may need to be removed before the pre-migration dnf update to avoid file conflicts with Rocky's openssl-fips-provider. The script handles this automatically.

Post-Migration Verification

After reboot, confirm the migration succeeded:

cat /etc/os-release

The NAME field should show "Rocky Linux from CIQ" or similar.

uname -r

The kernel version should contain .ciq. (x86_64) or _ciq (aarch64).

depot list

Should show the enrolled tier product as enabled.

dnf repolist

Should show CIQ depot repos and Rocky Linux base repos. No RHEL repos should be present.

Tier Changes

You can switch between tiers at any time by re-running the script with a different -t flag. For example, to move from Pro to Plus:

sudo bash migrate2rlc.sh -r -t rlc-plus -u USERNAME -p TOKEN

The script detects the existing RLC installation and performs a tier change rather than a full migration.

Troubleshooting

FIPS conflict during distro-sync: If the migration fails with a file conflict involving openssl-fips-provider, confirm FIPS was disabled before migration. Run fips-mode-setup --check to verify. If FIPS is still active, disable it, reboot, and re-run the script.

subscription-manager conflicts: If subscription-manager was not cleanly detached and the package swap fails, run subscription-manager remove --all and subscription-manager unregister manually, then re-run the script.

RHUI leftovers: If RHUI repo files remain in /etc/yum.repos.d/ after migration, remove them manually. The script attempts to clean these, but some cloud-specific packages install additional repo configs.

GPG key errors during distro-sync: If dnf distro-sync fails with GPG verification errors, run rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-Rocky-9 and retry.

Third-party repos disabled post-migration: The script disables third-party repos during migration to prevent conflicts. They are re-enabled by the post-reboot recovery service. If a repo was not re-enabled, check /etc/yum.repos.d/ for .rpmsave files.

DISCLAIMER

The migrate2rlc script and playbook are provided "as is" without warranty of any kind, express or implied. Use of these tools is entirely at your own risk. CIQ, Inc. assumes no responsibility or liability for any data loss, system downtime, service disruption, or other damage resulting from the use or misuse of these tools. It is the user's responsibility to ensure adequate backups and testing in a non-production environment before performing any migration on production systems.