cPanel ELevate FAQ

The cPanel ELevate FAQ is designed to address common technical questions and issues encountered when working with cPanel ELevate. Whether troubleshooting server configurations, managing user accounts or preparing for system upgrades. You will find practical answers and guidance below to support efficient system administration.

cPanel ELevate is a tool provided by cPanel to perform in place upgrades of the underlying operating system on a server running cPanel, specifically designed to transition from CentOS 7 to AlmaLinux 8 or Rocky Linux 8. Elevate leverages the Leapp framework, which handles the OS migration while preserving cPanel settings, configurations, and hosted data.

The cPanel ELevate process:

• Reinstalling or upgrading system packages to their AlmaLinux/Rocky Linux 8 equivalents.

• Migrating critical services, such as Apache, PHP, MySQL, and mail servers, while maintaining configurations and compatibility.

• Validating software and module compatibility, especially for third-party tools or custom configurations.

• Ensuring that cPanel & WHM continues to function seamlessly after the upgrade.

The ELevate process is non-trivial and requires careful preparation, including full backups, service compatibility checks, and potential reconfiguration of custom integrations post-upgrade.

• To view the status of ELevate on your server, run the following command:
  

/scripts/elevate-cpanel --status

• The progress of the ELevate process is saved in a JSON file located at:
  

/var/cpanel/elevate

• Within this file/var/cpanel/elevate, two important keys reflect the state of the process:
  

stage_number

Indicates which step of the ELevate process is currently active.

• Values range from 1 to 5 during the upgrade.

• A value of 6 means the process has been successfully completed.

status

Describes the current condition of the upgrade.
Possible values include:

running

• the process is actively executing.

paused

• the process is temporarily halted.

success

• the process has finished without errors.

failed

• an error has occurred that stopped progress.

• To check the main log for the ELevate process, use the following command:

/scripts/elevate-cpanel --log

• Leapp-related messages and reports are saved in the following locations:
  

/var/log/leapp/leapp-report.txt
/var/log/leapp/leapp-report.json

These files contain details about any warnings, errors or recommendations generated by Leapp.

• If the ELevate process was stopped, paused, review and address any issues that were reported. Once resolved you can resume the process using:

/scripts/elevate-cpanel --continue

• If the process appears to be stuck or repeatedly restarting on stage 1, try unlocking it by running:

/scripts/elevate-cpanel --start

• Clear the current state (do not use this if the process has moved past stage 2):

/scripts/elevate-cpanel --clean

• Restart the process:

/scripts/elevate-cpanel --start

• If the CCS service fails to start after the upgrade, it may be due to a schema issue or incomplete installation.

• On RHEL-based systems:

rpm -q cpanel-z-push 

• On Ubuntu-based systems:

apt list --installed | grep cpanel-z-push

1. Remove existing packages:

• On RHEL-based systems:

dnf -y remove cpanel-ccs-calendarserver cpanel-z-push

• On Ubuntu-based systems:

apt -y purge cpanel-ccs-calendarserver cpanel-z-push 

2. Remove CCS home directory:

rm -rf /opt/cpanel-ccs/

3. Reinstall packages:

• On RHEL-based systems:

dnf -y install cpanel-ccs-calendarserver cpanel-z-push

• On Ubuntu-based systems:

apt -y install cpanel-ccs-calendarserver cpanel-z-push

4. Clear the queue:

/usr/local/cpanel/bin/servers_queue run

5. Check if the service is running:
/scripts/restartsrv_cpanel_ccs –status

• If Calendar Server (CCS) data wasn’t imported automatically, it can be found in:

/var/cpanel/elevate_ccs_export/

To import data for all users:

• Run the following command as root:

/usr/local/cpanel/3rdparty/bin/perl -MCpanel::Config::Users -e 'require "/var/cpanel/perl5/lib/CCSHooks.pm"; my @users = Cpanel::Config::Users::getcpusers(); foreach my $user (@users) { my $import_data = { user => $user, extract_dir => "/var/cpanel/elevate_ccs_export/$user", }; CCSHooks::pkgacct_restore( undef, $import_data ); }'

To import data for a single user (replace CPTEST with the actual username):

/usr/local/cpanel/3rdparty/bin/perl -e 'require "/var/cpanel/perl5/lib/CCSHooks.pm"; my $import_data = { user => "CPTEST", extract_dir => "/var/cpanel/elevate_ccs_export/CPTEST", }; CCSHooks::pkgacct_restore( undef, $import_data );'

• The ELevate script is designed to upgrade your current cPanel & WHM® environment to a newer version. However, there are several technical conditions that must be met before the process can begin. This overview outlines those requirements and highlights potential blockers that could prevent a successful upgrade.

To proceed with the upgrade, please ensure the following:

• You must be logged in as the root user.

• Your server must be running one of the supported operating systems:

• CentOS 7 or CloudLinux 7 (with cPanel & WHM version 110)

• Ubuntu 20 (with cPanel & WHM version 118)

• AlmaLinux 8 (only supported under specific release tiers such as RELEASE or LTS)

• The cPanel installation must be up-to-date with the latest minor version available for your Operating System.

• A valid license must be in place for both cPanel and CloudLinux, if applicable.

• The script must be located in /scripts and executed from there. It also needs to be the most recent version. Use command:

/usr/local/cpanel/scripts 

We also recommend setting up multiple methods to access your server (e.g. SSH, console, IPMI, or provider-specific tools) to avoid being locked out during the upgrade.

• You can pre-check your system for potential blockers by downloading the elevate-cpanel script and run the following command:

/scripts/elevate-cpanel --check

• Several scenarios may prevent the upgrade from proceeding. These include:

Ensure enough free space is available:

• Root (/): at least 5 GB

• Boot (/boot): 120 MB

• Temporary (/tmp):

• 5 MB for RHEL-based systems

• 750 MB for Ubuntu-based systems

• /usr/local/cpanel: 1.5 GB

• /var/lib: 5 GB

• The script requires a readable sshd_config file. If it’s missing or unreadable, the upgrade will fail.

• Processes like cPanel updates upcp and backups running at the same time can interfere. These must be stipped before starting the upgrade.

/usr/local/cpanel/scripts/upcp

/usr/local/cpanel/bin/backup

• Upgrades are not supported on containerized environments or systems with incompatible EasyApache 4 (EA4) packages.

Ensure that your PHP versions meet the following versions:

• AlmaLinux OS 8: PHP 7.2+

• CloudLinux 8: PHP 5.1+

• Ubuntu 22: PHP 8.1+

• AlmaLinux OS 9: PHP 8.0+

Unsupported versions in the use will block the upgrade. Installed but unused older PHP versions will be removed during the process.

• Only JetBackup version 5 or later is compatible. Older versions must be upgraded.

• The system must correctly execute mount –a and manage GRUB2 settings.

• A valid boot configuration and consistent kernel settings are necessary.

• On RHEL-based system, the script runs a preliminary ‘dry run’ check using leapp pre-upgrade to identify risks.

• If your system uses traditional ethX naming for NICs, it may be changed to cpethX during the process.

• MySQL upgrades must not be in progress. Unsupported versions must be upgraded. For remote MySQL setups, a local instance may be temporarily enabled during the upgrade.

• If securetmp is enabled, it will be temporarily disabled to allow for enough disk space during the Ubuntu distribution upgrade, and reenabled afterward.

• If you’re hosted with OVH, the monitoring system must be disabled during the upgrade to prevent interruptions. You can acknowledge this by creating a specific touch file.

APT Issues Ubuntu-based systems

• Unstable APT state

• Held packages

• Unsupported sources in /etc/apt/sources.list.d

• Improper repository syntax

• Enabled unsupported repositories with active packages

• Incomplete transactions

The script will attempt to resolve some issues, but unresolved conflicts must be addressed manually before continuing.

• If packages from unsupported sources are detected, they must be removed. These can interfere with the upgrade, even if newer versions exist. After a successful upgrade, you may reinstall or replace these packages as needed.

• Please review your environment against the points above. If everything is in order, you can proceed with the upgrade.

When: During Stage 4 of 5

Error:

* 2025-04-12 18:18:58 (9939) [INFO] error: rpmdb: BDB0060 PANIC: fatal region error detected; run recovery

* 2025-04-12 18:18:58 (9939) [INFO] error: db5 error(-30973) from dbenv->close: BDB0087 DB_RUNRECOVERY: Fatal error, run database recovery 

Solution:

# Remove corrupted Berkeley DB

rm -f /var/lib/rpm/__db.* 

# Initialize a fresh RPM database

rpm --initdb

# Rebuild the RPM database

rpm --rebuilddb

/scripts/elevate-cpanel --continue

When: During Stage 3 of 5

Error:

* 2025-04-14 20:31:57 (9835) [ERROR] Detected multiple physical network interfaces where one or more use kernel naming (e.g. eth0). The upgrade process cannot continue because stability of names cannot be guaranteed. Please read the article at https://access.redhat.com/solutions/4067471 for more information.

* 2025-04-14 20:31:57 (9835) [ERROR] You can read the full leapp report at: /var/log/leapp/leapp-report.txt

* 2025-04-14 20:31:57 (11256) [FATAL] The 'leapp upgrade' process failed.

Solution:

https://www.linkedin.com/pulse/resolving-multiple-nics-using-ethx-error-updating-7-8-reyes-galgani

# Grab the current active network adapter MAC address:

ip -c a

# Edit/create this file:

vim /etc/udev/rules.d/70-persistent-net.rules

# Add (sub the MAC address and adapter name at end (enp2s0 is a good alternative):

SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:1D:D8:B7:41:45", ATTR{dev_id}=="0x0", ATTR{type}=="1", KERNEL=="eth*", NAME="enp2s0"

# Rename and edit the ifcfg files, update the "DEVICE=" entry:

cd /etc/sysconfig/network-scripts/

mv ifcfg-eth0 ifcfg-enp2s0

vim ifcfg-enp2s0

# Make sure IPMI is working and that you have the server root password to login or if you reset it, that you can login… whatever floats your boat :-)

# Restart the server

# Continue the upgrade:

/scripts/elevate-cpanel --continue

cd /etc/sysconfig/network-scripts/
mv ifcfg-eth0 ifcfg-enp2s0
vim ifcfg-enp2s0 # Ensure DEVICE="enp2s0"

Reboot the server and continue:

/scripts/elevate-cpanel --continue

When: After reboot into the upgrade kernel during Stage 4 of 5.

Error: The boot process gets stuck at the section where selinux does the autorelabel.

Solution:

# Restart the server with CTRL+ALT+DEL (not a reset)

# In GRUB, add the following as you would normally add the FSCK stuff

selinux=0 enforcing=0

# This will force a skip of the selinux autorelabel actions

# Check the --log if the upgrade is continuing

When: During Stage 3 of 5

Error:

Some of the target repositories require GPG keys that are not installed in the current RPM DB or are not stored in the /etc/leapp/files/vendors.d/rpm-gpg/,/etc/leapp/repos.d/system_upgrade/common/files/rpm-gpg/8 directory.

Leapp is not able to guarantee validity of such gpg keys and manual review is required, so any spurious keys are not imported in the system during the in-place upgrade. The following additional gpg keys are required to be imported during the upgrade:

* 2025-04-16 19:16:31 (9835) [ERROR] - https://repo.cloudlinux.com/kernelcare/RPM-GPG-KEY-KernelCare

Solution:

# Import the KernelCare GPG key

curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-KernelCare https://repo.cloudlinux.com/kernelcare/RPM-GPG-KEY-KernelCare

rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-KernelCare

When: During the preparation stage, while attempting to register the AutoSSL provider

Error:

* 2025-04-29 22:38:35 [WARN] Unknown error while checking blockers: Cpanel::Exception/(XID 3938az) The system failed to load and to parse the file “/var/cpanel/autossl.json” because of an error: (XID fvtneh) The system failed to parse the JSON stream data “s=a00f6e6189854810841d3cc5cfca6262;i=4bcf71;b=ed515fce7730473ba461a1b00bbaa572;m=914c693c6b8” for the caller “(eval)” because of an error: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before "s=a00f6e618985481084...") at /usr/local/cpanel/Cpanel/JSON.pm line 128.

at /usr/local/cpanel/Cpanel/Transaction/File/BaseReader.pm line 60.

Cpanel::Transaction::File::BaseReader::_init_data_with_catch(Cpanel::Transaction::File::JSONReader=HASH(0x4b38370), "path", "/var/cpanel/autossl.json") called at /usr/local/cpanel/Cpanel/Transaction/File/BaseReader.pm line 42

Cpanel::Transaction::File::BaseReader::new("Cpanel::Transaction::File::JSONReader", "path", "/var/cpanel/autossl.json") called at /usr/local/cpanel/Cpanel/SSL/Auto/Config/Read.pm line 102

Cpanel::SSL::Auto::Config::Read::new("Cpanel::SSL::Auto::Config::Read") called at /usr/local/cpanel/Cpanel/SSL/Auto.pm line 70

Cpanel::SSL::Auto::get_all_provider_info() called at /scripts/elevate-cpanel line 709

Elevate::Components::AutoSSL::is_using_sectigo(Elevate::Components::AutoSSL=HASH(0x4f3e1e0)) called at /scripts/elevate-cpanel line 686

Elevate::Components::AutoSSL::_check_autossl_provider(Elevate::Components::AutoSSL=HASH(0x4f3e1e0)) called at /scripts/elevate-cpanel line 681

Elevate::Components::AutoSSL::check(Elevate::Components::AutoSSL=HASH(0x4f3e1e0)) called at /scripts/elevate-cpanel line 580

Elevate::Components::_check_single_blocker(Elevate::Components=HASH(0x3626530), "AutoSSL") called at /scripts/elevate-cpanel line 568

Elevate::Components::_check_all_blockers(Elevate::Components=HASH(0x3626530)) called at /scripts/elevate-cpanel line 527

eval {...} called at /scripts/elevate-cpanel line 527

Elevate::Components::_has_blockers(Elevate::Components=HASH(0x3626530), 1) called at /scripts/elevate-cpanel line 472

Elevate::Components::check(Elevate::Components=HASH(0x3626530)) called at /scripts/elevate-cpanel line 11041

cpev::run("cpev", "--check") called at /scripts/elevate-cpanel line 10981

* 2025-04-29 22:38:35 [WARN] Please fix the detected issues before performing the elevation process.

Read More: https://cpanel.github.io/elevate/blockers/

[root@helpcentre ~]# whmapi1 set_autossl_provider provider=LetsEncrypt x_terms_of_service_accepted='https://letsencrypt.org/docume...'

---

metadata:

command: set_autossl_provider

reason: "API failure: (XID 2qjz9d) The system failed to load and to parse the file “/var/cpanel/autossl.json” because of an error: (XID 5dm2qw) The system failed to parse the JSON stream data “s=a00f6e6189854810841d3cc5cfca6262;i=4bcf71;b=ed515fce7730473ba461a1b00bbaa572;m=914c693c6b8” for the caller “(eval)” because of an error: malformed JSON string, neither tag, array, object, number, string or atom, at character offset 0 (before \"s=a00f6e618985481084...\") at /usr/local/cpanel/Cpanel/JSON.pm line 128.\n"

result: 0

version: 1

Solution:

You may see:

[root@helpcentre ~]# cat /var/cpanel/autossl.json ; echo

s=a00f6e6189854810841d3cc5cfca6262;i=4bcf71;b=ed515fce7730473ba461a1b00bbaa572;m=914c693c6b8

Replace the command using the following:

[root@helpcentre ~]# cat /var/cpanel/autossl.json ; echo

{"provider_properties":{"LetsEncrypt":{"terms_of_service_accepted":"https://letsencrypt.org/docume..."}},"provider":"LetsEncrypt","_schema_version":1,"metadata":{"notify_autossl_expiry_coverage_user":"0","notify_autossl_renewal_coverage_user":"0","notify_autossl_renewal_uncovered_domains":"0","notify_autossl_renewal_coverage":"0","notify_autossl_renewal_coverage_reduced_user":"0","notify_autossl_renewal_uncovered_domains_user":"0","notify_autossl_expiry_coverage":"0","notify_autossl_renewal_coverage_reduced":"0","notify_autossl_expiry_user":"0","notify_autossl_renewal":"0","notify_autossl_renewal_user":"0","clobber_externally_signed":"1","notify_autossl_expiry":"0"}}

Run --check again

• This section provides helpful utilities, shell functions, service controls, and PHP package installation commands to assist during and after the cPanel ELevate process.

• Sometimes changing PHP versions to 82/81 yields errors, try installing all the needed packages:

PHP 81

• yum install -y ea-php81-php-ioncube10 ea-php81-php-soap ea-php81-php-litespeed ea-php81-php-zip ea-php81-php-gettext ea-php81-php-xml ea-php81-php-iconv ea-php81-libc-client ea-php81-php-sockets ea-php81-php-fileinfo ea-php81-php-imap ea-php81-runtime ea-php81-php-ftp ea-php81-pear ea-php81-php-bcmath ea-php81-php-mbstring ea-php81-php-opcache ea-php81-php-odbc ea-php81-php-tidy ea-php81-php-fpm ea-php81-php-posix ea-php81-php-calendar ea-php81-php-cli ea-php81-php-xmlrpc ea-php81-php-curl ea-php81-php-intl ea-php81-php-devel ea-php81-php-gd ea-php81-php-common ea-php81-php-mysqlnd ea-php81-php-exif ea-php81-php-pdo ea-php81-php-sodium

PHP 82

• yum install -y ea-php82-php-ioncube10 ea-php82-php-soap ea-php82-php-litespeed ea-php82-php-zip ea-php82-php-gettext ea-php82-php-xml ea-php82-php-iconv ea-php82-libc-client ea-php82-php-sockets ea-php82-php-fileinfo ea-php82-php-imap ea-php82-runtime ea-php82-php-ftp ea-php82-pear ea-php82-php-bcmath ea-php82-php-mbstring ea-php82-php-opcache ea-php82-php-odbc ea-php82-php-tidy ea-php82-php-fpm ea-php82-php-posix ea-php82-php-calendar ea-php82-php-cli ea-php82-php-xmlrpc ea-php82-php-curl ea-php82-php-intl ea-php82-php-devel ea-php82-php-gd ea-php82-php-common ea-php82-php-mysqlnd ea-php82-php-exif ea-php82-php-pdo ea-php82-php-sodium

PHP 83

• yum install -y ea-php83-php-ioncube10 ea-php83-php-soap ea-php83-php-litespeed ea-php83-php-zip ea-php83-php-gettext ea-php83-php-xml ea-php83-php-iconv ea-php83-libc-client ea-php83-php-sockets ea-php83-php-fileinfo ea-php83-php-imap ea-php83-runtime ea-php83-php-ftp ea-php83-pear ea-php83-php-bcmath ea-php83-php-mbstring ea-php83-php-opcache ea-php83-php-odbc ea-php83-php-tidy ea-php83-php-fpm ea-php83-php-posix ea-php83-php-calendar ea-php83-php-cli ea-php83-php-xmlrpc ea-php83-php-curl ea-php83-php-intl ea-php83-php-devel ea-php83-php-gd ea-php83-php-common ea-php83-php-mysqlnd ea-php83-php-exif ea-php83-php-pdo ea-php83-php-sodium

• If you require support for older PHP versions on your sites, please request Imunify360 from Afrihost.