Skip to Content
Bash Script GuidesRHEL 10 to Rocky Linux from CIQ

RHEL 10 to Rocky Linux from CIQ

Applies to: RHEL 10.0, migrating to RLC Pro 10. The rlc-pro tier is the only tier available on EL10, and RHEL 10.0 is the tested point release.

Overview

migrate2rlc converts a Red Hat Enterprise Linux 10 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. The mechanics are the same EL package-swap path RHEL 8 and RHEL 9 use. What differs on EL10 is the scope. Its refusals are enforced by gates that stop the run before any migration step, before any package swap, repository rewrite or branding, while its untested-source limits are evidence statements rather than gates, since nothing refuses a run on their account. See Scope for what a refusal does and does not leave on the host.

Scope

  • The tested source is RHEL 10.0, migrating to RLC Pro 10. This is the combination the EL10 path was validated against, on the bash script and the Ansible playbook alike.
  • -t rlc-pro is the only tier accepted on EL10. -t rlc-plus and -t rlc-96-lts stop the run with EL10 currently supports the rlc-pro tier only, before any package swap, repository rewrite or branding (migrate2rlc.sh:16793-16797). rlc-plus-10 does exist as a depot channel, so the refusal is not about a missing channel. Nothing brands an EL10 host for the Plus tier and no EL10 Plus migration has been tested end to end, and a part-branded host is the one state this tool refuses to produce.
  • There is no tier change on EL10. The gate above runs on every invocation, including on a host already running RLC Pro 10, so a request for another tier is refused there too.
  • CentOS Stream 10 is refused outright, with its own message naming the reason, which is that Stream 10 repositories moved to mirror.stream.centos.org and the tool has not been updated or tested for that layout (migrate2rlc.sh:16805-16810).
  • Air-gapped migration is not available on EL10. The air-gap major list is EL8 and EL9 only (migrate2rlc.sh:144, gate at :16611-16615), and an EL10 host passing -m is refused with that list.
  • Oracle Linux 10, AlmaLinux 10 and Rocky Linux 10 pass the same EL family detection this host does, but none of them has been tested. Treat RHEL 10.0 as the supported EL10 source.
  • Verified on x86_64. The code carries no architecture gate on EL10, but no aarch64 EL10 migration has been exercised.

What a refused run leaves behind is worth stating exactly, because the run order matters. The pre-migration backup (-b/-B) runs before the tier, Stream 10 and FIPS gates, so those refusals all arrive after it. A run that asked for a backup and then hit one of those refusals has already written its backup archive and installed any helper packages the backup needed, the NFS client, cifs-utils, rsync or tar. An EFI host migrating with -r may also have had efibootmgr and mokutil installed by the preflight, which runs before the gates too. No release package has been swapped, no repository rewritten, nothing branded, and the backup share is unmounted when the run stops. The air-gap refusal is the one EL10 gate that fires before the backup, so it alone leaves nothing behind.

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/dnf database. The pre-flight runs dnf -y check and stops if it reports dependency or conflict errors. Fix those before migrating
  • FIPS mode must be disabled before migration. On EL9 the check is fips-mode-setup; EL10 does not ship that tool at all, so there the check reads the kernel's own flag at /proc/sys/crypto/fips_enabled (migrate2rlc.sh:1854-1878). Disable FIPS by the procedure your RHEL 10 documentation gives, reboot, then start
  • Satellite/Katello-registered systems cannot migrate while /etc/rhsm/ca/katello-server-ca.pem is present, unless you pass -K (or -e katello_bypass=true on the Ansible path). Without it the script exits with the exact commands needed to detach first. See Katello and Red Hat Satellite Sources in the root README before using -K
  • RHEL subscription-manager: unregister the system yourself first (subscription-manager unregister). As on EL8 and EL9, the script backs up your Subscription Manager certificates and records which repos are subscription-managed, but it does not unregister the system or disable those repos for you. An active subscription can leave stale, subscription-managed repos enabled during the swap

Migration Command

sudo bash migrate2rlc.sh -r -t rlc-pro -u USERNAME --token-file /root/.ciq-token

Replace USERNAME with your CIQ Depot username, and see below for the token file. This is the same invocation the EL8 and EL9 guides show; nothing about the command changes for EL10.

-r is what makes the script migrate rather than exit. Without it, the run only detects and validates the system, takes any backup you asked for, and migrates nothing. It does not reboot; -y does. Leave -y off and the script asks before rebooting, which is fine at a console. A non-interactive run (a runbook, a pipeline, ssh host <command>) has nothing to answer that prompt with, so the answer defaults to no and the host is left converted and still running the old kernel. Pass -y for any unattended run, or reboot by hand when the script tells you to.

Supplying the Depot token

Put the token in a file that only root can read, and pass the path with --token-file. This is the recommended form. Creating the file empty and private first keeps the token out of your shell history.

sudo install -m 600 /dev/null /root/.ciq-token sudo vi /root/.ciq-token

The file holds the token on one line and nothing else. Keep the mode at 0600. A token file that is group- or world-readable is rejected, the way ssh refuses a loose private key. -P FILE is a short alias for --token-file and behaves identically.

For an unattended run, set DEPOT_TOKEN in the environment instead of using a file. That is the supported form for CI. It needs MIGRATE2RLC_ACCEPT_DISCLAIMER=1 and -y -b skip so nothing waits for input. -p TOKEN still works and is discouraged, and the script warns on stderr when the token arrives that way. The full token rules, including the exit statuses for each bad-token-file case, are in the root README.

What Happens During Migration

The steps are the same EL package-swap sequence the RHEL 8 and RHEL 9 guides describe. In order:

  • subscription-manager certificates are backed up and subscription-managed repos are recorded, but not unregistered or disabled automatically (see Prerequisites)
  • RHEL release and branding packages (redhat-release, redhat-logos, and similar) are removed and their Rocky equivalents installed
  • The Rocky Linux and CIQ GPG keys are staged and verified (see GPG keys below); Red Hat's existing gpg-pubkey entries are not removed
  • A full distro-sync aligns all packages to Rocky Linux versions
  • The CIQ Depot CLI is installed from the EL10 client repository (https://depot.ciq.com/dlv2/depot-el10.x86_64/ on an x86_64 host) and the system is enrolled in the rlc-pro-10 depot product
  • The tier release package rlc-pro-release is installed. It exists for EL10, and it owns the RLC identity files the same way it does on EL9
  • A post-migration dnf update pulls tier branding and updated packages
  • Source-distribution residue is cleaned up. /etc/redhat-release is pointed at /etc/system-release where nothing owns it, and rhsmcertd is disabled
  • Third-party repos are re-enabled right after the post-migration update, and a systemd oneshot service is configured for post-reboot recovery, which re-enables them again after reboot as a fallback, restarts services, runs verify_migration.sh, removes the pre-migration kernel packages, and prints a summary

RHEL 10 ships no modular content, so the module-handling step finds nothing to convert on this source. That is a difference in what the distribution carries rather than a different code path.

The point of no return is the distro-sync. Once it has swapped the release packages there is no undo, and "rolling back" means restoring from a backup. Everything after that point repairs and reports; nothing after it reverses. Take a backup before you start, either with the script's -b option or your own process.

EL10 Specific Notes

GPG keys, and a different CIQ key on EL10

Two keys are staged, both embedded in the script and both verified against a pinned SHA512 digest before use, so no internet key fetch is trusted blindly.

The Rocky key for EL10 is RPM-GPG-KEY-Rocky-10 from https://dl.rockylinux.org/pub/rocky/RPM-GPG-KEY-Rocky-10 (migrate2rlc.sh:146-163). That is the single-key file at the top-level path, RSA4096, fingerprint FC22 6859 C086 0BF0 DDB9 5B08 5B10 6C73 6FED FC85. The versioned path under pub/rocky/10/... serves a two-key bundle with a different digest; the pin names the top-level file, so treat only that one as the key this script verifies.

The CIQ content key on EL10 is different from the one EL8 and EL9 use. EL8 and EL9 content is signed by CIQ Signing Key V2, but RLC 10 packages are signed by CIQ Signing Key RSA (RLC 10), key id 4EDCED55444998F8, and they do not verify against V2. The script stages the RLC 10 key from https://ciq.com/keys/rpm-gpg-key-ciq-10-rsa on EL10, pinned like the Rocky key (migrate2rlc.sh:183-213). A mismatch is fatal rather than a warning, because every RLC package this migration installs is verified against that one key.

If CIQ rotates the content key, the run stops and prints the observed SHA512 digest. Confirm the digest against CIQ, then re-run passing it with -k SHA512. That accepts exactly one named digest and nothing else, so it is not a way to silence a mismatch you cannot explain. It never applies to the depot client key.

Kernel

migrate2rlc installs the CIQ kernel explicitly on aarch64 EL9 only, so on EL10 no CIQ kernel is installed on any architecture. The post-migration dnf update takes whichever kernel-core is newest across the enabled repositories, and on x86_64 that is currently the stock Rocky kernel. A RHEL 10 x86_64 host that finishes on the stock Rocky kernel has migrated correctly. The end-of-run kernel report names what booted, so you do not have to work it out from the version string.

Secure Boot

The boot-chain replacement documented for EL9 x86_64, where the post-migration dnf update moves shim-x64 and grub2-efi-x64 to the CIQ builds, has not been measured on EL10. No claim is made here about which packages the EL10 update swaps, or about SBAT generations on an EL10 host. Take a snapshot or have console access to the firmware before you migrate an EL10 UEFI host, the same precaution the EL9 section asks for, because a boot chain that fails is not repairable from the running system.

FIPS

FIPS-enabled hosts are refused. On EL10 the check reads the kernel's own flag at /proc/sys/crypto/fips_enabled, because EL10 does not ship fips-mode-setup and a binary-only check would pass silently on a FIPS-enabled host. Disable FIPS first, reboot, then migrate.

Post-Migration Verification

The post-reboot recovery service runs verify_migration.sh for you and writes the result into /var/log/migrate2rlc.log. Read that first. Re-run it at any time with:

sudo bash /root/verify_migration.sh

Two line shapes carry the result. FAIL: marks one problem found, with the remedy where there is one. VERIFY-COMPLETE: is the last line and appears only when the script reached the bottom. If it is missing, the host is unverified rather than verified-clean, whatever the FAIL count says.

The tier assertion compares the tier you requested against the tier the host actually landed, reading the marker the migration wrote at /var/lib/migrate2rlc/requested_tier. On an EL10 Pro host the evidence is the installed rlc-pro-release package, and a healthy host reports TIER OK.

The kernel report tells you which kernel booted and how it compares to what is installed. Expect the stock Rocky kernel shape on x86_64, and read it as success. Every line of the kernel report is INFO: and none of it can fail a migration.

Manual spot checks:

cat /etc/os-release # NAME should show Rocky Linux from CIQ cat /etc/redhat-release # Should agree with /etc/system-release, and not say Red Hat systemctl is-enabled rhsmcertd # Should be disabled, or not installed depot list # Should show rlc-pro-10 as the enrolled product dnf repolist --enabled # CIQ depot and Rocky base repos, no RHEL repos rpm -q rlc-pro-release # The tier release package, present on EL10

Read the output, not the exit status. verify_migration.sh exits 0 even when it prints FAIL: lines, so count the failures instead:

sudo bash /root/verify_migration.sh | grep '^FAIL:'

No output from that command means no failures were reported.

Post-Migration Kernel and Boot Cleanup

The post-reboot recovery service also removes the pre-migration kernel packages, guarded so the running kernel and the last installed kernel-core are never removed; re-sweeps for boot entries orphaned by that removal; and regenerates the rescue kernel and initramfs against the surviving kernel via kernel-install. This runs automatically and there is no flag that turns it off.

This is destructive, and it removes a fallback you may be relying on. Before it runs, a host that boots badly can still recover by picking the old kernel at the GRUB menu. Once the pre-migration kernel packages are gone, that option is gone too. Recovery after this point is through the rescue entry (if one exists), or through console access or a snapshot. See Post-Migration Kernel and Boot Cleanup in the root README for the full detail, including the three verify_migration.sh checks this adds.

Air-Gapped Migration

Not available on EL10. Air-gap is validated for EL8 and EL9 only, and an EL10 host passing -m is refused with the major list before anything happens. If you need an offline EL10 migration, raise it with CIQ Support rather than attempting to mirror by hand; the mirror layout for EL10 has not been validated. See READMEs/airgap_migration_guide.md for what the EL8/EL9 air-gap path does cover.

Tier Changes

Not available on EL10. The EL10 tier gate runs on every invocation, so a host already running RLC Pro 10 that asks for rlc-plus or rlc-96-lts is refused exactly like a fresh host. Re-running to the same tier (-r -t rlc-pro) does work, and is the recovery path for a run that enrolled in depot but did not finish branding. For the EL9 tier permutations, see Tier Changes in the root README.

Ansible Path

The Ansible playbook migrates a RHEL 10.0 host with the same invocation shape as EL8 and EL9, and the same single-tier rule. See the EL 10 Ascender guide for the Ascender deployment and the standalone Ansible guide for direct ansible-playbook usage.

Troubleshooting

EL10 currently supports the rlc-pro tier only: You passed -t rlc-plus or -t rlc-96-lts on a RHEL 10 host. The run stopped before any package swap, repository rewrite or branding. If you also passed -b, the backup has already been taken and its helper packages installed, so the host is not untouched in that case; see Scope for the exact list. The backup share itself is unmounted on the way out. Re-run with -t rlc-pro, or use an EL9 host for the other tiers.

CentOS Stream 10 is not a supported migration source: Stream 10 content moved to mirror.stream.centos.org and the tool has not been updated or tested for that layout. There is no workaround in this release.

Air-gapped mode (-m) supports only these Enterprise Linux majors: 8, 9: EL10 cannot migrate air-gapped in this release. Migrate online.

FIPS refusal on start: The run read 1 from /proc/sys/crypto/fips_enabled and stopped before any migration step. If you passed -b, the backup has already been taken by then, helper packages included, so the host is not untouched in that case. Disable FIPS by the procedure your RHEL 10 documentation gives, reboot, and re-run.

GPG key errors during distro-sync: The staged keys are pinned, so a verification failure means either a staged key file was altered or CIQ rotated the content key. The log prints the observed SHA512. Confirm it against CIQ; if it is a genuine rotation, re-run with -k <observed digest>.

Migration fails at distro-sync: Check /var/log/migrate2rlc.log for the specific dnf error. Common causes are conflicting third-party packages, a broken RPM database, and network issues during package download.

Migration refuses to start on a Satellite-managed host: The host carries /etc/rhsm/ca/katello-server-ca.pem. Re-run with -K. See the Katello note in Prerequisites and the root README before using it.

FAIL: /etc/redhat-release still reports Red Hat Enterprise Linux: A source-distribution release package survived the swap and still owns the file. The log names the owning package. Remove it with dnf remove PACKAGE, then re-run.

Verification says the host is unverified: The output has no VERIFY-COMPLETE: line, so verify_migration.sh did not reach the bottom. Re-run it by hand with sudo bash /root/verify_migration.sh and read where it stops.

The host booted the stock Rocky kernel: This is not a failure on x86_64. See the Kernel note above.


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.

This tool automatically reports migration_outcome (success/failure) and whether the RLC Pro repo ended up configured, and nothing else. Pass -T to opt out. Pass -S to additionally share your source distribution and an optional failure note, captured to a local file only and never sent unless you attach it to a support ticket yourself.