RHEL 10 to Rocky Linux from CIQ
Applies to: RHEL 10.0, migrating to RLC Pro 10. The
rlc-protier 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-prois the only tier accepted on EL10.-t rlc-plusand-t rlc-96-ltsstop the run withEL10 currently supports the rlc-pro tier only, before any package swap, repository rewrite or branding (migrate2rlc.sh:16793-16797).rlc-plus-10does 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-mis 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 checkand 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.pemis present, unless you pass-K(or-e katello_bypass=trueon 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-managercertificates 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-pubkeyentries are not removed - A full
distro-syncaligns 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 therlc-pro-10depot product - The tier release package
rlc-pro-releaseis installed. It exists for EL10, and it owns the RLC identity files the same way it does on EL9 - A post-migration
dnf updatepulls tier branding and updated packages - Source-distribution residue is cleaned up.
/etc/redhat-releaseis pointed at/etc/system-releasewhere nothing owns it, andrhsmcertdis 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.