H-Sphere Sysadmin Guide

IP Migration (Changing IPs) For The H-Sphere Cluster

This document explains how to change IPs on Unix/Linux servers for H-Sphere 2.4.x. If you have an older version, please get updated first.

Changing IPs on systems without NAT
Changing External IPs on systems using NAT
Changing Internal IPs on systems using NAT
Running H-Sphere on two sets of IPs

Changing IPs on Systems Without NAT

H-Sphere IP migration is performed by means of Java IP Migrator called by the IPMIGR wrapper available for download from the psoft.net website. IP Migrator will:

change H-Sphere physical, logical, and system IPs
update IPs in H-Sphere database
change IPs in the system files except network startup configuration
update IP-dependent resources such as apache, FTP and DNS

IP Migrator doesn't migrate NIC system files to avoid potential problems with server inaccessibility. These files must be migrated manually by the local administrator.

IP Migrator doesn't modify reverse DNS configuration because H-Sphere doesn't manage reverse DNS. For information on reverse DNS configuration, you may refer to www.tldp.org/HOWTO/DNS-HOWTO-5.html#ss5.3

IP Migration Pre-Requisites

IMPORTANT:
It is higly recommended that you upgrade your H-Sphere to the latest stable version before IP migration. New IP migrator may not work smoothly with some older H-Sphere Java classes.

Before you begin IP migration, do the following changes, and don't forget to undo them after the migration:

Add the following line to the very beginning of the /hsphere/shared/scripts/apache-reconfig script. This will prevent Apache from restarting gracefully after posting each web site configuration:
exit 0
(Skip this step for IP Migrator 0.3 and up, and for H-Sphere 2.4.3 Patch 5. If you do the migration under FreeBSD, and IP to be bound is the same as main IP, you need to perform this step notwithstanding the IP Migrator version. Otherwise you system is at risk of get crashed.)
Add the following line to the very beginning of the /hsphere/shared/scripts/ip-shared script. This will protect the main H-Sphere IP.
exit 0

After that, replace the IP on the main network interface to the new IP for all boxes, and set up the old IP as an alias for the new one;

Example:

eth0 Link encap:Ethernet HWaddr 00:D2:B5:A1:07:12 inet addr:[New_IP] Bcast:[New_Broadcast] Mask[New_NetMask]: UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:269050319 errors:0 dropped:0 overruns:0 frame:11 TX packets:336024701 errors:0 dropped:0 overruns:19 carrier:0 collisions:0 txqueuelen:100 Interrupt:21 Base address:0x4000 eth0:0 Link encap:Ethernet HWaddr 00:D2:B5:A1:07:12 inet addr:[Old_IP] Bcast:[Old_Broadcast] Mask:[Old_NetMask] UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 Interrupt:21 Base address:0x4000

Important: If IP migration is performed whsphere-apache.html#script_restarting_apacheithin one datacenter, make sure that your servers can be accessed from the Internet at both old and new IPs. If you change to IPs outside your datacenter, it would take a downtime before you make your servers available on new IPs.

IP Migration Map File

Before you start IP migration, you may manually create an IP migration map file in the cpanel user home directory ~cpanel/. The file contains the list of old IPs to be migrated to new IPs. It can be either an XML file, or a plain text file of the following format:

IP_OLD1 IP_NEW1 [MASK_NEW1]
IP_OLD2 IP_NEW2 [MASK_NEW2]
...
IP_OLDn IP_NEWn [MASK_NEWn]

Specify the mask in the third column only if it differs from the default mask (255.255.255.0) for this particular IP. Otherwise, omit it.

This manually created IP migration map file will be used by the H-Sphere IP migrator script. Starting with version 0.3, IP migrator is able to convert plain text map files into XML and provides interface to automatically create a ready-to-use map XML file according to the admin's choice.

Important: IP migration map file must have the cpanel:cpanel ownership! Either create it under the cpanel user, or run under root:

chown cpanel:cpanel ipmap.xml

IP Migration Step By Step

The steps below are performed on the server with the Control Panel installed.

Log into the CP server as root:
# su -
Download IP Migrator:
# wget http://www.psoft.net/shiv/IPMIGR-0.7.tgz

The latest IP Migrator version is 0.7. If you have an older version, update it.
See IP Migrator Change Log
Untar the archive:
# tar -zxf IPMIGR-0.7.tgz
Enter the IP Migrator directory:
# cd IPMIGR
Install the IP Migrator:
# make install
This will install the following files:
- ~cpanel/ipmigrator - IP migrator itself
- ~cpanel/IPMigratorFast.jar - makes H-Sphere related changes: in the system database, configs, etc.
- ~cpanel/shiva/ipm/ipmigr - makes changes in service config files on H-Sphere servers
Stop H-Sphere
Back up H-Sphere system database
Log in as the cpanel user
Run the IP Migrator script. The IP Migrator script is located in the cpanel home directory.
Start H-Sphere
Remove the following line from /hsphere/shared/scripts/apache-reconfig and from /hsphere/shared/scripts/ip-shared:
exit 0
If the IPs have been migrated successfully and all IP-dependent services seem to work fine, finish the migration by removing the old IPs. To remove the old IPs, run:
./ipmigrator --clear-old-ips --xml=<ipm_xml>

Where <ipm_xml> is the IP migration map XML file that you used for the migration.
Example:
```
./ipmigrator --clear-old-ips --xml=ipm1.xml

H-Sphere version is: 2.4.3.503. The new IPMigratorFast will be used.

Removing old IPs
Done
```

Changing External IPs on Systems With NAT

This section explains how to change your external IPs on a system using NAT (see details here). You may need to follow this instruction when you move to a different location and would like to preserve your internal IP settings.

Change IPs in ~cpanel/shiva/psoft_config/ips-map.xml and ~cpanel/shiva/psoft_config/hsphere.properties

Change IPs in SiteStudio configs /hsphere/shared/SiteStudio/psoft_config/*. You can use a simple script:

#!/bin/sh
if [ $# = 0 ] ; then
              echo $"Usage: changeip.sh OldIP NewIP"
              exit 1
fi

for i in /hsphere/shared/SiteStudio/psoft_config/*.properties
do
echo "Processing $i";
echo ",s/$1/$2/g
wq" | ed $i
done

Change external IPs in httpd.conf on the web box.
Restart H-Sphere
Restart Apache
Log in as the cpanel user and recreate zones with the dns creator:

java psoft.hsphere.tools.DNSCreator -m db -dz

Changing Internal IPs on Systems With NAT

To change from one set of internal IPs to another:

Change the IPs in ~cpanel/shiva/psoft_config/ips-map.xml.
Change your internal IPs by following the instruction on Changing IPs on Systems Without NAT.

How do I get H-Sphere working on two sets of IPs?

If you would like to ensure smooth change of IPs and have everything duplicated on the old and new sets of IPs before making the switch, you need to do the following:

On the Web box:

Before the IP migration you need to copy the /hsphere/local/config/httpd/sites directory to /hsphere/local/config/httpd/sites.old to preserve your old client's apache configs.
Go to /hsphere/local/config/httpd/sites.old and edit index.conf changing sites to sites.old (cd /hsphere/local/config/httpd/sites.old; perl -pi -e 's/sites/sites.old/' index.conf)
Copy namevh.conf to namevh.old.conf
Proceed with the IP migration.
Add the following lines at the bottom of the /hsphere/local/config/httpd/httpd.conf file:
Include /hsphere/local/config/httpd/sites.old/[0-9]*.conf
Include /hsphere/local/config/httpd/namevh.old.conf

On the DNS servers:

Add your old DNS IPs to the /etc/named.conf config to force your DNS servers to listen to the old IPs.
Bind your old IPs to the NIC on your servers.