H-Sphere Sysadmin Guide

Migrating Winbox

(H-Sphere 2.4.x)

This is a draft for your consideration. Don't use it in production environment.

This document explains how to migrate H-Sphere winbox to a different server. You can also consider winbox migration instructions for H-Sphere 2.3.x-2.4.x.

Commercial products. This procedure doesn't move products such as MS SQL, Miva, Cold Fusion etc. In order to use them on the new server, you need to install them manually before the migration.
Web statistics. You may lose AWStats and Webalizer statistics for the time of migration.

1. Prepare Source And Target Servers
1.1. Update H-Sphere on the source box.
1.2. Install H-Sphere winbox software on the target box.
1.3. Clean up HShome directory from orphaned files and folders.
2. Recreate H-Sphere Resources
2.1. Trim the skeleton on the target box.
2.2. Change the IP of the target physical server.
2.3. Run physical creator on the CP box.
2.4. Move user content using the rsync tool.
2.5. Enable signup for the logical server.
3. Manual Post-recreate steps
3.1. Install Shared SSL certificates.
3.2. Export user SSL certificates from the source box to the target box.
3.3. Repeat content move.
3.4. Stop rsync on the target box.
3.5. If you run dedicated IPs, set them up on the target box and delete them from the source box.
3.6. Update H-Sphere on the target box.

Step 1.1. Update H-Sphere on the source box

Update H-Sphere to the leatest build of 2.4.x. Please refer to the table of versions for instructions.

Step 1.2. Install H-Sphere winbox software on the target box

The target box must have a fresh install of Windows 2000 or 2003 server as required in Preparing Winbox and Winbox Installation manuals. Don't set up customer accounts or domains.

Step 1.3. Clean up HShome directory from orphaned files and folders

Before migration we highly recommend cleaning your HShome from orphaned files and folders in order to migrate only relevant content.

Step 2.1. Trim the skeleton on the target box

Disable Signup on the source server for the time of migration to avoid data loss.
Remove content of the HSphere\skeleton directory.
Download file skeleton_empty.exe file into this directory.
Execute skeleton_empty.exe from command line with the following parameters:
skeleton_empty.exe -extract -Directories

Step 2.2. Change IP of the target physical server.

In the admin CP, select E.Manager -> P.Servers and click the name of the server. In the IP 1 field, enter the new IP of the server. In the Mask 1 field, enter the mask for this IP.

Step 2.3. Run PhysicalCreator on the CP box

In the admin cp, select P.Servers of the E.Manager menu and click server info for the Winbox in question. Check if server info shows on the page that appears. If not, the cp server can't communicate with the Winbox. Make sure to fix this issue before proceeding.
Downolad tail utility for Windows and put it in the directory WINDOWS (win2003) or WINNT (win2000).
Log into the system database and run the following DB query to find out the number of domains to create, replacing ??? with the ID of the logical server you are migrating:
select count(*) from iis_vhost i, parent_child p, accounts a, user_account ua where i.id=p.child_id and p.account_id = a.id and a.deleted is null and ua.account_id = a.id and (a.demo <> 1 OR demo IS NULL) and host_id = ???;
Run PhysicalCreator as the cpanel user:
java -Xms64M -Xmx512M psoft.hsphere.tools.PhysicalCreator -rg winweb -co -lid LOGICAL_SERVER_ID > creator.log 2>&1 &

More on PhysicalCreator
In the command line on the Winbox, run tail -f action.log to monitor the creation of Winbox resources.
In another command line window, periodically check the number of created domains by running:

find "CreateWebHost(" <HS_DIRECTORY>\logs\action.log /c
for example:
find "CreateWebHost(" d:\hsphere\logs\action.log /c

Step 2.4. Move content using the rsync tool

Check your service processes to make sure that HSquotas is running.

In the directory <DISK>:\hsphere\rsync on the target server, create file rsync.conf with the following content:

log file = ./rsync.log
use chroot = false
strict modes = false
hosts allow = *

[UNIQUE_SESSION_ID_STRING]
        path = <DISK>:\hshome
    read only = false
        comment = content area
    list = false

Run rsync-start.asp with the browser and follow the authorization wizard for the user that was created during H-Sphere Windows software installation (usually HSadmin). If successful, you'll see a 0 (zero) on the last screen. To run rsync-start.asp, type the following line in the browser address field:
http://TARGET_WINBOX_IP/cfg/rsync-start.asp

In the <DISK>\hsphere\rsync directory on the source server, create file rsynccontent.bat with the following content:

rem %1 = path to content to move
rem %2 = cygwin path to content to move
rem %3 = traget IP
rem %4 = target module name
rem FOR /F "usebackq delims=" %%i IN (`dir /B/A:D %1`) DO rsync.exe -avpgoz "/cygdrive/%2/%%i" %3::%4
rem The following line for moving content without compression
FOR /F "usebackq delims=" %%i IN (`dir /B/A:D %1`) DO rsync.exe -av "/cygdrive/%2/%%i" %3::%4

In the command prompt, launch content move from the source server to the target server:
rsynccontent.bat <DISK_WITH_USER_HOMES_ON_SOURCE_SERVER>:\hshome <DISK_LETTER>/hshome TARGET_WINBOX_IP UNIQUE_SESSION_ID_STRING > rs.log
For example:

rsynccontent.bat e:\hshome e/hshome 192.0.34.166 asdfasdf-b041-4d62-8a9f-qwerqwerqwer > rs.log

Step 2.5. Enable signup for the logical server

To do it, refer to instructions on logical servers.

Step 3.1. Install Shared SSL Certificates

In the admin control panel, install completely new Certificate key and file pair You can get them in /hsphere/shared/apache/conf/ssl.shared/[domain.name]/ on any Unix/Linux web server. This will repost the wildcard certificate on all servers, including the Winbox you are migrating.
Download Recreation scripts in a zip archive and unpack them to a separate directory on the Winbox, for example recreation_scripts.
Log into the system database and run the following DB query to select the domain names with shared SSL enabledreplacing ??? with the ID of the logical server you are migrating:
select s.name,hostnum,d.name from shared_ssl s, parent_child p1, parent_child p2, domains d, iis_vhost h where s.id = p1.child_id and p1.parent_id = p2.child_id and p2.parent_id = d.id and p2.child_id = h.id and h.host_id= ???;
Copy results of the query into a text file in the recreation_scripts directory and name it, for instance, S_SSL.txt. It will have the following format:

sname1 | hostnum1 | domain_name1
sname2 | hostnum2 | domain_name2
...
snameN | hostnumN | domain_nameN
where:
snameX - is the third level domain secured with the wildcard certificate, e.g. user22.yourdomain.com
hostnumX - is the domain ID in IIS
domain_nameX - is the corresponding second level domain, e.g. user22.com.
Enter the recreation_scripts directory and run the following command:
sslprepare.bat %1 %2 %3 %4 %5 > SetSSL.txt
where:
rem %1 - is the file name you have created (e.g. S_SSL.txt)
rem %2 - Winbox IP
rem %3 - Service domain used for shared SSL
rem %4 - H-Sphere login used at Winbox installation
rem %5 - H-Sphere password used at Winbox installation.
Open SetSSL.txt and remove the first part leaving only the list of links.
Run the following command:

WGET.EXE -i SetSSL.txt
This will install all Shared SSL resources on the Winbox.

Step 3.2. Export user SSL certificates from the source box to the target box

User SSL certificates must be moved one by one.

On the source box, open the MMC console.
If you are in Logical Certificate Stores view mode, in the console tree, click Certificates.
Right click a certificate and select All Tasks->Export.
Follow the wizard choosing the following settings:
* Yes, export the private key
* Include all certificates in the certtification path if possible
On the target box, go to the same certificates console
Right click the area where the certificates must show and choose All Tasks->Import.
Follow the wizard choosing the following settings:
* Mark the private key as exportable
* Automatically select the certificate store based on the type of certificate

Repeat these steps for all user certificates.

Step 3.3. Repeat Content Move

Check your service processes to make sure that HSquotas is running.
Repeat exactly the same steps you did for content move above to synchronize the content that was changed during the migration steps.

Step 3.4. Stop rsync on the target box

Run rsync-stop.asp with the browser and follow the authorization wizard. If successful, you'll see a 0 (zero) on the last screen. To run rsync-stop.asp, type the following line in the browser address field:

http://TARGET_WINBOX_IP/cfg/rsync-stop.asp

Step 3.5. If you run dedicated IPs, set them up on the target box and delete them from source

In the browser, run ip-delete.asp to delete dedicated IPs on the source box and follow the authorization wizard for the user that was created during H-Sphere Windows software installation (usually HSadmin). If successful, you'll see a 0 (zero) on the last screen. To run ip-delete.asp, type the following line in the browser address field:
http://SOURCE_WINBOX_IP/cfg/ip-delete.asp?IP=IP_Adress
In the browser, run ip-create and follow the wizard to create dedicated IPs on the target box:
http://TARGET_WINBOX_IP/cfg/ip-create.asp?IP=IP_Adress

Step 3.6. Update H-Sphere on the target box

Update H-Sphere to the latest build 2.4.x. to restore Skeleton files.