KB
cPanel & Hosting

Change Primary IP of cPanel

5 min read932 words15 code blocks

At a glance#

  • Purpose: Change the main shared IP address of a cPanel/WHM server.
  • Applies to: cPanel & WHM on any supported Linux distribution.
  • Risk: High — affects every hosted site, DNS record and the cPanel licence.
  • Time: About 1 hour, plus DNS propagation.

Overview#

The primary IP is the shared address used for virtual hosts, outbound mail, DNS records and cPanel licence validation. Changing it touches all of those at once.

The order matters. Change the OS network configuration and cPanel's configuration together, then reactivate the licence — the licence is tied to the IP, and the server becomes unusable until it is updated.

Warning: cPanel licences are bound to the primary IP. After the change, WHM and cPanel will not function until /usr/local/cpanel/cpkeyclt has been run successfully. Confirm with your licence provider beforehand that the new IP is authorised, or the reactivation in step 8 will fail and you will be left with a non-functional server.

Before you start#

  • Root access, plus console or IPMI access — you will lose SSH when the IP changes.
  • The new IP address, netmask and gateway, confirmed with the network team.
  • Confirmation that the cPanel licence can be moved to the new IP.
  • A maintenance window. Sites will be unreachable during the change and DNS propagation.
  • A full backup or VM snapshot.

Record the current state:

bash
cat /var/cpanel/mainip
ip addr show
hostname -f

Lower the DNS TTL for affected zones to 300 seconds at least 24 hours in advance. Without this, clients cache the old IP for the full previous TTL and the outage runs far longer than the work does.

Procedure#

1. Update the shared IP in WHM#

  1. Log in to WHM as root.
  2. Go to Home → Server Configuration → Basic WebHost Manager Setup.
  3. Find The IP address (only one address) that will be used for setting up shared IP virtual hosts.
  4. Enter the new IP address.
  5. Save.

2. Update the operating system network configuration#

Apply the new address at the OS level. The exact method depends on the distribution — see Configuring IP for Linux Server.

Warning: Your SSH session will drop the moment this takes effect. Have the console open before you apply it.

3. Update the main cPanel IP record#

Reconnect via the new IP or console, then:

bash
/scripts/mainipcheck

This updates /var/cpanel/mainip to match the interface.

Confirm:

bash
cat /var/cpanel/mainip

4. Rebuild /etc/hosts#

bash
/scripts/fixetchosts

This corrects the hostname-to-IP mapping. If it is wrong, mail and several cPanel services misbehave in ways that are hard to diagnose.

5. Restart networking#

bash
systemctl restart NetworkManager   # RHEL 8+/AlmaLinux
# or
systemctl restart network          # older CentOS/RHEL 7

6. Rebuild NAT configuration if applicable#

Only if the server sits behind NAT — that is, it has a private IP on the interface and a public IP in front of it:

bash
/scripts/build_cpnat

Verify:

bash
cat /var/cpanel/cpnat

7. Update account IP assignments#

Accounts still referencing the old shared IP need repointing:

bash
/scripts/updateuserdomains
/scripts/rebuildhttpdconf
systemctl restart httpd

To move a specific account explicitly:

bash
/bin/whmapi1 setsiteip ip=NEW.IP.ADD.RESS user=username

8. Reactivate the cPanel licence#

bash
/usr/local/cpanel/cpkeyclt

Expected output ends with:

text
Updating cPanel license...Done. Update succeeded.
Warning: If this fails, WHM and cPanel stay unusable. Confirm the server can reach license.cpanel.net on port 2089, and that the new IP is registered with your provider.

9. Update DNS records#

Update the A records for the server hostname, cpanel., webmail., mail. and any zone still pointing at the old IP.

bash
/scripts/rebuilddnsconfig

Check for zones still referencing the old address:

bash
grep -rl "OLD.IP.ADD.RESS" /var/named/

10. Update SPF and reverse DNS#

Mail will start failing SPF checks if this is missed, and delivery quietly degrades over the following days.

  • Update SPF records for every hosted domain to reference the new IP.
  • Ask the network or hosting provider to update the PTR record so the new IP resolves back to the mail hostname.

Confirm the PTR once set:

bash
dig -x NEW.IP.ADD.RESS +short

Verification#

bash
# cPanel's view of the main IP
cat /var/cpanel/mainip

# Interface configuration
ip addr show

# Licence valid
/usr/local/cpanel/cpkeyclt

# Services running
systemctl status httpd exim named

Then test from outside the server:

  • Load a hosted website over HTTP and HTTPS.
  • Log in to WHM and cPanel.
  • Send a test email out and confirm it is not rejected or marked as spam.
  • Receive a test email in.
  • Confirm dig yourdomain.com +short returns the new IP.

Restore the DNS TTL to its normal value once everything is confirmed stable.

Troubleshooting#

SymptomCause and fix
WHM inaccessible after the changeLicence not updated. Run /usr/local/cpanel/cpkeyclt from SSH or console.
cpkeyclt failsFirewall blocking outbound TCP 2089, or the IP is not authorised. Test with curl -v https://license.cpanel.net:2089.
Sites still serve on the old IPApache configuration not rebuilt. Run /scripts/rebuildhttpdconf and restart httpd.
Outbound mail rejected as spamMissing PTR record or stale SPF entries. Both must be updated.
Some accounts unreachableThose accounts still hold a dedicated old IP. Repoint with whmapi1 setsiteip.
Hostname resolves to the old IP/etc/hosts not rebuilt. Run /scripts/fixetchosts.
Everything correct but users still see the old siteDNS caching. Confirm with dig @8.8.8.8 domain.com and wait out the TTL.