Migration to RLC Guide (migrate2rlc)

Migrate Enterprise Linux or Amazon Linux 2 to Rocky Linux from CIQ.

Overview

migrate2rlc converts an existing Linux system to Rocky Linux from CIQ (RLC Plus, RLC Pro, or RLC Pro 9.6 LTS) using CIQ Depot repositories. It supports two OS families across two architectures:

Enterprise Linux 8 and 9 (RHEL, Oracle Linux, CentOS Stream, AlmaLinux, Rocky Linux)
Amazon Linux 2 (blue/green migration to Rocky 9.6 LTS on AWS)

Two migration methods are available:

A) Bash script: run directly on the target system
B) Ansible playbook: run remotely via CIQ Ascender or standalone Ansible

Supported Source Distributions

Enterprise Linux (direct package swap + `distro-sync`)

Red Hat Enterprise Linux (RHEL) 8.x and 9.x
Oracle Linux 8.x and 9.x (including UEK kernel systems)
CentOS Stream 8 and 9
AlmaLinux 8.x and 9.x
Rocky Linux 8.x and 9.x (community to RLC upgrade, no package swap needed)

Amazon Linux 2 (blue/green on AWS)

Amazon Linux 2 (x86_64 and aarch64/Graviton)

Architecture Support

Both x86_64 and aarch64 are fully supported for EL 8/9 migrations. CIQ kernels are available for both architectures. Naming convention differs:

x86_64: .ciq. suffix (e.g., 5.14.0-611.36.1.el9_7.ciq.3)
aarch64: _ciq suffix (e.g., 5.14.0-611.36.1+2.1.el9_7_ciq)

Amazon Linux 2 supports both x86_64 and aarch64 (Graviton).

Product Tiers

Tier	Description
RLC Plus	Free tier with Portal registration. CIQ-built kernel, GPU drivers, community support.
RLC Pro	Enterprise tier. Plus + FIPS 140-3, proactive bug fixes, SLA, indemnification.
RLC Pro 9.6 LTS	Long-term support for Rocky 9.6. Version-pinned repositories. EL9 only.

Switch tiers anytime by re-running the script with a different -t flag.

Key Features

Auto-detects OS family and routes to the appropriate migration path
Amazon Linux 2 blue/green migration: assesses source, provisions Rocky 9.6 target on AWS, enrolls in depot
aarch64 CIQ kernel explicit install after migration
The script automatically detects third-party repositories and packages before migration; during migration, third-party repos are temporarily disabled to prevent conflicts with the distro-sync, and after migration they are re-enabled, while detected third-party services (Docker, nginx, httpd, PostgreSQL, Redis, k3s, Elasticsearch, etc.) are monitored after migration and their status is reported in the migration summary
Dynamic conflict detection (pattern-based, no hardcoded repo names)
Tier change support (Pro, Plus, LTS, all combinations)
Post-reboot auto-recovery via systemd oneshot service
Live service monitoring (per-service/repo status every 60s, 10 min timeout)
Migration summary always shown (pass or fail) with troubleshooting commands
GRUB boot entry fix: updates grubenv saved_entry after kernel swap
Edge case handlers for HPC/enterprise environments (immutable repos, kernel versionlock, NVIDIA DOCA, Mellanox kmod, Foreman/Satellite repos)
Oracle Linux UEK kernel force-removal before swap
Community Rocky Linux optimized path (tier change only, no package swap)
depot CLI integration with duplicate repo cleanup
Pre-migration backup with 7 target options (local, NFS, SMB, S3, rsync, SFTP, diskimage)
Automated restore via -R SOURCE (file-level or block-level, mutually exclusive with -r)
DNS resolution and network connectivity pre-flight checks

Prerequisites

CIQ Depot credentials (username and token)
- Obtain from the CIQ Portal at https://portal.ciq.com
- RLC Plus can be obtained through a free Portal registration
- RLC Pro requires an active subscription
System requirements
- Root access on the target system
- Network access to https://depot.ciq.com
- Working DNS resolution
- For EL systems: clean RPM database (run dnf check to verify)
Pre-migration checklist
- The script offers built-in backup options, or feel free to use your own backup process
- Ensure the system is fully updated (dnf update -y)
- Disable FIPS mode if enabled (EL9 only): fips-mode-setup --disable
Amazon Linux 2 prerequisites
- AWS CLI installed and configured with ec2 permissions
- AWS Marketplace subscription for Rocky Linux 9.6 LTS from CIQ
- IMDS reachable

Quick Start

Enterprise Linux 8/9


sudo bash migrate2rlc.sh -r -t rlc-pro -u YOUR_USER -p YOUR_TOKEN

Amazon Linux 2


sudo bash migrate2rlc.sh -r -t rlc-96-lts -u YOUR_USER -p YOUR_TOKEN

Ansible Playbook (best deployed with CIQ Ascender)


ansible-playbook migrate2rlc.yml \
  -e depot_tier=rlc-pro \
  -e depot_username=YOUR_USER \
  -e depot_token=YOUR_TOKEN \
  -i inventory

Command-Line Options

Flag	Description
`-r`	Required to migrate. Confirms you accept the risks. Triggers automatic reboot after migration.
`-t TIER`	Target tier: `rlc-plus`, `rlc-pro`, or `rlc-96-lts` (default: `rlc-pro`).
`-u USER`	CIQ Portal username.
`-p TOKEN`	CIQ Portal token.
`-y`	Non-interactive mode (skip prompts, auto-confirm; also used with `-R`).
`-a`	Assess-only mode (AL2 only: run inventory + compatibility analysis, no provisioning).
`-e EXCLUDE`	Comma-separated packages to exclude from `distro-sync` (EL only).
`-b MODE`	Backup mode: `skip`, `local`, `nfs`, `smb`, `s3`, `rsync`, `sftp`, `diskimage`.
`-B TARGET`	Backup target path/URI (required for all `-b` modes except `skip`).
`-R SOURCE`	Restore from a migrate2rlc backup. Mutually exclusive with `-r`. Accepts `/path` (local), `host:/path` (NFS), `//srv/share` (SMB), `s3://bucket/path` (S3), or `user@host:/path` (rsync/SFTP).
`-V`	Generate RPM verification info before and after migration.
`-h`	Show help.

Pre-Migration Backup

The script offers built-in backup before migration begins. If -b is not specified and the script runs interactively, it prompts for a backup choice.

Mode	Target Format	Notes
skip	N/A	User handles backup, confirms to proceed
local	/mnt/backup	Local drive or partition
nfs	server:/path	Mount NFS share, backup, unmount
smb	//server/share	Mount Samba/CIFS share (credentials via env vars or prompt)
s3	s3://bucket/prefix	AWS S3 (supports env vars and named profiles)
rsync	user@host:/path	SSH-based rsync
sftp	user@host:/path	SSH-based SFTP
diskimage	/mnt/backup	Block-level partition clone via partclone/dd (local only)

Backup captures: full filesystem (excluding /proc, /sys, /dev, /run, /tmp), package manifest, service states, network config, repo config, crontabs. Each backup includes a RESTORE-INSTRUCTIONS.txt file with recovery steps.

Post-Migration Verification

After migration and reboot, verify:


cat /etc/os-release          # Should show Rocky Linux from CIQ
uname -r                     # Should show CIQ kernel (.ciq. suffix)
depot list                   # Should show enrolled product
dnf repolist --enabled       # Should show CIQ depot repos
systemctl is-active docker   # Check third-party services

A standalone verification script is available: verify_migration.sh

Tier Changes

To change tiers on an already-migrated system, re-run the script with the desired tier:


sudo bash migrate2rlc.sh -r -t rlc-plus -u YOUR_USER -p YOUR_TOKEN

All six tier permutations are supported: Pro to Plus, Plus to Pro, Pro to LTS, LTS to Pro, Plus to LTS, LTS to Plus.

Distro-Specific Guides

For detailed, per-distribution migration instructions:

Bash Script Guides

Distribution	Guide
RHEL 8	RHEL 8 Guide
RHEL 9	RHEL 9 Guide
Oracle Linux 8	Oracle Linux 8 Guide
Oracle Linux 9	Oracle Linux 9 Guide
AlmaLinux 8	AlmaLinux 8 Guide
AlmaLinux 9	AlmaLinux 9 Guide
Rocky Linux 8	Rocky Linux 8 Guide
Rocky Linux 9	Rocky Linux 9 Guide
CentOS Stream 8	CentOS Stream 8 Guide
CentOS Stream 9	CentOS Stream 9 Guide
Amazon Linux 2	Amazon Linux 2 Guide

Ansible/Ascender Playbook Guides

Scope	Guide
EL 9 via Ascender	EL 9 Ascender Guide
EL 8 via Ascender	EL 8 Ascender Guide
AL2 via Ascender	AL2 Ascender Guide
Standalone Ansible	Standalone Ansible Guide

Troubleshooting

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

Depot login fails: Verify credentials at https://portal.ciq.com. The token (not password) is required: depot login -f -u USERNAME -t TOKEN.

System fails to boot after migration: Check GRUB configuration. The script updates grubenv saved_entry, but custom GRUB configurations may need manual adjustment. Boot from a rescue image and check /boot/grub2/grubenv.

Third-party services not running: Check the migration summary at /var/log/migrate2rlc.log. Services that were running before migration should restart automatically. If not, check journalctl -u SERVICE_NAME.

Support

Questions or issues? Open a ticket at https://portal.ciq.com.

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.

Overview

Migration to RLC Guide (migrate2rlc)

Overview

Supported Source Distributions

Enterprise Linux (direct package swap + distro-sync)

Amazon Linux 2 (blue/green on AWS)

Architecture Support

Product Tiers

Key Features

Prerequisites

Quick Start

Enterprise Linux 8/9

Amazon Linux 2

Ansible Playbook (best deployed with CIQ Ascender)

Command-Line Options

Pre-Migration Backup

Post-Migration Verification

Tier Changes

Distro-Specific Guides

Bash Script Guides

Ansible/Ascender Playbook Guides

Troubleshooting

Support

DISCLAIMER

Enterprise Linux (direct package swap + `distro-sync`)