5/5 - (1 vote)

CentOS 7 to AlmaLinux 8 ELevate Migration Guide for cPanel Servers

The cPanel ELevate migration from CentOS 7 to AlmaLinux 8 carries significant risk but can succeed with meticulous preparation. Real-world experiences reveal that while many migrations complete successfully, unrecoverable failures (including unbootable servers) occur frequently enough that experienced sysadmins often recommend fresh installations over in-place upgrades. This guide documents the complete ELevate process, known blockers with resolutions, and hard-won lessons from production migrations.

The ELevate tool, developed by AlmaLinux and based on Red Hat’s leapp framework, has upgraded over 500,000 systems worldwide. However, cPanel servers introduce unique complexity: EasyApache 4 packages, database configurations, and third-party plugins like Imunify360 and JetBackup create additional failure points that generic ELevate documentation doesn’t address.

The cPanel ELevate workflow differs from standard ELevate

For cPanel servers, you must use the cPanel-specific ELevate fork (/scripts/elevate-cpanel) rather than running leapp directly. cPanel’s tool wraps the standard ELevate process with pre-flight checks for cPanel services, handles EA4 package transitions, and manages service restarts across the multi-reboot upgrade cycle.

Critical prerequisites before starting:

CentOS 7 or CloudLinux 7 must run cPanel & WHM version 110
Valid cPanel license (and CloudLinux license if applicable)
MySQL 8.0 or MariaDB 10.3+ (older versions block the upgrade)
All PHP versions must be 7.2 or higher for AlmaLinux 8
JetBackup must be version 5+ (JetBackup 4 will block)
Minimum disk space: 5 GB root, 120 MB /boot, 1.5 GB /usr/local/cpanel, 5 GB /var/lib

The migration executes across five stages with automatic reboots. Stage 1 performs pre-upgrade checks, Stage 2 prepares the system, Stage 3 runs the leapp upgrade creating the upgrade initramfs, Stage 4 reboots into the upgrade environment and transforms the OS, and Stage 5 completes cPanel restoration and cleanup. Expect 45 minutes to 2+ hours of downtime depending on system complexity.

Basic workflow commands:

# Download latest elevate script
wget -O /scripts/elevate-cpanel https://raw.githubusercontent.com/cpanel/elevate/release/elevate-cpanel
chmod 700 /scripts/elevate-cpanel

# Run pre-check (DO THIS FIRST - it identifies blockers)
/scripts/elevate-cpanel --check

# Start the upgrade after resolving all blockers
/scripts/elevate-cpanel --start

# If interrupted, continue from where you left off
/scripts/elevate-cpanel --continue

# Check status during multi-stage process
/scripts/elevate-cpanel --status

Kernel and system blockers require pre-migration cleanup

The leapp preupgrade check generates a report at /var/log/leapp/leapp-report.txt identifying inhibitors that must be resolved before proceeding. Several kernel-level blockers appear consistently across migrations.

Multiple kernel-devel packages installed will halt the upgrade immediately. DNF cannot produce a valid upgrade transaction with multiple kernel versions present:

# List all kernel packages
rpm -qa kernel\*

# Remove old kernels, keeping only the currently running version
yum -y remove kernel-devel-3.10.0-1160.45.1.el7 kernel-devel-3.10.0-1160.31.1.el7

Deprecated kernel drivers (pata_acpi, floppy) must be unloaded and blacklisted:

# Unload deprecated modules
sudo rmmod pata_acpi
sudo rmmod floppy

# Blacklist permanently
echo "blacklist pata_acpi" >> /etc/modprobe.d/blocklist.conf
echo "blacklist floppy" >> /etc/modprobe.d/blocklist.conf

SSH root login configuration changes between RHEL 7 and 8. OpenSSH will no longer allow root password login by default:

echo "PermitRootLogin yes" | sudo tee -a /etc/ssh/sshd_config

The leapp answer file requires manual confirmation for certain checks. Missing answers will block the upgrade:

# Confirm PAM PKCS11 module removal
sudo leapp answer --section remove_pam_pkcs11_module_check.confirm=True

# Confirm VDO device check
sudo leapp answer --section check_vdo.confirm=True

EasyApache 4 packages create the most common cPanel-specific blockers

Forum reports and GitHub issues consistently cite EA4 package incompatibilities as primary upgrade blockers. The error message explicitly lists problematic packages:

“One or more EasyApache 4 package(s) are not compatible with AlmaLinux 8. Please remove these packages before continuing: ea-openssl-devel, ea-php74-php-ioncube12, ea-php81-php-ioncube12“

Remove incompatible EA4 packages before migration:

# Remove ea-openssl-devel (CentOS 7 uses ea-openssl; AlmaLinux 8 uses ea-openssl11)
rpm -e --nodeps ea-openssl-devel

# Remove unsupported ioncube packages for older PHP versions
rpm -e --nodeps ea-php74-php-ioncube12 ea-php81-php-ioncube12

# Remove redis packages that cause conflicts
rpm -e --nodeps ea-php74-php-redis ea-php80-php-redis

PHP version restrictions are strict for AlmaLinux 8 targets:

# Remove PHP versions below 7.2 for AlmaLinux 8
for version in 54 55 56 70 71; do
  rpm -qa --qf '%{NAME}\n' | grep -E "^ea-php${version}-" | xargs yum -y remove 2>/dev/null
done

# Clean up orphaned PHP directories that may still trigger blockers
ls -la /opt/cpanel/ | grep ea-php
# Manually remove any old PHP directories if packages already removed

Orphaned PHP package detection (GitHub Issue #159) can block upgrades even after uninstallation. Users report ea-php71 showing as blockers when folders remain in /opt/cpanel/ after package removal. Clean these directories manually.

Third-party repository conflicts require systematic cleanup

Any repositories beyond the default CentOS 7 and EPEL sets will generate blockers if they have installed packages. The elevation process cannot validate package upgrade paths from unsupported sources.

Common third-party repositories that block upgrades:

Remi (PHP packages)
Dell OMSA
Nginx (Engintron)
Zabbix
Acronis cPanel backup
Vultr-specific repos
LiquidWeb/SourceDNS repos
Microsoft Azure repos

Repository cleanup procedure:

# Identify packages from non-standard repos
yum list installed | grep -v "@base\|@updates\|@epel\|@cp"

# List packages from specific repo (example: Remi)
yum list installed | grep @remi

# Disable problematic repositories
yum-config-manager --disable remi-safe
yum-config-manager --disable remi
yum-config-manager --disable nginx

# Remove packages from unsupported repos
yum remove $(yum list installed | grep @remi | awk '{print $1}')

# Remove repository files entirely
rm -f /etc/yum.repos.d/remi*.repo
rm -f /etc/yum.repos.d/nginx*.repo

# Clean yum cache
yum clean all

EPEL is explicitly supported for AlmaLinux migrations, but should be reinstalled post-migration:

# Post-migration EPEL installation for AlmaLinux 8
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
dnf config-manager --set-enabled powertools

CloudLinux rollout repository errors appear during some migrations with SSL certificate validation failures:

# Temporarily disable rollout repos
yum-config-manager --disable cloudlinux-rollout-*
yum-config-manager --disable cloudlinux-ea4-rollout-*

MySQL and MariaDB version requirements block unprepared servers

AlmaLinux 8 requires MySQL 8.0 or MariaDB 10.3+. Servers running older database versions cannot proceed until upgraded. cPanel will offer automatic MariaDB migration during elevation, but understanding the constraints is critical.

Key database migration considerations:

Once migrated to MariaDB, you cannot switch back to MySQL on cPanel servers
MySQL upgrades cannot be in progress when starting elevation
If MySQL service is disabled pre-elevate, Stage 4 will fail (GitHub Issue #287)

Fix disabled MySQL service before starting:

whmapi1 configureservice service=mysql enabled=1 monitored=0

Upgrade database version before elevation:

# Upgrade to MariaDB 10.6 via WHM API
/usr/local/cpanel/bin/whmapi1 start_background_mysql_upgrade version=10.6

# Monitor upgrade progress
tail -f /var/cpanel/logs/mysql_upgrade.log

CloudLinux users face additional complexity: cPanel installs MySQL 8 by default on CloudLinux 8 installations, and migration from MySQL 8 to MariaDB 10.x is not supported due to system table differences. Plan your database version strategy carefully before initiating elevation.

JetBackup, Imunify360, and other third-party cPanel plugins

JetBackup 4 does not support AlmaLinux 8/9 and will be detected as a hard blocker. You must upgrade to JetBackup 5+ or uninstall completely before migration.

Post-migration JetBackup 5 issues frequently reported:

MongoDB authentication error occurs when yum renames the auth file during upgrade:

# Restore MongoDB auth file
mv /usr/local/jetapps/etc/.mongod.auth.rpmsave /usr/local/jetapps/etc/.mongod.auth

JetBackup config backup errors (“Item Never Finished”):

yum install jetphp81-zip --enablerepo=jetapps,jetapps-stable
yum update 'jet*' --disablerepo=* --enablerepo=jetapps,jetapps-stable
service jetbackup5d restart

Imunify360 is fully compatible with AlmaLinux 8 and 9. The elevation process specifically recognizes Imunify360’s hardened PHP versions and allows upgrades to proceed. Ensure your Imunify360 installation is current (version 3.11+ has explicit ELevate support).

ConfigServer Security & Firewall (CSF) breaks frequently after migration due to OS-specific settings in /etc/csf/csf.conf. Users report lfd service timeout failures:

# Post-migration CSF reinstallation
cd /usr/src
rm -fv csf.tgz
wget https://download.configserver.com/csf.tgz
tar -xzf csf.tgz
cd csf
sh install.sh
systemctl restart csf lfd

Critical CSF warning: Do not simply restore your pre-migration csf.conf backup file. The “OS Specific Settings” section contains paths that differ between CentOS 7 and AlmaLinux 8. Restoring the full file will break CSF again. Manually migrate only your custom rules and settings.

LiteSpeed Web Server is compatible with AlmaLinux 8/9 for operation, but the installation scheme is incompatible with the ELevate process itself. LiteSpeed will not be automatically upgraded during elevation. Plan for manual LiteSpeed reinstallation/reconfiguration post-migration.

Real migration failures reveal critical gotchas

Forum reports from AlmaLinux, cPanel GitHub issues, and hosting communities document serious failures that official documentation doesn’t adequately warn about.

Server becomes unbootable after Stage 4 reboot (AlmaLinux Forums, July 2023):

“While upgrading the server did its reboot as it normally does, but the system never came back on, we looked at the console and saw an error showing it was not bootable and then another error showing the drive was not found the system then goes into emergency mode”

GitHub Issue #215 reports identical symptoms: server down after Stage 4, no SSH access, no ability to submit cPanel support ticket without Support Access ID. This failure mode requires out-of-band console access (IPMI, KVM, physical access) for recovery.

Network configuration lost (DirectAdmin Forums):

“Be careful with Elevate. I have successfully migrated CentOS 7 to Almalinux 8 on multiple servers. But just tried with one server to Almalinux 9, there were several issues: network missing (have to manually configure again, even that, the settings seem to be disappeared after rebooting)”

Multiple network interfaces with kernel naming (ethX) create inhibitors. cPanel ELevate offers to rename ethX to cpethX automatically. Accept this option. Manual renaming requires updating both the config file names and device references inside:

mv /etc/sysconfig/network-scripts/ifcfg-eth0 /etc/sysconfig/network-scripts/ifcfg-cpeth0
sed -i 's/eth0/cpeth0/g' /etc/sysconfig/network-scripts/ifcfg-cpeth0

Linode’s Lassie watchdog (GitHub Issue #274) interferes with elevation reboots, causing failures. Disable Lassie before starting migration on Linode servers.

OVH proactive monitoring must be acknowledged:

touch /var/cpanel/acknowledge_ovh_monitoring_for_elevate

Post-migration service failures and recovery procedures

Even successful migrations often require post-upgrade service restoration.

CCS (CalendarServer) service failure is common:

# Remove and reinstall CCS components
dnf -y remove cpanel-ccs-calendarserver cpanel-z-push
rm -rf /opt/cpanel-ccs/
dnf -y install cpanel-ccs-calendarserver cpanel-z-push
/usr/local/cpanel/bin/servers_queue run
/scripts/restartsrv_cpanel_ccs --status

Full service verification after migration:

# Verify OS version
cat /etc/redhat-release

# Check for remaining EL7 packages (should be minimal)
rpm -qa | grep el7

# Restart all cPanel services
/scripts/restartsrv_httpd
/scripts/restartsrv_mysql
/scripts/restartsrv_exim
/scripts/restartsrv_cpsrvd
/scripts/restartsrv_named

# Full service check
/scripts/checkservices

Reinstall PHP packages that were removed during elevation:

# Example: Reinstalling PHP 8.1 packages post-migration
yum install -y ea-php81-php-ioncube10 ea-php81-php-soap ea-php81-php-zip \
  ea-php81-php-xml ea-php81-php-mbstring ea-php81-php-opcache ea-php81-php-mysqlnd \
  ea-php81-php-gd ea-php81-php-curl ea-php81-php-intl ea-php81-php-common ea-php81-php-cli

Experienced sysadmins recommend caution over speed

The community consensus from XenForo, AlmaLinux forums, and hosting communities is clear: in-place upgrades on production cPanel servers carry substantial risk.

“I highly doubt any panel would support a major OS upgrade in place… I would never do an in-place upgrade of something so complex like cpanel. I actually did this exact thing last year, I spun up a new AlmaLinux 8 server to replace our CentOS 7 and then migrated the data over to the new server.”

cPanel’s official disclaimer on the elevate-cpanel repository: “We do not guarantee the functionality of software in this repository. You assume all risk for use of any software that you install from this repository. Installation of this software could cause significant functionality failures, even for experienced administrators.”

Best practices from successful migrations:

Always create a full server snapshot/backup before starting. VM snapshots or full disk images that allow complete rollback are essential.
Test in a sandbox environment first with a cloned production configuration.
Ensure out-of-band console access (IPMI, KVM, VNC, or physical). SSH will be unavailable during failures.
Schedule generous maintenance windows (minimum 2-4 hours for complex servers).
Run /scripts/elevate-cpanel --check multiple times and resolve every blocker before starting.
Document your exact pre-migration state including package lists, configurations, and service status.
Have a rollback plan that doesn’t depend on the server booting successfully.

The safer alternative: Spin up a new AlmaLinux 8 server, configure it fresh, and migrate accounts using cPanel’s transfer tools. This approach adds complexity but eliminates the risk of unrecoverable in-place upgrade failures. Multiple experienced admins report this method results in less than 2 hours total downtime with significantly lower risk.

Conclusion

The CentOS 7 to AlmaLinux 8 ELevate migration for cPanel servers is technically feasible but demands meticulous preparation. Pre-migration verification using /scripts/elevate-cpanel --check is non-negotiable. Every blocker must be resolved before starting. EA4 package conflicts, unsupported repositories, and database version requirements are the most common failure points.

Third-party plugins introduce unpredictable complications: JetBackup requires version 5+, CSF typically needs complete reinstallation post-migration, and LiteSpeed requires manual attention. Real-world failures (including unbootable servers) occur with enough frequency that snapshot backups and console access are mandatory, not optional.

For mission-critical production servers with complex configurations, the community wisdom favors fresh installations over in-place upgrades. The ELevate tool works, but the consequences of mid-upgrade failures on production cPanel servers are severe enough that the additional work of migration to a fresh server may be the more prudent choice.