This guide converts a running cPanel server from its current base OS (CentOS 7, AlmaLinux 8/9, or Rocky 8/9) to CloudLinux OS without reinstalling. End-to-end you should budget 20 minutes plus one reboot.
It assumes a working WHM, root SSH, and a valid CloudLinux activation key. If you don't have a key yet, grab one from the CloudLinux product page — the single-server licenses activate immediately and you can apply the key during the steps below.
Before you start
CloudLinux ships its own kernel and a userspace agent (lvectl, cagefsctl,
clnreg_ks). The deploy script swaps repositories, installs the new kernel alongside the
existing one, and registers the server against your account. The original OS kernel stays
on disk as a fallback grub entry.
Requirements:
- x86_64 only — ARM is not supported as of CloudLinux OS 9.
- 2 GB RAM minimum, 4 GB recommended once CageFS and the PHP Selector alt-php stack are populated.
- 1 GB free under
/usr/share/cagefs-skeleton(CageFS skeleton tree). - An active cPanel license — the conversion does not touch cPanel, but you'll be rebooting, so verify your cPanel license is healthy before starting.
Activate the license
The cldeploy script accepts the activation key directly, so you don't need to run
clnreg_ks separately on a fresh install. But if you're re-registering an existing host
or moving a license between IPs, run it first:
clnreg_ks --activation-key=YOUR-KEY-HERE
A successful registration writes /etc/sysconfig/rhn/systemid and prints the registered
hostname. If the command exits with License key is invalid, the key is either typoed,
already bound to a different IP, or expired — check the licensee email or
contact sales before proceeding.
Run cldeploy
cldeploy is the official conversion script. It detects the current OS, swaps in the
CloudLinux repositories, installs the kernel and userspace, and configures grub. From a
root shell:
wget https://repo.cloudlinux.com/cloudlinux/sources/cln/cldeploy
sh cldeploy -k YOUR-KEY-HERE
Expect 5-15 minutes depending on disk and network speed. The script is idempotent — if it fails partway, you can re-run it after fixing the underlying issue (usually a held package or a third-party repo conflict).
When it finishes, you'll see:
Please reboot your system to apply changes.
Do not skip the reboot. The userspace tools will load but LVE limits, CageFS, and the alt-php selector all depend on the CloudLinux kernel.
reboot
Verify the new kernel
After the host comes back up, confirm you booted into the CloudLinux kernel:
uname -r
You should see something with .lve in the version string, for example
5.14.0-503.40.1.lve.el9.x86_64. If uname -r still shows the stock AlmaLinux or Rocky
kernel, the grub default didn't update — check /boot/grub2/grub.cfg, set the CloudLinux
entry as default with grub2-set-default 0, and reboot once more.
Also verify the registration:
cldetect --check-license
A registered server prints License is OK. An unregistered one prints Not registered,
in which case re-run clnreg_ks with your key.
Enable CageFS
CageFS is the per-user virtualised filesystem that hides other tenants' processes and
files. It's optional on paper but mandatory in practice — without it, the LVE limits
still apply but users can ps auxf their way to every other account on the box.
yum install cagefs -y
cagefsctl --init
cagefsctl --enable-all
--init builds the skeleton (about 5 minutes, mostly hardlinking system binaries).
--enable-all flips every existing cPanel user into a cage. New accounts created via WHM
are caged automatically once CageFS is initialised.
Wire up the cPanel integration
WHM detects CloudLinux automatically after reboot and adds an LVE Manager entry under Plugins. If it doesn't appear, install the integration package manually:
yum install lvemanager -y
/usr/local/cpanel/scripts/check_cpanel_rpms --fix
The LVE Manager plugin gives you per-user CPU, memory, I/O, and process limits, plus the PHP Selector for letting customers pick their own PHP version and extensions. To enable the PHP Selector:
yum groupinstall alt-php -y
cagefsctl --setup-cl-selector
This pulls every supported alt-php version (5.6 through 8.4 as of writing) and registers
them with CageFS. It's a ~2 GB download — if you only need a couple of versions, install
them individually with yum install alt-php82 alt-php83 instead.
Tune the defaults
The out-of-the-box LVE limits (CPU 100%, memory 1 GB, I/O 1024 KB/s) are too generous for most shared hosting. Drop them to something realistic before you start onboarding customers — the CloudLinux LVE tuning guide covers the specific numbers we recommend for low-density and high-density shared plans.
Next steps
- CloudLinux LVE tuning for shared hosting — set per-user CPU, memory, and EP limits that match your plan tiers.
- How CloudLinux licenses are prorated and billed — understand the daily proration if you add the license mid-month.
- cPanel vs Plesk in 2026 — if you're still deciding on the control panel side of the stack.