Parallels H-Sphere Documentation System Administrator Guide


Preparing Servers for H-Sphere Installation


Related Docs:   Preparing Windows Boxes for H-Sphere Installation

Last modified: 11 Jan 2008


WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the official Parallels site.

The purpose of this document is to provide comprehensive information on how to prepare Linux and Unix servers for the installation of H-Sphere components by the Positive Software team or by customers themselves. It covers the following topics:

Please also read the following:

Note: We don't install H-Sphere on live servers and we don't take responsibility if your functional services go down during the H-Sphere installation.


Supported Operating Systems

Before requesting H-Sphere installation, make sure to install one of the following operating systems:

Operating System Supported OS Version Supported by H-Sphere*
RedHat Enterprise Linux 3.x, 4.x All supported H-Sphere versions
4.x (x86_64) Since 3.0 RC 1
5.x; 5.x (x86_64) Since 3.0 Patch 1
CentOS 3.x, 4.x All supported H-Sphere versions
4.x (x86_64) Since 3.0 RC 1
5.x; 5.x (x86_64) Since 3.0 Patch 1
White Box Enterprise Linux* 3.x, 4.x All supported H-Sphere versions
4.x Since 3.0 RC 1
FreeBSD* 5.5 H-Sphere 3.0 RC 1 and up for all servers, including CP server
H-Sphere 2.5.0 Patch 3 and up for all servers, except for CP server*
6.1 H-Sphere 3.0 RC 1 and up for all servers, including CP server
6.2 H-Sphere 3.0 RC 4 and up for all servers, including CP server

For supported Windows Server versions, refer to the Winbox Pre-installation guide.


  1. By supported Operating System we assume a 32-bit system, if not specified otherwise.
  2. H-Sphere versions before 2.5 are no longer supported! We only perform updates from these versions to the latest stable H-Sphere version.
  3. H-Sphere 2.4.3 support was terminated on 1 July 2007. H-Sphere 2.5 version is no longer supported since 1 October 2007. Please also be aware of other H-Sphere Services and Supported OS's EOL Dates.
  4. We claim H-Sphere support on WhiteBox OS, assuming it is a RedHat Enterprise Linux clone. However, PSoft does not test H-Sphere on WhiteBox servers.
  5. Starting with (H-Sphere 3.0 branch), native FreeBSD java diablo support is added to allow CP server installation on FreeBSD 5.x and 6.x.
  6. If you are installing H-Sphere control panel on a FreeBSD box, especially in case of multiprocessor architecture, make sure you have the /etc/libmap.conf file with the following content.
  7. CP installed on a server with 64-bit operating system requires glibc 32-bit compatibility library

You may also want to read a related discussion in our forum.


Hardware Requirements

If you are going to install H-Sphere to only one computer, make sure it is at least Pentium III, 500MHz CPU and 512MB RAM. This will allow to host only a small number of customers. Adding SiteStudio will require at least 1000MHz CPU and 1GB RAM.


Single-Server and Multi-Server Installation


General Considerations

H-Sphere can be installed on one or more servers. The required number of servers and their hardware configuration will largely depend on the number of accounts you are planning to host, Web and mail quotas, traffic load and other related factors.

Here are some general considerations common to H-Sphere server environment:

  1. We recommend installing Control Panel (CP) to a separate server. It is also acceptable to install one DNS server to the CP server box, for example, if you are planning 2-server installation.
  2. You must not install PostgreSQL hosting service on the same box with Control Panel, as the latter requires a separate PostgreSQL server for its system database.
  3. You can have several DNS servers on one box. However, for multiserver H-Sphere installation, you should install each DNS server on a separate box. The best solution is to have two DNS servers on separate boxes. More on DNS servers
  4. We advise installing mail server on the same box with MySQL server, as mail server requires its own MySQL database.
  5. It is reasonable to allocate separate physical servers for the most resource-consuming services. Usually, these are Web and mail servers, but sometimes it may be MySQL and PostgreSQL.

According to these recommendations, the following 4-server installation may be an optimal solution:

  • Server 1: Control Panel (with the system PostgreSQL database);
  • Server 2: Web1 + DNS1;
  • Server 3: Mail + MySQL1 (user DB) + DNS2;
  • Server 4: PostgreSQL (user DB) + MySQL2 (user DB).

Later on, you may add more boxes to your system, as your needs grow:

  • Server 5: Web2;
  • Server 6: Mail2 (with its own MySQL DB);


See the illustration chart of multi-server installation.


Sample 1/2/3-Server Configurations

Below are sample 1/2/3-server H-Sphere installations with preferable partitioning schemes outlined.

One Server Installation Two Server Installation Three Server Installation

Single-server installation includes Control Panel, DNS, Web, mail, and MySQL services. The PostgreSQL hosting service isn't included because of the H-Sphere system PostgreSQL database.

Make sure you have at least two IPs available, because some features (like OpenSRS) require at least two DNS servers. More on Single DNS



/ root partition (/etc, /tmp, /root) - 1-3 GB
/usr - 3-5 GB
/var - 5-7 GB for mail and MySQL files
/hsphere (or /home - see HDD Partitioning) - the remaining disk space for H-Sphere installation and Web hosting.


/ root partition (/etc, /tmp, /root) - 2-6 GB
/usr - 6-10 GB
/var - 10-15 GB for mail and MySQL files
/hsphere (or /home - see HDD Partitioning) - the remaining disk space for H-Sphere installation and Web hosting.

120+ GB HDD:

/ root partition (/etc, /tmp, /root) - 3-10 GB
/usr - 10-20 GB
/var - 15-30 GB for mail and MySQL files
/hsphere (or /home - see HDD Partitioning) - the remaining disk space for H-Sphere installation and Web hosting.

The more users you are planning to have, the more disk space is required. If you want to have SiteStudio, it will also be installed onto this partition. However, this will require at least 512 RAM and a 500MHz processor.

In addition, you can create a separate mail partition for the H-Sphere mail system. Its size will depend on your mail quotas for users and the number of mailboxes. See illustration

Consider the following partitioning scheme for the two-server configuration:

1) Control Panel + DNS2:

The partitioning requirements are similar to those for one server installation. This box will have the H-Sphere control panel, the system database, DNS server, and SiteStudio (optional).

2) Web + Mail + MySQL + PostgreSQL + DNS1:

/ - 1-3 GB
/usr -3-5 GB
/var - 5-7 GB for mail and MySQL files.
/hsphere - takes the rest of the space for Web content and is the biggest partition. See illustration

Consider the following partitioning scheme for a three-server configuration:

1) Control Panel

The partitioning requirements are the similar to those for the one server installation. This box will have the H-Sphere control panel, the system database, and SiteStudio (optional).

2) Web + DNS2:

/ - 1-3 GB
/usr - 3-5 GB
/var -3-5 GB
/hsphere - takes the rest of the space and is the biggest partition.

3) Mail + DNS1 + MySQL + PostgreSQL:

/ - 1-3 GB
/usr - 3-5 GB
/var - takes the rest of the space for mail and MySQL files.

See illustration


HDD Partitioning

H-Sphere is installed to the /hsphere directory.

We recommend dedicating a separate partition for the H-Sphere installation directory and mount it as /hsphere.

# mkdir -p /hsphere
# chmod 755 /hsphere

H-Sphere directory can be located on any other partition as well. However, we do not recommend installing H-Sphere to the root / partition. Having H-Sphere on the root partition may cause certain problems. For instance, if disk quota gets damaged, you cannot repair it without server reboot and fsck check in the single user mode.

If your H-Sphere installation directory is to be located on another partition, for example, /usr/hsphere on the /usr partition, the /hsphere symlink to this directory must be anyway created:

# mkdir -p /usr/hsphere
# ln -s /usr/hsphere /hsphere
# chmod 755 /usr/hsphere

Important: Do not create /hsphere as a symlink to another partition on servers with FreeBSD 5.3 and up! Allocate the separate /hsphere partition instead! If this is impossible, use nullfs partitioning for this purpose.

There are no more requirements to partitioning the servers, just make sure there is enough disk space to store user and other H-Sphere data.


Required Components and Configuration

Prior to the installation, make sure your server has the following:


  1. Install OpenSSH package on each H-Sphere box. You can use standard RPMs under Linux or packages under FreeBSD. Usually, the standard Linux and FreeBSD installations contain the OpenSSH package, you can use it without any restrictions. However, we recommend to update the package to the last version. SSH keys need to be configured under the cpanel user.
  2. To enable Permit Root Login, open file /etc/ssh/sshd_config and uncomment the line:
    PermitRootLogin yes
    Make sure PermitRootLogin is set to yes. Then restart SSH:
    • for Linux:
      /etc/init.d/sshd restart
    • for FreeBSD 4.x:
      kill -HUP `ps ax | grep sshd | grep -v grep | grep -v tty | awk '{print $1}'`
    • for FreeBSD 5.x:
      /etc/rc.d/sshd restart
  3. Enable the OpenSSH daemon start at server startup.
  4. Start the OpenSSH daemon.



We strongly recommend using typical Linux/FreeBSD kernel (i.e., coming with official OS distributives or updates). In particular, in case of FreeBSD we instist on GENERIC kernel with basic configuration. We do not guarantee correct H-Sphere work on a server with customized kernel! Please carefully test H-Sphere functionality on such a server before it becomes a production server!

Disk Quota

Enable the disk quota feature on each H-Sphere Web server. There is no need to enable it on other servers.

To enable disk quota:

  1. Log in as root.
  2. Insert the usrquota directive (userquota for FreeBSD) into the /etc/fstab file for the corresponding partition.
    On Linux, it must look similar to this:
    LABEL=/hsphere   /hsphere   ext2   defaults,usrquota   1 1
    On FreeBSD, it must look similar to this:
    LABEL=/hsphere   /hsphere ufs rw,userquota 2 2
  3. Execute the following commands:
    quotaoff /partition_with_userquota_enabled
    mount -o remount /partition_with_userquota_enabled (Linux only, skip this line with FreeBSD)
    rm -rf /partition_with_userquota_enabled/aquota.user /partition_with_userquota_enabled/quota.user
    quotacheck -mufv /partition_with_userquota_enabled(Linux)
    quotacheck -guv /partition_with_userquota_enabled(FreeBSD)
    quotaon /partition_with_userquota_enabled
    [-] If quotacheck returns the error: quotacheck: Cannot get quotafile name for /dev/xxx
    Do the following:
    1) # touch /partition_with_userquota_enabled/aquota.user
    2) # quotacheck -m /partition_with_userquota_enabled
    and ignore the message:
    "quotacheck: WARNING - Quotafile /partition_with_userquota_enabled/aquota.user was probably truncated. Can't save quota settings..."
    3) quotaon /partition_with_userquota_enabled
  4. FreeBSD Web server installations: Enable disk quota in the kernel configuration. Also, in /etc/default/rc.conf set:

Root Partitions: we don't recommend enabling the disk quota feature on root partitions. Use other partitions for this! Therefore, we advise not to place H-Sphere files on the root partition.

Quotacheck: quota versions can have some differences on different OSs. You may need to execute the quotacheck command with some additional parameters. Please read the command manual before performing this action.

Ports (Firewall Configuration)

In your firewall settings, open the following ports in both directions and specify the connection type - tcp or udp or both.
We need that firewall be configured by our customers.

[-] Pix firewall note
Pix firewall doesn't work correctly with H-Sphere and SiteStudio, because it doesn't allow servers within one H-Sphere cluster to communicate by external IPs, which is critical for both products.

Port Usage CP Server Web Server Mail Server DNS Server MySQL Server PGSQL Server Real Server Windows Server MS SQL Server MPS Server MRTG Server
20 FTP-DATA tcp tcp           tcp      
21 FTP tcp tcp           tcp      
22 SSH* tcp tcp tcp tcp tcp tcp tcp        
25 SMTP     tcp         tcp      
53 DNS udp udp udp tcp and udp ** udp udp udp udp udp    
80 HTTP   tcp tcp   tcp tcp tcp tcp tcp tcp tcp
110 POP     tcp                
143 IMAP     tcp                
144 IMAP proxy     tcp (localhost only)                
443 HTTPS tcp tcp           tcp     tcp
465*** Mail SSL     tcp                
587 submission     tcp                
873 RSYNC tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers tcp between H-Sphere servers    
953 RNDC       tcp and udp**              
993*** Mail SSL     tcp                
995*** Mail SSL     tcp                
1433 MS SQL               tcp tcp    
1922 IMAGEMAKER tcp (localhost only)                    
3306 MySQL tcp to all MySQL servers       tcp     tcp      
3389 Terminal Service               tcp tcp    
5432 Postgres tcp (CP only)         tcp   tcp      
5631 pcAnywhere               tcp (optional) tcp (optional)    
8009 Tomcat tcp (CP only)                    
8080 HTTP tcp                    
8443 SSL tcp                    
55000 OpenSRS tcp (if used)                    
10125 SOAP

SOAP (hide)

SOAP (Simple Object Access Protocol) serves data communication between Control panel and Windows servers.

tcp between H-Sphere servers             tcp tcp    

*For those requesting PSoft support, make sure your firewall settings allow SSH connection to PSoft IPs.

**For highest security, open:
  - udp permanently;
  - tcp worldwide during H-Sphere installation and post-installation tests;
  - tcp between H-Sphere DNS servers permanently.

***Open these ports only if you want to use Mail SSL.

Note: In the above table, all ports should be opened for external connections unless specified otherwise (for example, "tcp between H-Sphere servers").

DNS Server Notes:

1. Port 953 (rndc) should be open for localhost only if your DNS server is using BIND 9.x.

2. If your DNS server is using BIND 8.x, it can be upgraded to run with H-Sphere, but old domains would still have to be managed by hand. Please agree your DNS server upgrade with our installation team.
* As of now we don't provide support for Reverse DNS configuration.


H-Sphere installation script is written in Perl, therefore Perl is required on each box. To check if Perl is installed, run:

perl -V

Caution: Do not update or change any configuration to your system Perl, as it will most likely damage your H-Sphere installation.

See the list of supported Perl versions per OS.


Make sure the make utility is installed on every box. To check if make is installed, run:

make -v

Command-Line URL Download Utility (wget or fetch)

H-Sphere installation script requires the command-line URL download utility, wget for Linux, fetch for FreeBSD.

compat3x package

On FreeBSD 4.X servers, make sure to have the compat3x package installed for compatibility with 3.x. To diagnose if your compat3x is missing, run:


and then go to Configure -> Distributions


SELinux Must Be Off

(RedHat Enterprise Linux 4, CentOS 4 and up, and White Box Enterprise Linux 4 only)

Before H-Sphere installation, make sure SELinux is off on your Linux servers.

To check SELinux status, run:

selinuxenabled && echo $?

If as a result of this command you receive 0, SELinux is enabled. No result means that SELinux is off.

To disable SELinux, set the following option in /etc/selinux/config:


This will turn off SELinux after reboot. To disable SELinux immediately, type:

setenforce 0

Now that you have prepared the servers, you can proceed to H-Sphere installation or request installation by Psoft.

Related Docs:   Preparing Windows Boxes for H-Sphere Installation

© Copyright 2017. Parallels Holdings. All rights reserved.