Parallels H-Sphere - 3.5 Developer Guide

Parallels® H-Sphere

Parallels H-Sphere 3.5
Developer Guide

Legal and Copyright Notice

ISBN: N/A

Parallels Holdings, Ltd.

c/o Parallels International GmbH

Vordergasse 59

CH-Schaffhausen

Switzerland

Phone: [phone]

Fax: [phone]

© Copyright 2011,

Parallels, Inc.

All rights reserved

Distribution of this work or derivative of this work in any form is prohibited unless prior

written permission is obtained from the copyright holder.

Product and service names mentioned herein are the trademarks of their respective owners.

Contents

Preface 5

About This Guide ........................................................................................................................... 6

Typographical Conventions ........................................................................................................... 6

Feedback ....................................................................................................................................... 7

H-Sphere System Database 8

Getting User Information from the Parallels H-Sphere System Database .................................... 9

Database Connections ................................................................................................................ 13

Regular Shared Connections ............................................................................................ 13

Connections With Opened Transaction ............................................................................ 13

Unix Hosting Resources and Tools 15

Creating Unix-Hosted Resources ................................................................................................ 16

Example: ............................................................................................................................ 21

Global Resources And Resource Dependencies ........................................................................ 26

globals.xml ......................................................................................................................... 26

resource_dependences.xml .............................................................................................. 30

List of Resource Dependencies ........................................................................................ 30

Account Preferences ................................................................................................................... 33

TimeUtils Class ............................................................................................................................ 33

FreeMarker Access Control List (FMACL) Objects ..................................................................... 35

Purpose ............................................................................................................................. 35

Implementation .................................................................................................................. 35

External Credits ........................................................................................................................... 37

Running Parallels H-Sphere in Debug Mode .............................................................................. 38

Script Runner ............................................................................................................................... 39

Windows Hosting Resources 40

Creating Resources for Winbox ................................................................................................... 41

Introduction ........................................................................................................................ 41

Requirements .................................................................................................................... 41

Naming Conventions ......................................................................................................... 41

General Scheme of Resource Functioning ....................................................................... 42

Methods ............................................................................................................................. 43

Keys ................................................................................................................................... 44

Error Handling ................................................................................................................... 45

Resource Hierarchy ........................................................................................................... 46

Logging .............................................................................................................................. 46

Resource Types ................................................................................................................ 46

Schemas ............................................................................................................................ 47

Attributes ........................................................................................................................... 48

Crash Reporting on Winbox ........................................................................................................ 52

Crash Record File Structure .............................................................................................. 52

Detecting Crashes in Parallels H-Sphere and non Parallels H-Sphere Modules ............. 53

IIS 6.0 Native Mode ..................................................................................................................... 53

ISAPI Filters ....................................................................................................................... 54

IIS Log Plugin .................................................................................................................... 54

Preface 4

Parallels H-Sphere XML API 55

Enabling Parallels H-Sphere XML API ........................................................................................ 57

Testing Parallels H-Sphere XML API .......................................................................................... 57

Getting the List of Available XML API Services ........................................................................... 59

Generating WSDL Files for Parallels H-Sphere XML API Services ............................................ 60

Parallels H-Sphere XML API Security Settings and Authentication ............................................ 60

Adding Custom Payment Gateways and Domain Registrars 63

Web Payment SDK ...................................................................................................................... 64

Domain Registrar SDK ................................................................................................................ 64

Merchant Gateway SDK .............................................................................................................. 64

Appendix 66

Logging in as the cpanel User ..................................................................................................... 67

Restarting Parallels H-Sphere Control Panel .............................................................................. 67

In this chapter:

About This Guide ............................................................................................... 6

Typographical Conventions ............................................................................... 6

Feedback .......................................................................................................... 7

C H A P T E R 1

Preface

6 Preface

Formatting convention

Type of Information

Example

Special Bold

Items you must select,
such as menu options,
command buttons, or
items in a list.

Go to the System tab.
Titles of chapters,
sections, and
subsections.

Read the Basic
Administration chapter.

Italics

Used to emphasize the
importance of a point, to
introduce a term or to
designate a command
line placeholder, which is
to be replaced with a real
name or value.

The system supports the
so called wildcard
character search.

Monospace

The names of
commands, files,
directories, and domain
names.

The license file is located
in the

http://docs/common/
licenses directory.

About This Guide

This guide explains how to perform certain development tasks, such as, creating
custom Unix-hosted and Windows-hosted resources. It provides Parallels H-Sphere
XML API reference to manage Parallels H-Sphere services from remote applications
via SOAP.

It is helpful that you also refer to Parallels H-Sphere Customization Guide for the
explanation of Parallels H-Sphere customization, localization, and Parallels H-Sphere
addons (packages).

Typographical Conventions

Before you start using this guide, it is important to understand the documentation
conventions used in it.

The following kinds of formatting in the text identify special information.

Preface 7

Preformatted

On-screen computer
output in your command­line sessions; source
code in XML, C++, or
other programming
languages.

# ls –al /files

total 14470

Preformatted
Bold

What you type,
contrasted with on-screen
computer output.

# cd /root/rpms/php

CAPITALS

Names of keys on the
keyboard.

SHIFT, CTRL, ALT

KEY+KEY

Key combinations for
which the user must
press and hold down one
key and then press
another.

CTRL+P, ALT+F4

Feedback

If you have found a mistake in this guide, or if you have suggestions or ideas on how to
improve this guide, please send your feedback using the online form at

http://www.parallels.com/en/support/usersdoc/. Please include in your report the

guide‟s title, chapter and section titles, and the fragment of text in which you have found
an error.

This chapter explains how to write common queries to the H-Sphere system database

In this chapter:

Getting User Information from the Parallels H-Sphere System Database .......... 9

Database Connections ...................................................................................... 13

C H A P T E R 2

H-Sphere System Database

and how to operate with the database connections.

H-Sphere System Database 9

Getting User Information from the Parallels H-Sphere System Database

Selecting user info:

select users.* from users, user_account where
users.id=user_account.user_id and user_account.account_id=
USER_ACCOUNT_ID;

Selecting mail accounts info:

select m.* from mailboxes m, parent_child p where p.child_type=1002 and
p.child_id=m.id and p.account_id= USER_ACCOUNT_ID;

Selecting resellers info:

select u.* from users u, resellers r, user_account a where
u.id=r.admin_id and r.id=a.user_id and account_id= USER_ACCOUNT_ID;

Selecting credit card info:

select c.* from users u, user_billing_infos u_b, credit_card c,
user_account a
where u.id = u_b.user_id and c.id = u_b.billing_info_id and

u.id=a.user_id and a.account_id= USER_ACCOUNT_ID;

Selecting reseller’s users credit card info:

This is possible if you don‟t encrypt credit card numbers in Parallels H-Sphere
database. In this case run the following query:

select cc.cc_number, cc.name, cc.exp_year, cc.exp_month, cc.type from
accounts as acc join credit_card as cc on (cc.id=acc.bi_id) where
acc.reseller_id= RESELLER_ACCOUNT_ID;

Selecting credit card types:

 All supported credit cards:

select * from cc_brands;

 Credit cards allowed in Merchant Gateway:

select * from active_merch_gateway;

Selecting virtual FTP info:

select f.* from ftp_vuser f, parent_child p where p.child_type=2003 and
p.child_id=f.id and p.account_id= USER_ACCOUNT_ID;

Selecting user’s home directory:

To select user‟s home directory from the system database and connect it to account:

select * from unix_user where unix_user.id = parent_child.child_id and
parent_child.account_id = USER_ACCOUNT_ID;

Selecting user’s website directory:

Website directory always equals user‟s home directory and domain
name.

Selecting user’s hosting plan:

10 H-Sphere System Database

To select the name of the plan, run the following query:

select plans.description from plans, accounts where accounts.id =
USER_ACCOUNT_ID and plans.id = accounts.plan_id;

Selecting domain name:

To obtain data on domain names, run the following query:

select domains.name from domains, parent_child where domains.id =
parent_child.child_id and parent_child.account_id = USER_ACCOUNT_ID;

Selecting IP address:

To retrieve data on all IPs, run the following query:

select IP from l_server_ips, parent_child where child_id =
l_server_ips.r_id and parent_child.child_type = 8 and

parent_child.account_id = USER_ACCOUNT_ID;.

There can be multiple IPs per domain.

Selecting IP of the domain:

To retrieve IP for the given domain name, run the following command:

select IP from l_server_ips, domains, parent_child where domains.id =
parent_child.parent_id and parent_child.child_id = l_server_ips.r_id
and domains.name =’YOUR_DOMAIN_NAME’;

Selecting account ID for the domain:

To get the data about account ID of the given domain, execute the query:

select account_id from domains, parent_child where domains.id =
parent_child.child_id and domains.name =’DOMAIN_NAME’;

Selecting logical server of the domain:

To retrieve IP for the given domain name, run the following command:

select hostid from unix_user, parent_child where
parent_child.account_id = YOUR_ACCOUNT_ID and child_id = unix_user.id;

Selecting shared IP of the domain:

To get the information about shared IPs for the domain, run:

select IP from l_server_ips where where l_server_id =’HOSTID’ and flag
=’SHARED_IP’;

Selecting user’s e-mail address:

To receive data on clients contact emails, run the following query:

select * from contact_info, accounts where contact_info.id =
accounts.ci_id and accounts.id = USER_ACCOUNT_ID;

Selecting emails of all users, excluding resellers’ end users:

To receive the list of all email addresses ignoring resellers‟ end users, run the following
query:

H-Sphere System Database 11

select c_i.email from contact_info c_i join accounts a on
(c_i.id=a.ci_id and a.reseller_id=1);

Getting user emails by their MySQL database names:

select c.email from mysqldb m, parent_child pc, accounts a,
contact_info c where m.db_name=’DBNAME’ and m.id=pc.child_id and
pc.child_type=6001 and pc.account_id=a.id and a.ci_id=c.id;

Verify users:

To verify whether a user exists in Parallels H-Sphere:

select id from users where username=’USER_NAME’ and
password=’PASSWORD’;

Defining physical/logical servers:

Run the following commands to get info about physical/logical servers:

 by IP address:

select l_server_id from l_server_ips where l_server_ips =
‘IP_ADDRESS’;

 by logical server:

select p_server_id from l_server where id = ‘LOGICAL_SERVER_ID’;

 selecting info about physical server:

select * from p_server where id = ‘PHYSICAL_SERVER_ID’;

Selecting user’s billing info:

To select billing info from accounts, run the following query:

select * from billing_info, accounts where billing_info.id =
accounts.bi_id and accounts.id =USER_ACCOUNT_ID;

Billing periods for plans:

All information including discounts if present:

select * from plan_value where name like ‘_PERIOD%’ and plan_id=plan_id;

Discounts:

select * from plan_value where name like ‘%_DISC_%’ and plan_id=plan_id;

Payment modes:

select billing from plans where id=plan_id;

plans.billing takes the following values:

 0 - without billing;

 1 - billing mode;

 2 - billing with trial period.

Getting plan pricing details:

select * from plan_value where plan_id=plan_id;

Getting domain registration pricing details:

 select * from tld_prices;

12 H-Sphere System Database

 select * from plan_value where name like „_TLD_%‟;

H-Sphere System Database 13

Database Connections

There are two possible types of connections to the Parallels H-Sphere database:

 Regular shared connections

 Connections with opened transaction

Important: In any case, you should use only prepared statements when working with
the Parallels H-Sphere database!

Regular Shared Connections

The part of the code which establishes and uses a regular database connection should
look something similar to this:

PreparedStatement ps = null;
Connection con = Session.getDb();
try {

ps = con.prepareStatement(...........);

......................................

} finally {
Session.closeStatement(ps); con.close();
}

Connections With Opened Transaction

In general, the part of the code which establishes and uses a transaction connection
should look as follows:

// checking if the transaction exists
boolean wasTrans = Session.isTransConnection();
Connection con = wasTrans ? Session.getDb() :
Session.getTransConnection();
try {
// some operation with the database
} catch (Exception ex){
if (!wasTrans) {
// rollback transaction
con.rollback();
// some data to release cache and to synchronize with old data
in HS DB
}
throw ex;
} finally {
if (!wasTrans) {
// commit transaction and release connection
Session.commitTransConnection(con);
} else {
con.close();

14 H-Sphere System Database

}
}

Important:

1 There is the pool of transaction connections (5 by default). Opening a

new transaction that exceeds this maximum would cause the system
to hang up.

2 As the number of available transactions is resctricted, you must

release the transaction connection you have opened by using the
following command:

Session.commitTransConnection(con);

3 To get an opened transaction connection:

con = Session.getTransConnection();

4 Later in the code, you may get the same connection:

con = Session.getDb();

Note: Never close a transaction connection you haven‟t opened!

5 Please make sure you synchronize your objects with the

corresponding data in the database. You must release your cache if
you make a rollback.

This chapter explains how to write custom Unix hosting resources and outlines some

In this chapter:

Creating Unix-Hosted Resources ...................................................................... 16

Global Resources And Resource Dependencies ............................................... 26

Account Preferences ......................................................................................... 33

TimeUtils Class ................................................................................................. 33

FreeMarker Access Control List (FMACL) Objects ............................................ 35

External Credits ................................................................................................. 37

Running Parallels H-Sphere in Debug Mode ..................................................... 38

Script Runner .................................................................................................... 39

C H A P T E R 3

Unix Hosting Resources and Tools

other developer tools related to Parallels H-Sphere Unix servers.

16 Unix Hosting Resources and Tools

Creating Unix-Hosted Resources

A Unix-hosted resource is created as follows:

1 Login as the cpanel user (on page 67) to CP server.

2 Create a class that implements this resource.

Create a new Parallels H-Sphere resource class in the

~cpanel/shiva/psoft/hsphere/resource directory. For example:

package psoft.hsphere.resource;
import psoft.hsphere.*;
import java.util.Collection;

public class MyResource extends Resource {
public MyResource(int type, Collection init) throws Exception
{
super(type, init);

...........

}
public MyResource(ResourceId rid) throws Exception {
super(rid);

...........

}
}

The class must have 2 constructors, as illustrated in the above example.

 The first constructor, MyResource(int type, Collection init), is used

on the resource creation and its init argument contains the list of the String class
objects. The MyResource method‟s arguments starting from the third are
parameters passed from the HTML form. For example:

<assign result=parent.addChild(request.resource_name,””, db_id,
user_id)>

Here, db_id and user_id are parameters taken from the HTML form.

In this case, the values of db_id and user_id are passed to constructor as
Collection of Strings.

 The second constructor, MyResource(ResourceId rid), is used when the

user (owner of the resource) is logged in and ClassLoader loads the resource.

Also, the resource may overwrite the initDone() method called upon the
resource creation. initDone() is designed to save all additional parameters into
the database and to execute additional scripts.

The resource may also overwrite the delete() method called upon the recource
deletion. This method is used to delete all additional database records related to
this resource.

If the resource creates system resources (directories, files, etc.) on a certain host,
the resource should implement the HostDependentResource interface:

package psoft.hsphere.resource;

Unix Hosting Resources and Tools 17

public interface HostDependentResource {
/**

• Method checks if a resource can be moved to the target
server

• @param newHostId

• @return

• @throws Exception

*/
public boolean canBeMovedTo(long newHostId) throws Exception;

/** The method physically creates a physical implementation

• of a resource on a logical serevr with the passed ID

• @param targetHostId

• @throws Exception

*/
public void physicalCreate(long targetHostId) throws
Exception;

/**

• The metod deletes a physical implementation of a resource
on

• a logical server with the passed ID

• @param targetHostId

• @throws Exception

*/
public void physicalDelete(long targetHostId) throws
Exception;
/**

• The method sets an ID of the logical server to

• which this resource is linked

• @param newHostId

• @throws Exception

*/
public void setHostId(long newHostId) throws Exception;
/**

• The method returns an ID of a logical server

• to which this resource is being linked

• @return

• @throws Exception

*/
public long getHostId() throws Exception;
}

In case of the HostDependentResource implementation, the method
physicalCreate(long targetHostId) must be called from the method
initDone(), and the method physicalDelete(long targetHostId) from

the method delete(). The methods physicalCreate(long targetHostId)
and physicalDelete(long targetHostId) call scripts to create and delete
system resources, respectfully. The method canBeMovedTo(long newHostId)
should return true if physical components of the resource (files, directories, etc) can
be moved to or created on the host. The methods setHostId(long newHostId)
and getHostId() respectfully set and get id of the host where resource physical
components are located.

18 Unix Hosting Resources and Tools

General order of calling methods during the first resource creation is as follows:

Column

Type

Modifier

Description

id

integer

not null

unique resource type id

name

character
varying(40)

not null

unique resource name

price

character
varying(5)

flags:

M (initial value must be set)

R (recurrent)

U (usage)

F (initial value is optional)

S (setup)

description

character
varying(100)

resource brief description

MyResource(int type, Collection init)
public void initDone()
public void physicalCreate(long targetHostId)

The resource parameter values predefined in the <plan_name>.xml file can be
retrieved by calling the getPlanValue(String key) method defined in
Resource.class. For example, in unix.xml, the myresource resource is
described with the res_myresource construction with the block of predefined values:

<res_myresource>
...
<values>
<value name=”some_key”>some value</value>
...
</values>
</res_myresource>

Then, to get the value for some_key, the getPlanValue method is used as
follows:

<assign value=myresource.getPlanValue(“some_key”)>

In order to retrieve the resource values, FM_ methods should be implemented to be
called from the HTML form. FM_ method, with its name having the FM_ prefix, is a
method that returns a value of the TemplateModel class. If you call an FM_
method from a template, the Freemarker code will look like:

<assign multiply=myresource.multiply(a, b)>

Here, myresource is resource name in the plan, and multiply refers to the
FM_multiply(a, b) method, where a and b are the method‟s arguments. In

this case, the TemplateModel‟s FM_multiply(int x, int y) method of
MyResource class will be called.

3 Insert resource information into the Par allels H-Sphere database.

Information must be added to the type_name table:

Unix Hosting Resources and Tools 19

rprice

character
varying(5)

reseller flags:

R (recurrent)

U (usage)

F (initial value is optional)

S (setup)

required

smallint

flag indicating if this resource is
required for all accounts

priority

smallint

must be 0

ttl

integer

resource deletion time (should not be
set initially)

20 Unix Hosting Resources and Tools

 Index: type_name_name

Primary key: type_name_pkey To add a resource, insert the resource data into the

type_name table, like this:

INSERT INTO type_name (id,name,description,required,priority)
VALUES (119, „my_resource‟, „My Resource‟,0,0);

1 Include the resource to the plan XML configuration file.

The resource should be included into XML configuration files for each type of plans
where this resource is to be enabled (for example, unix.xml for Unix plan). These
files are located in the ~cpanel/shiva/psoft/hsphere/plan/wizard/xml/
directory.

You need to add the resource tags with the new resource wherever necessary
according to the guide on creating XML plan wizards in Parallels H-Sphere
Customization Guide.

For example:

<categories>

.......................

<category description=”planeditor.myresource”>

.........................................

<resource name=”my_resource”
class=”psoft.hsphere.resource.MyResource” adminonly=”1”/>

.........................................

</category>

.......................

</categories>

To make the resource available automatically upon accounts‟ creation, add the
res_RESOURCE_NAME construction to the plan XML file, where RESOURCE_NAME is
the value set in the name attribute of the resource tag for the given resource.

Make sure you also set the interface text label set as the description attribute of the
category tag. This is done in the custom hsphere_lang.properties file. For the
label in the above example, the label is set as follows:

planeditor.myresource = My Resource

2 Implement the resource in CP Web interface.

1. Create templates for this resource.

Create templates according to the template procedure. See the example below
for the templates you may need to add.

2. Add a new menu item for this resource in CP menu.

Customize CP menu and add a new menu item to the custom menu.xml, for
example:

<menudef id=”unix”>

....................

<menuitem name=”myresource” label=”myresource.label”
URL=”design/myresource.html” resource=””
tip=”myresource.tip”/>

....................

</menudef>

Unix Hosting Resources and Tools 21

Then, add labels myresource.label and myresource.tip to the custom
hsphere_lang.properties file and run language bundle compiler:

[]$ java psoft.hsphere.LangBundlesCompiler

3 Create scripts for the resource’s physical implementation.

You must be logged in as root to create these scripts in the
/hsphere/shared/scripts/ directory. See the example below on how you
may create these scripts.

Note: Make changes to custom templates, interface text bundles and XML files, not to
the default ones! Otherwise, you will lose your settings with subsequent Parallels H­Sphere upgrades. Please refer to the Parallels H-Sphere Customization Guide for
details.

Example:

Below is a detailed example of how to create and add a new resource to Parallels H­Sphere.

1 Login as cpanel user (on page 67) to the CP server.

2 Create a resource class:

package psoft.hsphere.resource;
import java.util.*;
import psoft.hsphere.*;
public class MyResource extends Resource implements
HostDependentResource {
public MyResource(int type, Collection init) throws Exception
{
super(type, init);
}

public MyResource(ResourceId rid) throws Exception {
super(rid);
}

/*In this case the resource can be moved to any host*/
public boolean canBeMovedTo(long newHostId) throws Exception {
return true;
}

/* This method is started when the resource is created */
public void initDone() throws Exception {
physicalCreate(Long.parseLong(recursiveGet(“host_id”).toString
()));
}

/*

• Deletes persistant representation of the resource as well
as its system/physical representation

• @throws Exception
*/
public void delete() throws Exception {