Last modified: 27 Dec 2007

This document explains how to migrate users into H-Sphere from H-Sphere and other control panels using XML-structured data. It can also serve as a guide to setting up a large number of H-Sphere users at a time. You are expected to have an installed and configured H-Sphere control panel on the target server.

• Migratable Resources
• Migration Procedure
• Troubleshooting

Note: Migration of users and resellers by means of XML files underwent certain changes in H-Sphere 2.5 Beta 1 and up. In particular, resellers and their end users are now migrated in separate XML files. For H-Sphere versions earlier than 2.5, please refer to this document.

Migratable Resources

Users can be migrated with the following resources:

• User contact and billing info
• Domains (with or without DNS)
• DNS: custom A, MX, CNAME records; domain vhost aliases; domain aliases with their DNS and mail configuration
• Web: settings, FrontPage, CGI, CGIDir, MIME, PHP, SSI, ErrorDoc, ErrorLog, TransferLog, Webalizer, ModLogAn, RefferrerLog, AgentLog, Vhost alias, Directory indexes, Redirect, Urchin3, Urchin4, ASP, ASP.NET, ColdFusion, MSSQLManager
• Mail: Mailboxes, Autoresponder for mailboxes, Mailforwards, Mailing lists
• FTP: resources: virtual hosts, anonymous virtual hosts, virtual host directories with permissions, virtual host users, FTP subaccounts (Unix)
• MySQL: users, databases with user permissions
• PostgreSQL: users, databases
• MSSQL: users, logins, databases
• ODBC: dsn records with params
• Crontab: crontab records for users

The following resources are NOT YET implemented in XML migration mechanism:

• DNS: instant access domain alias
• Web: SSL, Shared SSL, MivaEmpresa, MivaCart, osCommerce, PhpBB

Migration Procedure

The migration procedure takes the following steps:

Step 1. Create XML File Containing User Data

Create xml and dtd files to migrate resellers and end users or end users without resellers.

If you are moving users from H-Sphere, do it with the UserInfoExtractor utility as suggested in Creating User Migration XMLs In H-Sphere.

If you are moving users from a different control panel, follow the instruction on Creating User Migration XMLs Outside H-Sphere.

Step 2. Create XML File Containing Reseller Plan Data

Note: Skip this step if you are migrating only master admin's end users.

Create XML files for the reseller plans to be migrated. If you migrate from H-Sphere, use the PlanExtractor utility. Otherwise, create plan XML according to our documentation. Please refer to Migrating Plans with XML for details.

Step 3. Prepare The Target Control Panel

Before you start creating accounts from the xml files, log as cpanel user, go to the target H-Sphere control panel and do the following:

1. Make sure that the names of the plans are exactly the same as those in your user data xml file. To get a list of all reseller and user plans in the system, run:
   
   java psoft.hsphere.migrator.ResellerUserCreator -d migrate_resellers.xml -dl -pp
2. In the xml file, find users that have empty or filled mysql tag. In the control panel, enable MySQL resource for the plans you are migrating these users to.
3. If you intend to migrate the existent user content into H-Sphere, include but deactivate FrontPage in all plans you are migrating your customers to, and in which FrontPage will be used.
4. If you want to preserve original billing period start date, make sure that the billing periods have the same duration and go in the same order as those in your old control panel.

Step 4. Create Reseller Plans

Note: Skip this step if you don't have resellers.

If you have resellers, run PlanCreator to create reseller plans on the target H-Sphere installation, for example:

Step 5. Create Resellers

To create resellers, run ResellerUserCreator:

Step 6. Create End Users

To migrate end users, run CommonUserCreator:

Note: To prevent double charges for resources billed on the monthly basis, such as Traffic and Disk Usage, CommonUserCreator shifts start date for them to the day before the date of migration.

Troubleshooting

If the migration software fails to create a reseller/end user account, it will return an error and stop the migration. In this case, read the messages on the screen to find which user caused the failure, read the log file and try to remove the cause of the error.

Note: If the domain tag of this user in the XML file contains the ip attribute and if the IP in this user's domain was created before the error occurred, go to the H-Sphere control panel and delete this IP.

Then, proceed with the migration using the above command plus one of these two options:
-r user_login - proceed with the migration starting with the user with this login name;
-rc user_login - delete this user and then proceed with the migration starting with this user.
The full command must look like this:
a) for a reseller's end user: