Upgrade AlmaLinux 8 → 9 on a Production cPanel Server

Upgrading a production server is a delicate operation that requires careful planning, thorough testing, and precise execution. If your cPanel server runs on CloudLinux 8 (which is based on AlmaLinux 8), you may want to move to CloudLinux 9 (based on AlmaLinux 9) to take advantage of newer packages, longer support, and enhanced security. This guide walks you through the entire upgrade process, from pre-upgrade preparation to post-upgrade validation, while keeping your cPanel services running smoothly.

1. Understand the Upgrade Path and Prerequisites

CloudLinux 9 is built on AlmaLinux 9, so the OS upgrade follows the same steps as a standard AlmaLinux 8-to-9 migration. However, cPanel adds extra considerations:

• cPanel version compatibility: You must run cPanel 98.0.28 or newer, which supports CloudLinux 9. Check the cPanel documentation for the exact minimum version.
• Backup strategy: A full system backup—including cPanel accounts, MySQL databases, and configuration files—is mandatory.
• Third-party software: Verify that any custom scripts, PHP extensions, or additional services (e.g., Redis, RabbitMQ) have AlmaLinux 9 packages or are compatible with the newer libraries.
• Disk space: The upgrade needs at least 2 GB of free space on the root filesystem for temporary files.

2. Prepare Your Server

2.1. Take a Complete Backup

# Create a compressed backup of /home, /etc, and MySQL databases
tar -czpf /root/backup-pre-upgrade-$(date +%F).tar.gz \
    /home /etc /var/lib/mysql

Store the backup on a separate storage device or a remote location (for example, an S3 bucket) before proceeding.

2.2. Verify cPanel Compatibility

# Check the currently installed cPanel version
/usr/local/cpanel/cpanel -V

If the version is older than the required minimum, update cPanel first:

# Run the cPanel update script
/usr/local/cpanel/scripts/upcp

After the update, re-run the version check to confirm the new version.

2.3. Disable Automatic Updates and Services That May Interfere

# Stop the cPanel service temporarily
systemctl stop cpanel

# Disable yum/dnf automatic timers
systemctl disable --now dnf-automatic.timer

3. Upgrade the Underlying AlmaLinux OS

CloudLinux provides an official upgrade tool that automates the migration from CloudLinux 8 to CloudLinux 9. The tool handles repository changes, package replacements, and kernel upgrades.

3.1. Install the CloudLinux Upgrade Tool

# Download and install the upgrade script
curl -O https://repo.cloudlinux.com/cloudlinux/upgrade/upgrade-to-cl9.sh
chmod +x upgrade-to-cl9.sh

3.2. Run the Upgrade Script

# Execute the script (it will prompt for confirmation)
./upgrade-to-cl9.sh

The script performs the following actions:

• Switches the base repository from cloudlinux8 to cloudlinux9.
• Runs dnf distro-sync to replace AlmaLinux 8 packages with AlmaLinux 9 equivalents.
• Installs the new CloudLinux kernel and updates the bootloader.
• Removes obsolete packages that have no AlmaLinux 9 counterpart.

During the process, you will see a summary of packages to be installed, upgraded, or removed. Review the list carefully. If you spot a critical third-party package that is being removed, pause the upgrade and investigate an alternative version before continuing.

3.3. Reboot Into the New Kernel

# Reboot the server
reboot

After the reboot, confirm you are running the CloudLinux 9 kernel:

# Check kernel version
uname -r

Typical output will show a version like 5.14.0-cl9.x86_64.

4. Post-Upgrade Tasks for cPanel

4.1. Verify cPanel Services

# Start cPanel services
systemctl start cpanel

# Check status of core services
systemctl status cpanel
systemctl status httpd
systemctl status mysql

All services should be active (running). If any fail, examine the journal logs:

# View recent logs for a failing service
journalctl -u httpd -p err -n 20

4.2. Run cPanel’s Internal Upgrade Checks

# Run the cPanel post-upgrade script
/usr/local/cpanel/scripts/check_cpanel_rpms --fix
/usr/local/cpanel/scripts/upcp --force

The first command repairs any mismatched RPMs, while the second forces a cPanel software refresh to align with the new OS libraries.

4.3. Update PHP Versions and Extensions

CloudLinux 9 ships with newer PHP versions. To keep existing sites functional, reinstall the PHP packages you need:

# List installed PHP versions
php -v

# Example: install PHP 8.1 and common extensions
yum install -y alt-php81-php \
    alt-php81-php-mysqlnd \
    alt-php81-php-gd \
    alt-php81-php-mbstring

Adjust the version numbers (e.g., alt-php82) based on your site requirements.

4.4. Re-enable Automatic Updates (Optional)

# Reactivate dnf-automatic timer if desired
systemctl enable --now dnf-automatic.timer

5. Validate the Upgrade

5.1. Test Websites and Applications

• Open a browser and navigate to each hosted domain. Verify front-end functionality and login to any admin panels.
• Run curl -I https://example.com from the server to check SSL/TLS handshake and response headers.

5.2. Check Mail Flow

# Send a test email from the command line
echo "Test mail from upgraded server" | mail -s "Upgrade Test" your@email.com

Confirm receipt and inspect the mail logs (/var/log/exim_mainlog) for any errors.

5.3. Review System Logs for Errors

# Look for recent errors in the journal
journalctl -p err -b -n 50

Address any lingering issues before declaring the upgrade complete.

6. Rollback Plan (If Needed)

Even with careful preparation, unexpected problems can arise. Having a rollback plan minimizes downtime:

1. Restore the pre-upgrade backup: Boot into a rescue environment (for example, CloudLinux rescue mode) and extract the backup archive to the original locations.
2. Reinstall the previous kernel: Use the rescue environment to install the CloudLinux 8 kernel package (kernel-cloudlinux) and update the GRUB configuration.
3. Re-enable cPanel services: Start cPanel and verify that all services return to their prior state.

Document any deviations from the plan; they will help refine future upgrades.

Conclusion

Upgrading a production cPanel server from CloudLinux 8 (AlmaLinux 8) to CloudLinux 9 (AlmaLinux 9) is a multi-step process that demands thorough backups, compatibility checks, and post-upgrade validation. By following the structured workflow outlined above—preparing backups, using the official CloudLinux upgrade tool, re-configuring cPanel, and testing all services—you can transition to the newer platform with confidence and minimal disruption to your customers.