Changing the hostname on a running cPanel server looks like a one-liner — hostnamectl set-hostname and done. It is not. The hostname is referenced by the services SSL certificate, the Exim HELO banner, the MySQL grants table on replication setups, the cPanel license check, AutoSSL's CAA evaluation, and a handful of cached files under /var/cpanel/. Miss one and you get a service that limps for weeks until a customer complains.
This is the order that produces no downtime on a production shared server. It works whether you're moving from a temporary install hostname (server1.localdomain) to a real one, or rotating away from a vendor-default like vps-12345.provider.com.
Before you start — three things to verify
A WHM hostname must be a fully qualified domain name that is not used for hosting customer sites. The usual convention is server1.example.com where example.com is your company domain and customers live on different parent domains. If you pick a hostname that's also a customer DNS zone, AutoSSL will compete with the customer's certificate and the cPanel UI will refuse to set it.
Verify in this order:
# 1. The new hostname resolves to this server's main IP
dig +short server1.example.com A
ip -4 addr show | grep inet
# 2. Reverse DNS for the main IP matches the new hostname
dig +short -x 203.0.113.42
# 3. The hostname is not already a cPanel account or DNS zone
whmapi1 listaccts search=example.com searchtype=domain
whmapi1 listzones | grep example.com
Forward DNS (A record) must exist before you change the hostname or AutoSSL will fail at the new hostname's first validation run. Reverse DNS (PTR) is usually set in your VPS provider's control panel, not on the server itself — set it now and the mail steps later become a no-op.
Step 1 — Change the hostname
From the shell:
/scripts/set_hostname server1.example.com
set_hostname does what hostnamectl does, plus it updates /etc/hosts, restarts the services that cache the hostname, and triggers the cPanel daemon to re-read it. Do not use hostnamectl set-hostname on its own — the value sticks in the kernel but cPanel keeps reading the old one from /var/cpanel/cpanel.config until the next restart.
Confirm it took:
hostname -f
whmapi1 gethostname
Both should return the new FQDN. If gethostname still shows the old value, run /usr/local/cpanel/etc/init/stopcpsrvd && /usr/local/cpanel/etc/init/startcpsrvd to force a cache flush.
Step 2 — Re-run the license check
The cPanel license is tied to your main IP, not the hostname, so the license itself doesn't invalidate when you rename the host. But the license file at /var/cpanel/license_token.txt caches a server identity blob that includes the hostname, and a stale token sometimes produces the misleading "License Invalid" banner in WHM after a rename.
Refresh it:
/usr/local/cpanel/cpkeyclt
You should see Update succeeded and a fresh expiry date. If you instead see License is not valid for the IP, the main IP has changed (which can happen on cloud rebuilds) — that's a different problem covered in the cPanel license invalid checklist.
If you're on a non-standard licence type — DNSONLY, VPS Optimized, or a developer key — the same cpkeyclt command works. See the cPanel license tier breakdown if you're not sure which one you're running.
Step 3 — Reissue the services SSL certificate
cPanel installs a single certificate covering the hostname for WHM (:2087), cPanel (:2083), Webmail (:2096), and the mail protocols (Exim, Dovecot). After a hostname change the existing cert no longer matches and browsers throw ERR_CERT_COMMON_NAME_INVALID on the WHM URL.
Force AutoSSL to re-issue for the new hostname:
/usr/local/cpanel/bin/autossl_check --all --verbose 2>&1 | grep -i hostname
This runs a full AutoSSL pass and prints any hostname-related events. The relevant line is Installing service SSL certificate for "server1.example.com". If you see DCV failed, jump to the AutoSSL failure decision tree — the cause is almost always missing A record or a redirect.
For a manual reissue without waiting for AutoSSL's queue:
whmapi1 start_autossl_check_for_one_user user=root
The root user owns the services certificate.
Step 4 — Fix the mail HELO and rDNS
Exim uses the hostname as its outbound HELO banner. Receiving mail servers compare HELO against the sending IP's reverse DNS — a mismatch lands you in spam folders or earns an outright reject from Gmail and Outlook.
Three things must agree:
| Setting | Where | Value |
|---|---|---|
| Forward DNS | Your DNS provider | server1.example.com → 203.0.113.42 |
| Reverse DNS | VPS provider's control panel | 203.0.113.42 → server1.example.com |
| Exim HELO | /etc/mailhelo | server1.example.com |
The cPanel hostname change updates /etc/mailhelo automatically. Verify:
cat /etc/mailhelo
exim -bV | grep -i hostname
# Send a probe and check the headers
echo "test" | mail -s "helo check" check-auth@verifier.port25.com
The reply from port25 arrives in about 30 seconds and includes the HELO it observed and whether it matches rDNS. If they disagree, the cause is the VPS provider's PTR record — fix it there, not on the server.
For deeper deliverability work after the hostname change, follow the SPF, DKIM, and DMARC setup guide — the SPF and DMARC records that reference the hostname need to be regenerated.
Step 5 — Update downstream systems
These do not break automatically when the hostname changes. Touch them in this order:
- Your billing system. If Blesta or WHMCS provisions accounts using the server hostname as the API target, update the server record. In Blesta, Settings → Company → Modules → Universal Module → Edit server — change the host field, save, and click the Test Connection button.
- DNS cluster peers. If this server is part of a DNSONLY cluster, the peer servers reference it by hostname in their cluster config. SSH into each peer and update
/var/cpanel/cluster/root/config/entries, then restartcpdnsd. - Monitoring and backups. Update the target hostname in your monitoring agent's config and in any JetBackup destinations that point to this server by name rather than IP.
- Your own SSH known_hosts. The fingerprint doesn't change, but if you connect via the hostname your local
~/.ssh/known_hostshas an entry for the old one —ssh-keygen -R old-hostname.example.comclears it.
Step 6 — Verify
Run the full check:
/usr/local/cpanel/scripts/check_cpanel_rpms --long --no-digest
whmapi1 servicestatus
hostname -f
openssl s_client -connect localhost:2087 -servername $(hostname -f) </dev/null 2>&1 | grep -i subject
The openssl line should return subject=CN = server1.example.com matching the new hostname. The service status output should show all services green, especially Exim and Dovecot — those are the ones most likely to be stuck on the old hostname after a partial rename.
Tail the cPanel error log for a few minutes:
tail -f /usr/local/cpanel/logs/error_log
A clean rename produces no hostname mismatch or certificate verify failed entries. If you see either, it's almost always step 3 (cert reissue) that didn't complete — re-run autossl_check --all and the entry disappears.
Next steps
- If the hostname change was part of moving to a new IP, follow up with the cPanel license invalid checklist to update the licence to the new address.
- For Softaculous, the licence is tied to the hostname's resolved IP — see moving a Softaculous licence to a new IP before the next install attempt fails.
- For a brand-new build, follow the cPanel VPS install guide, which sets the hostname correctly at install time and avoids this entire procedure.