Air-Gapped Migration (migrate2rlc)
Migrate an Enterprise Linux 8 or 9 system to Rocky Linux from CIQ (RLC Pro or RLC Plus) with no internet access on the machine being migrated. All packages are served from a local mirror you populate once from CIQ Depot.
This is the right path when your production hosts have no outbound egress (isolated network segments, classified environments, or strict no-internet policy). One host with internet access builds the mirror; every air-gapped host migrates from that mirror.
Scope
| Supported | Not supported in air-gap |
|---|---|
| Source: RHEL, Rocky, AlmaLinux, Oracle Linux, CentOS Stream 8/9 | CentOS 7 (needs Leapp first), EL10 |
Target tiers: rlc-pro, rlc-plus | rlc-86-lts, rlc-96-lts, Amazon Linux 2 |
| Architectures: x86_64, aarch64 | non-Enterprise Linux sources |
Both migrate2rlc.sh and migrate2rlc.yml | restore mode (-R) |
Combining -m with an unsupported tier, OS, or mode is rejected up front with
a clear error. Both version-pinned LTS tiers are excluded, so an air-gapped host
cannot be migrated to RLC Pro 8.6 LTS or RLC Pro 9.6 LTS with -m. Mirroring a
version-pinned channel and pinning releasever against it has not been built or
tested, and the flag combination is refused rather than half-supported.
How it works
[ Mirror host ] --(internet)--> CIQ Depot + dl.rockylinux.org
| setup_airgap_mirror.sh (rsync or reposync + GPG keys)
| serves http://<mirror>/depot/<repo-id>/...
v
[ Air-gapped targets ] migrate2rlc.sh -m http://<mirror>/depot
- no outbound internet
- all packages + GPG keys come from the mirror
A single -m MIRROR_URL flag puts the migration into air-gapped mode: it skips
every depot.ciq.com / internet probe, points all repositories at your mirror,
uses GPG keys embedded in the script (still verified against pinned checksums),
and never installs the depot CLI.
Prerequisites
On the mirror host (the one machine with internet):
- A CIQ Depot organization token. Export it as an environment variable, never
pass it on the command line:
RSYNC_PASSWORDfor the rsync method, orDEPOT_TOKENfor the reposync method.
- Disk for the mirror. Roughly 100 to 150 GB for two EL majors on one
architecture. Size precisely with
rsync --dry-run --statsbefore a full pull. rsync(rsync method) ordnf reposync/dnf-plugins-core(reposync method), plushttpdif you use--serve.
On each air-gapped target:
- Network reachability to the mirror host on HTTP/HTTPS only.
- A maintenance window. Migration swaps the distribution and reboots.
- The mirror must stay reachable for the entire run, including the
post-reboot recovery step, not only the up-front pre-flight check. That step
now also runs
verify_migration.sh, which queriesdnfand will report the host unverified if the mirror has gone away by then. - Ansible path only: a Python interpreter meeting your control node's
ansible-core floor (3.9 on 2.20 and newer, lower on older releases, and the
playbook derives it), installed before the host is
disconnected. The playbook's first play stops the run if there is none, and
it installs nothing. On EL8 that means
sudo dnf install -y python3.12while the host still has a package source, since the depot mirror carries the migration content rather than the target's own AppStream. The bash path needs none of this, which is one reason it is the better fit for air-gapped fleets.
For the Ansible path, on the control node: verify_migration.sh must sit
beside migrate2rlc.yml. The playbook copies it to each target and runs it after
reboot, and a pre-flight assertion refuses the run when it is missing, before
anything on the target has been changed. Both files are in the repository root.
Important: for EL9 Pro branding, the package rlc-pro-release must be
present inside the rlc-9-pro repository on your mirror, not rlc-9-core,
which carries only the generic rlc-release (the Plus tier's release
package). setup_airgap_mirror.sh mirrors rlc-9-pro unconditionally
alongside rlc-9-core, so a normal sync includes both; the migration prints a
loud warning if the Pro package is missing from the target's repos.
Step 1, build the mirror
Run on the internet-connected mirror host. Pick one method.
rsync method (rsync daemon at rsync.depot.ciq.com:873, module names equal
repo IDs, signed repodata preserved verbatim):
export RSYNC_PASSWORD="<your-org-token>"
sudo -E bash setup_airgap_mirror.sh \
--method rsync --user <org-user> \
--majors "9" --arches "x86_64" \
--serve --keys --verify
reposync method (HTTPS only; run on a host where depot login and
depot enable <product> have already configured the repos):
export DEPOT_TOKEN="<your-org-token>"
sudo -E bash setup_airgap_mirror.sh \
--method reposync --user <org-user> \
--majors "8 9" --arches "x86_64" \
--serve --keys --verify
--serve installs and configures httpd (with SELinux and firewalld handled)
to serve the mirror at http://<mirror>/depot. --keys stages the Rocky 8/9
and CIQ GPG keys under <dest>/keys/. --verify confirms every required
repository serves repodata/repomd.xml.
reposync note: --download-metadata is mandatory and the script always passes
it. Without it, modularity and group metadata are dropped and EL8 AppStream
module operations fail on the air-gapped node.
Step 2, run the migration
On each air-gapped target, point migrate2rlc at the mirror. Use an IP literal or a name your target can resolve without internet DNS.
Bash:
sudo bash migrate2rlc.sh -r -t rlc-pro -m http://<mirror>/depot -y
-r is what makes the script migrate rather than exit, and it confirms you accept
the risks. Without it, the run only detects and validates the system and takes
any backup requested with -b/-B; it migrates nothing on any source family.
It does not reboot. -y does, five seconds after the migration finishes,
and -y is also what suppresses every prompt. Drop -y and the run still
converts the host, then reaches the reboot prompt, takes the default "no"
because a non-interactive SSH session has nothing to answer with, and finishes.
That leaves the target converted and still running its old kernel, which is a
bad place to stop on an air-gapped machine. If you do drop -y and reboot by
hand later, the mirror must still be reachable at that moment, because the
post-reboot recovery step pulls from it. On the Ansible path the reboot is a
separate variable, -e auto_reboot=true, which the example below passes.
Ansible:
ansible-playbook migrate2rlc.yml \
-i inventory.ini \
-e airgapped=true \
-e mirror_base_url=http://<mirror>/depot \
-e depot_tier=rlc-pro \
-e accept_disclaimer=true \
-e auto_reboot=true
-e auto_reboot=true reboots each host as soon as its migration finishes.
Leave it out if you want to stage the reboots, and keep the mirror up until
the last host has come back, because the post-reboot recovery step still
pulls from it.
The migration writes a marker at /var/lib/migrate2rlc/airgap_mirror_url so the
verifier and any later tier change know the system was migrated air-gapped.
If your mirror requires authentication, also pass depot_username with either
depot_token_file or depot_token (Ansible), or -u with either --token-file
or -p (bash). Prefer the file form, at mode 0600, for the same reason as in a
connected migration. The token stays out of the argument list of the command you
run, and a token file that is group- or world-readable is rejected. -p and
depot_token still work and are discouraged, and the script warns when the token
arrives on the command line. Most air-gap mirrors are unauthenticated; in that case
no credentials are needed and the generated depot-rlc.repo carries empty
username and password values.
On an unauthenticated mirror you no longer have to think about a stray
DEPOT_TOKEN. An air-gapped run ignores a token that arrived from the
environment and says so on stderr, because this is the one path where
depot-rlc.repo is kept on the host permanently, so a credential picked up that
way would sit there for the life of the machine with no flag typed and no
warning. A token you supply deliberately is still used, which is what an
authenticated mirror needs: --token-file or -p on the bash path,
depot_token_file or depot_token on the Ansible path.
The generated depot-rlc.repo stays mode 0600 when it still carries
credentials, and relaxes to 0644 when it does not. That keeps an authenticated
mirror token root-only while still letting non-root dnf queries read a
credential-free permanent repo file.
Telemetry in air-gapped mode
Air-gapped mode does not change the automatic migration-outcome report described in the main README's
Telemetry and the Opt-In Survey section. The destination defaults to empty on every migration, air-gapped
or not, so no network call leaves the target either way; the two fields (migration_outcome,
rlc_pro_repo_configured) are still written to /var/lib/migrate2rlc/migration-summary.txt. -T /
-e migrate2rlc_telemetry_opt_out=true and -S / -e migrate2rlc_survey_consent=true work the same as
in a normal migration; the opt-in survey file is written locally and needs no network access to capture.
Secure Boot on EL9 x86_64. The post-migration dnf update runs against your
mirror rather than against depot.ciq.com, but it is the same update, so on an
EL9 x86_64 UEFI host it replaces shim-x64 and grub2-efi-x64 with the CIQ
builds if your mirror carries them. A full rlc-9-core sync does carry them,
and a full sync is what setup_airgap_mirror.sh performs. This is not optional
and no flag turns it off. SBAT was measured safe across all three shim builds
and both grub2 builds, so a Secure Boot host does not fail to boot from a
revocation, but the CIQ shim does ratchet the machine's SbatLevel forward one
way, which will refuse older rescue media. Read the full treatment in the root
README under "Secure Boot and the CIQ Boot Chain on EL9 x86_64" before migrating
a production Secure Boot host, and note that on an air-gapped host a machine that
will not boot is harder to recover than usual.
Step 3, verify
The post-reboot recovery service runs the verifier for you and writes the result
into /var/log/migrate2rlc.log (bash) or
/var/lib/migrate2rlc/migration-summary.txt (Ansible). Re-run it at any time:
sudo bash /root/verify_migration.sh
In air-gapped mode (auto-detected from the marker file, or forced with
--airgapped) the verifier treats the absent depot CLI as informational rather
than a failure, and asserts that depot-rlc.repo baseurls point at your mirror
and the expected repositories are enabled.
A clean run reports no FAIL: lines and ends with a VERIFY-COMPLETE:
line. Both conditions matter. A count of zero failures on its own cannot tell
"checked everything, found nothing" apart from "never ran", and on an air-gapped
host the second is the likelier of the two, because every dnf query in the
verifier depends on the mirror still being reachable. Each of those queries is
bounded at 90 seconds, so an unreachable mirror costs the run a few minutes and
then reports honestly rather than hanging. If the marker is absent, treat the
host as unverified rather than as verified-clean.
The mirror baseurl assertion compares literally rather than as a pattern, so a mirror URL containing regular-expression characters no longer matches a repo file pointing somewhere else. On an air-gapped host that assertion is the main thing standing between you and a machine quietly pulling from the wrong place, so it is worth reading rather than skimming.
The same post-reboot recovery step also removes the pre-migration kernel
packages, re-sweeps for boot entries orphaned by that removal, and
regenerates the rescue kernel and initramfs against the surviving kernel.
None of that needs the mirror, since it works from the local RPM database and
/boot, so it runs the same way air-gapped as it does connected. It is
destructive: once the pre-migration kernel packages are removed, the old
kernel is no longer a GRUB menu option to fall back to, and on an air-gapped
host that matters more than usual, because there is no internet fallback
either. Recovery after this point is through the rescue entry, console
access, or a snapshot. See the root README's "Post-Migration Kernel and Boot
Cleanup" section for the full detail, including the three new
verify_migration.sh checks and the separately tracked CUSP-4024 gap.
Run it as sudo, as above, for a complete check. The Plus tier's evidence is
a repository file that chmod 0600 root protects even off a mirror, so a
non-root run cannot read it.
verify_migration.sh also compares the tier you requested against the tier
the host actually landed, learning the requested tier from the marker
migrate2rlc wrote at migration time. For an air-gapped Pro migration on
EL9, a correct host reports TIER OK once rlc-pro-release is installed
(see the rlc-pro-release warning below if it is not). For an air-gapped
Plus migration, no artefact can ever prove the tier landed. Plus has no
release package of its own, and the depot CLI that would otherwise write a
product repo file is never installed air-gapped. That check correctly
reports TIER NOT ASSERTED (evidence) on every air-gapped Plus host; it is
not a failure and does not mean the migration is wrong. EL8, air-gapped or
not, ships no tier-specific release package at all and reports
TIER NOT ASSERTED (platform) for the same reason.
Judge the run by those lines and not by the exit status. verify_migration.sh
exits 0 whether or not it printed a failure, so a wrapper that checks only the
return code will read a failed migration as a success.
Command reference (air-gap flags)
| Flag | Meaning |
|---|---|
-m MIRROR_URL | Mirror base URL. Presence of this flag enables air-gapped mode. |
-g GPG_KEY_DIR | Use Rocky/CIQ GPG keys from this directory instead of the embedded copies (filenames: RPM-GPG-KEY-rockyofficial, RPM-GPG-KEY-Rocky-9, RPM-GPG-KEY-CIQ). Requires -m. |
-M REPO_FILE | Install a custom .repo file verbatim instead of the generated one (for a non-standard mirror layout). Requires -m. |
The Ansible equivalents are -e mirror_base_url=, -e mirror_gpg_key_dir=, and
-e mirror_repo_file= (all require -e airgapped=true).
GPG keys are verified against pinned SHA512 checksums whether they come from the
embedded copy or -g, so the trust chain holds offline. A -g directory must
contain the genuine upstream keys.
Troubleshooting
Pre-flight fails: a required repository is missing. The migration lists each
missing repo with a copy-pasteable rsync and reposync command to fix it.
Re-run setup_airgap_mirror.sh for those repo IDs, then re-run the migration.
EL9 Pro: rlc-pro-release is not installed warning. Your mirror's
rlc-9-pro repository does not contain rlc-pro-release (it is not in
rlc-9-core, which carries only the generic rlc-release). Re-sync
rlc-9-pro in full and confirm the package is present, then re-run
dnf install -y rlc-pro-release on the target.
GPG verification fails on a staged key. The key on your mirror or in your
-g directory does not match the pinned upstream key. Use the embedded keys
(omit -g) or re-fetch the genuine Rocky/CIQ keys.
Third-party repositories are unreachable after migration. Expected. Repos that pointed at the internet are re-enabled but cannot be reached from an air-gapped host. Mirror them separately if your workloads need them.
The migration stalls or fails mid-run on a repo error. Confirm the mirror host stayed up and reachable for the whole migration, including after the reboot.
Verification reports the host unverified, with no VERIFY-COMPLETE: line.
The verifier did not reach the bottom. On an air-gapped host the usual cause is
the mirror becoming unreachable between the reboot and the post-reboot recovery
step, which leaves the verifier's dnf queries timing out. Confirm the mirror is
up, then re-run sudo bash /root/verify_migration.sh by hand.
The Ansible run refused to start, naming verify_migration.sh. Copy
verify_migration.sh from the repository root into the same directory as
migrate2rlc.yml on the control node, then re-run. The assertion fires before
the play changes anything on the target, so there is nothing to undo.
The Ansible play failed on its last task. As of this release a verification
failure fails the play, where previously the Ansible path reported success
regardless. The host has still migrated and its third-party repos and services
have still been restored; the verdict is deliberately the final task. Read the
FAIL: lines in the failure message, or the summary on the host at
/var/lib/migrate2rlc/migration-summary.txt.
FAIL: lines for boot entries, leftover kernels, or the rescue image. See
the root README's "Post-Migration Kernel and Boot Cleanup" section for what
each means and how to remedy it; none of these three checks depend on the
mirror being reachable, since they read the local RPM database and /boot.
Katello / Satellite-registered sources
If the source carries /etc/rhsm/ca/katello-server-ca.pem, the migration stops
with a clear message before making changes. You have two ways forward, and the
message prints both.
The one that changes nothing on the host is to re-run with -K, which migrates
the host as it is and removes no subscription or CA state. -K combines with
the air-gap flags:
sudo bash migrate2rlc.sh -r -K -t rlc-pro -m http://<mirror>/depot -y
The Ansible equivalent adds -e katello_bypass=true to the air-gapped
invocation.
The other way is to detach first, by unregistering and cleaning
subscription-manager and removing the katello-ca-consumer package, then
re-running the migration.
Air-gapped hosts are the case where -K earns its keep, because a host with no
route to the internet often has no route to its Satellite either, and detaching
a host from a management plane it cannot currently reach is awkward. Note that
Satellite still believes it manages the host after a -K migration, so
unregister it once the host is back on a network that can reach Satellite,
after the migration rather than before. Full detail is in the Katello and Red
Hat Satellite Sources section of the root README.
See also
- Build the mirror:
setup_airgap_mirror.sh --help - CIQ Depot rsync: https://docs.ciq.com/depot/1/how-to-guides/how-to-rsync
- CIQ Depot reposync: https://docs.ciq.com/depot/1/how-to-guides/how-to-reposync