|
This document explains how to migrate users into H-Sphere
from other hosting control panels.
Besides, it may serve as a
guide to setting up a large number of H-Sphere users at a time.
It covers the following topics:
The mechanism of user migration allows you to transfer:
- User contact info
- User billing info
- Domains (with DNS as well as without)
- Mailboxes
- Autoresponder for mailboxes
- Mailforwards
- Mailing lists
- MySQL databases with user privileges
Requirements
- Installed and correctly tuned H-Sphere control panel.
- Set of user data to transfer, as described below. User data must include the following items:
- Contact info
- Billing info
- Username and password
- Domain names
- Mailboxes
- Autoresponse texts for mailboxes
- Names of the mailing lists with the names of the subscribers
- Names of the mail forwards with the names of the subscribers
- Names of MySQL databases with user privileges
Formatting User Data
User data must be organized in two files, one with end user data,
the other with reseller data, each having two parts,
(1) data definitions and (2) structurized data, and complying
with the following requirements:
- The string "Special" in the account's tag attribute
is the name of the plan inside H-Sphere.
This means that the account for John-the-User will be created
under the plan with the name "Special". It is recommended
to create one plan for all transferred users, but of course
you can create individual plans for each transferred account.
- Both of the info tag groups are obligatory, and should be
entered as shown in the example, excluding the user data.
IMPORTANT: under no circumstances should you replace the value
of the items's tag name attribute or the value of the info's
prefix attribute.
- Each domain tag must contain the mailservice tag, even if
the latter contains no data.
- mailservice tag contains different types of mail objects.
Each mail object has the "name" or "email"
attributes. The value of the "name" attribute is
appended to "@domain_name", where the domain_name
is the name of the enclosing domain tag. In other words, do
not assign attribute names such values as "smth@domain_name".
However, when the attribute is called "email", provide
a full e-mail address as the value.
Formatting End User Data
Create the migrate_users.xml file. It will have two parts:
Part 1: Data Type Definitions
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE users [
<!ELEMENT users (user+)>
<!ELEMENT user (account+)>
<!ELEMENT info (item+)>
<!ELEMENT account (info+, domain*, mysql*)>
<!ELEMENT domain (mailservice+,subdomain*,aliases*,dns*)>
<!ELEMENT subdomain (mailservice*,aliases*,dns*)>
<!ELEMENT mailservice (mailbox*,forward*,maillist*)*>
<!ELEMENT aliases (alias+)>
<!ELEMENT alias (dns*)>
<!ELEMENT mailbox (autoresponder*)>
<!ELEMENT forward (subscriber+)>
<!ELEMENT maillist (subscriber*)>
<!ELEMENT mysql (database*,mysqluser*)>
<!ELEMENT mysqluser (grant*)>
<!ELEMENT autoresponder (#PCDATA)>
<!ELEMENT dns (record+)>
<!ELEMENT record (#PCDATA)>
<!ATTLIST user login CDATA #REQUIRED>
<!ATTLIST user password CDATA #REQUIRED>
<!ATTLIST user reseller CDATA "">
<!ATTLIST account suspended CDATA "">
<!ATTLIST account plan CDATA #REQUIRED>
<!ATTLIST account balance CDATA "">
<!ATTLIST account bpid CDATA "">
<!ATTLIST account startdate CDATA "">
<!ATTLIST info prefix CDATA #REQUIRED>
<!ATTLIST item name CDATA #REQUIRED>
<!ATTLIST domain name CDATA #REQUIRED>
<!ATTLIST domain ip CDATA "">
<!ATTLIST domain quota CDATA "">
<!ATTLIST domain transfer CDATA "">
<!ATTLIST domain type CDATA "transfer">
<!ATTLIST subdomain name CDATA "">
<!ATTLIST mailservice catchall CDATA "">
<!ATTLIST mailbox name CDATA #REQUIRED>
<!ATTLIST mailbox password CDATA "">
<!ATTLIST forward name CDATA #REQUIRED>
<!ATTLIST subscriber email CDATA #REQUIRED>
<!ATTLIST maillist name CDATA #REQUIRED>
<!ATTLIST database name CDATA #REQUIRED>
<!ATTLIST database description CDATA "">
<!ATTLIST mysqluser login CDATA #REQUIRED>
<!ATTLIST mysqluser password CDATA #REQUIRED>
<!ATTLIST grant privileges CDATA #REQUIRED>
<!ATTLIST grant on CDATA #REQUIRED>
<!ATTLIST alias name CDATA #REQUIRED>
<!ATTLIST alias dns CDATA "1">
<!ATTLIST record name CDATA #REQUIRED>
<!ATTLIST record type CDATA #REQUIRED>
<!ATTLIST record ttl CDATA #REQUIRED>
<!ATTLIST record data CDATA #REQUIRED>
<!ATTLIST record pref CDATA "">
]>
Part 2: Formatting Actual User Data.
Enter user data into the migrate_users.xml file.
This will be the second part of the file containing data
for each individual user. You may have hundreds and
thousands of users in your file.
Example:
<users>
<user login="john" password="the-user" reseller="resellerguy">
<account plan="Special">
<info prefix="_bi_">
<item name="first_name">John</item>
<item name="last_name">The-User</item>
<item name="company">John-the-user inc.</item>
<item name="address1">Example Street 10</item>
<item name="city">New York</item>
<item name="state">New York</item>
<item name="postal_code">ABC #J0</item>
<item name="country&qu*ot;>US</item>
<item name="phone">###-###-####</item>
<item name="email">john@example.com</item>
<item name="type">Check</item>
</info>
<info prefix="_ci_">
<item name="first_name">John</item>
<item name="last_name">The-User</item>
<item name="company">John-the-user inc.</item>
<item name="address1">Example Street 10</item>
<item name="city">New York</item>
<item name="state">New York</item>
<item name="postal_cod*e">ABC #J0</item>
<item name="country">US</item>
<item name="phone">###-###-####</item>
<item name="email">john@example.com</item>
<item name="type">Check</item>
</info>
<domain name="example.com">
<mailservice catchall="support">
<mailbox name="sales" password="123456">
<autoresponder>
This is some test message in autoresponder.
</autoresponder>
</mailbox>
<mailbox name="support" password="123456">
</mailbox>
<mailbox name="payroll" password="123456">
</mailbox>
<maillist name="news">
<subscriber email="subsriber1@example.com"/>
<subscriber email="subscriber2@example.com"/>
</maillist>
<forward name="solver">
<subscriber email="subsriber3@example.com"/>
<subscriber email="support@example.com"/>
</forward>
</mailservice>
<subdomain name="sub1.example.com"/>
<subdomain name="sub2.example.com"/>
<aliases>
<alias name="example.com"></alias>
<alias name="example.example.com"></alias>
</aliases>
</domain>
<mysql>
<database name="db_name" description="db_description"/>
<mysqluser login="db_login" password="db_password">
<grant privileges="'grant select,insert,update,delete,create,drop,alter
on `db_name`.* to db_login@"%"'" on="db_name"/>
</mysqluser>
<mysqluser login="somelogin" password="somepassword">
<grant privileges="'grant select,insert,update,delete,create,drop,alter
on `db_name`.* to somelogin@"%"'" on="db_name"/>
</mysqluser>
</mysql>
</account>
</user>
<user login="somelogin" password="somepassword" reseller="resellerguy">
<account plan="Unix Basic" balance="$66.72" startdate="11/21/2003" bpid="2">
<info prefix="_bi_">
<item name="first_name">somefirstname</item>
<item name="last_name">somelastname</item>
<item name="company">Some ltd.</item>
<item name="address1">Some Street 11</item>
<item name="city">London</item>
<item name="state">London</item>
<item name="postal_code">ABC #J0</item>
<item name="country">UK</item>
<item name="phone">###-###-####</item>
<item name="email">user@example.com</item>
<item name="type">CC</item>
<item name="cc_type">AX</item>
<item name="cc_number">#### ###### #####</item>
<item name="cc_name">Example credit card name</item>
<item name="cc_exp_month">01</item>
<item name="cc_exp_year">2004</item>
<item name="cc_name">Example credit card name</item>
</info>
<info prefix="_ci_">
<item name="first_name">Somefistname</item>
<item name="last_name">Somelastname</item>
<item name="company">Some ltd.</item>
<item name="address1">Some Street 11</item>
<item name="city">London</item>
<item name="state">London</item>
<item name="postal_code">ABC #J0</item>
<item name="country">UK</item>
<item name="phone">###-###-####</item>
<item name="email">user@example.com</item>
<item name="type">CC</item>
</info>
<domain name="examplehoster.com" type="service">
<mailservice>
<mailbox name="sales" password="123456">
<autoresponder>
This is some test message in autoresponder.
</autoresponder>
</mailbox>
<mailbox name="support" password="123456">
</mailbox>
<mailbox name="payroll" password="123456">
</mailbox>
<maillist name="news">
<subscriber email="subsriber1@example.com"/>
<subscriber email="subsriber2@example.com"/>
</maillist>
<forward name="solver">
<subscriber email="joe@example.com"/>
<subscriber email="support@example.com"/>
</forward>
</mailservice>
<subdomain>
<subdomain name="sub1.example.com"></subdomain>
<subdomain name="sub2.example.com"></subdomain>
</subdomain>
<aliases>
<alias name="example.com"></alias>
<alias name="whatever.example.com"></alias>
</aliases>
</domain>
<domain name="thirdlevel.examplehoster.com" type="3ldomain">
<mailservice>
<mailbox name="sales" password="123456">
<autoresponder>
This is some test message in autoresponder.
</autoresponder>
</mailbox>
<mailbox name="support" password="123456">
</mailbox>
</mailservice>
</domain>
<mysql>
<database name="db_name" description="db_desription"/>
<mysqluser login="example_login" password="example_password">
<grant privileges="'grant select,insert,update,delete,create,drop,alter
on `db_name`.* to example_login@"%"'" on="db_name"/>
</mysqluser>
<mysqluser login="example_login" password="example_password">
<grant privileges="'grant select,insert,update,delete,create,drop,alter
on `db_name`.* to example_login@"%"'" on="db_name"/>
</mysqluser>
</mysql>
</account>
</user>
</users>
Note: In case of a user who is not created under a reseller, there is no need to
have the reseller attribute in the user tag:
<user login="mynewuser" password="passw">
If you need a user to be created under a particular reseller,
the reseller attribute takes the value of the reseller's login name:
<user login="newuser" password="passw" reseller="somereseller">
Preserving Account Billing
File migrate_users.xml allows you to transfer users with their account billing intact.
Account's main 'billing' attributes are:
- balance defines transferred account opening balance
- startdate defies transferred account creation date
Important: never set startdate later than the migration date, as it will cause unpredictable billing malfunctions.
- bpid defines transferred account billing period number: 0 - 1 month, 1 - 2 months, 2 - 3 months etc.
Example:
A user registered account with you on October 5, 2002;
on May 2, 2003 you are migrating this user to H-Sphere;
the account is transferred on a three month billing period;
the total cost of resources available under the plan for three months makes $90;
the uer has already pre-paid for the services until July 30, 2003.
Setting the above account attributes to:
<account balance="$115.00" startdate="10/5/2002" bpid="2">
you will transfer account to H-Sphere as created on October 5, 2002 with the first invoice of April 5, 2003 - July 5, 2003.
H-Sphere will leave out all 'closed' billing periods by the time of the transfer (i.e. October 5, 2002 - January 5, 2003 and
January 5, 2003 - April 5, 2003).
It will accrue the account $90 plan's recurrent fee for the current billing period of April 5, 2003 - July 5, 2003 and
immediately credit $115 as Initial balance adjustment.
This amount covers the current billing period expenses ($90) and prorated expenses for 25 days of the next billing period
the user already pre-paid for ($25).
Formatting Reseller Data
Create migrate_resellers.xml file. Its first part (data type definitions)
must be the following:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resellers [
<!ELEMENT resellers (reseller+)>
<!ELEMENT info (item+)>
<!ELEMENT reseller (info+,administrator,zone+)>
<!ELEMENT zone (instantalias+)>
<!ATTLIST reseller login CDATA #REQUIRED>
<!ATTLIST reseller password CDATA #REQUIRED>
<!ATTLIST reseller plan CDATA #REQUIRED>
<!ATTLIST info prefix CDATA #REQUIRED>
<!ATTLIST item name CDATA #REQUIRED>
<!ATTLIST administrator login CDATA #REQUIRED>
<!ATTLIST administrator password CDATA #REQUIRED>
<!ATTLIST administrator email CDATA #REQUIRED>
<!ATTLIST zone name CDATA #REQUIRED>
<!ATTLIST zone email CDATA #REQUIRED>
<!ATTLIST instantalias prefix CDATA #REQUIRED>
<!ATTLIST instantalias tag CDATA #REQUIRED>
]>
Next, enter reseller data into migrate_resellers.xml
according to the following example:
<resellers>
<reseller login="acc" password="acc" plan="Reseller Plan">
<info prefix="_ci_">
<item name="first_name">Reseller_name</item>
<item name="last_name">Reseller_last_name</item>
<item name="email">reseller@example.com</item>
<item name="company">Accounting Resources</item>
<item name="address1">Reseller_address</item>
<item name="address2"/>
<item name="city">Reseller city</item>
<item name="state">CA</item>
<item name="postal_code">#####</item>
<item name="country">US</item>
<item name="phone">###-###-####</item>
</info>
<info prefix="_bi_">
<item name="first_name">Reseller_name</item>
<item name="last_name">Reseller_last_name</item>
<item name="email">reseller@example.com</item>
<item name="company">Accounting Resources</item>
<item name="address1">Reseller_address</item>
<item name="address2"/>
<item name="city">Reseller_city</item>
<item name="state">CA</item>
<item name="type">CC</item>
<item name="cc_type">AX</item>
<item name="cc_number">################</item>
<item name="cc_name">Reseller_credit_card_name</item>
<item name="cc_exp_month">01</item>
<item name="cc_exp_year">2004</item>
<item name="postal_code">92626</item>
<item name="country">US</item>
<item name="phone">###-###-####</item>
</info>
<administrator email="admin@example.com" login="admin_login" password="admin_password"/>
<zone email="webmaster@example.com"
name="example.com"> <instantalias prefix="u" tag="2"/> </zone>
</reseller>
<resellers>
Creating Accounts
Before you start creating accounts from the xml files,
go to the H-Sphere control panel and do the following:
-
Make sure that the names
of the plans are exactly the same as those in your old control panel and
user data xml file.
-
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.
-
If you intend to migrate the existent user content into H-Sphere,
then, in Plan Wizard, include but deactivate
FrontPage in all plans you are migrating your customers to, and in which
FrontPage will be used.
-
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.
Besides the control panel settings, you need to do the following:
Validate the user data xml files with any xml validation software. Make sure the xml file does not contain user with the login "admin".
If such user exists, rename it. Make sure that mail sections of each user in the xml file don't contain mail loops. The billing period starting date in the user data xml file must have the format:
"MM/dd/yy"
Make sure that in the user tag the value of the login attribute is unique
and does not begin with a number
(this value will be used as the H-Sphere control panel login name).
Now you are ready to create the accounts. For this, do the following:
If you have resellers:
- Log into your control panel server under cpanel user running the following command:
su -l cpanel
- Execute the following command:
java psoft.hsphere.migrator.ResellerUserCreator -d file.xml -l migrate.log -dl
These parameters are required and define the following:
-d file.xml - the name of the xml file to be migrated;
-l migrate.log - the name of the log file;
-dl - write detailed log.
- After you have migrated resellers, migrate end users with
the following command:
Note: make sure you are logged under cpanel user.
java psoft.hsphere.migrator.CommonUserCreator -d file.xml -l migrate.log -dl
These parameters are required and define the following:
-d file.xml - the name of the xml file to be migrated;
-l migrate.log - the name of the log file;
-dl - write detailed log.
If the migration software fails to create a user account, it will return an error,
and stop the migration process. 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 - try to delete this user and then proceed with the migration starting with this user.
The full command must look like this (make sure you are logged as cpanel user):
java psoft.hsphere.migrator.CommonUserCreator -d file.xml -l migrate.log -dl -r user_login
After the transfer, users may change their type of payment.
|
