H-Sphere Versions

For more information contact us

Updating H-Sphere to 2.5 Patch 6

09 Oct 2006


Release Notes  |     Install  |     Winbox Install  |     Winbox Update  |     Change Log  |     Package List

This H-Sphere version is outdated and is not supported. Please refer to latest supported versions.

This document explains how to upgrade H-Sphere to 2.5 Patch 6 from H-Sphere 2.4.3 Patch 11 and up. If you have a lower version, please upgrade to 2.4.3 Patch 11 first.



Consider this before you update H-Sphere:

  • The upgrade won't work without a valid H-Sphere license to cover all accounts in the system!

  • Please refer to the list of operating systems supported by H-Sphere.

    1. Update to H-Sphere 2.5 and up is not recommended for H-Sphere clusters with CP servers under FreeBSD 4.x up to FreeBSD 4.9, as these FreeBSD versions do not fully support Java 1.5.
    2. H-Sphere Winbox versions earlier than 2.5 won't work correctly with H-Sphere 2.5 Beta 2 and up! In the same way, Winbox 2.5 Beta 2 and up won't work with H-Sphere under 2.5!
    3. Serv-U FTP is no longer supported in H-Sphere Winbox 2.5 and up. If you are currently using it and would like to update to this version, first switch to MS FTP.
    4. We currently don't recommend updating H-Sphere to version 2.5 and up when there are 512 and more ColdFusion mappings on a Windows server (i.e., ColdFusion is turned on for more than 511 Winbox users)
  • In H-Sphere 2.5 and up, it is required to customize server configuration files indirectly via respective template files. All custom changes in major default configuration files for Apache, FTP, PHP, DNS, MySQL, and PostgreSQL are removed with each update! Please carefully follow this update instruction to customize config file templates!

  • If you have CP installed on a FreeBSD box, especially in case of multiprocessor architecture, please make sure you have the /etc/libmap.conf file on the CP box with this content.

  • Update on boxes with FreeBSD 5.3 and up will halt if the /hsphere directory is a symlink! Please re-partition your servers' HDD to move H-Sphere content to the /hsphere directory before you proceed with the update. Please refer to Preparing Servers: HDD Partitioning.

  • If you have a mail server running on the same box as the CP server, and CP server uses port 80, change CP port to 8080 in /hsphere/local/home/cpanel/apache/conf/httpd.conf or contact H-Sphere support.

  • In H-Sphere 2.4.3 RC 1 and up, custom server groups for name (DNS) logical servers are no longer supported! If you are upgrading from an earlier version, please remove all custom name server groups (including all respective logical/physical servers). Please refer to Server Groups for details.

  • MySQL Updates.
  • Make sure that port 144 (localhost:144) is opened on all mailboxes.

  • If you are installing H-Sphere control panel on FreeBSD box running on multiprocessor computer architecture, create /etc/libmap.conf file. More in Preparing Servers for H-Sphere Installation.



  1. Make sure you have H-Sphere 2.4.3 Patch 11 or higher installed:
    # cat ~cpanel/shiva/psoft_config/hsphere.properties | grep HS_VERSION
    If you have an older version, update to H-Sphere 2.4.3 Patch 11 first and run a separate PostgreSQL update script to update PostgreSQL to 7.4.x version.
  2. Download the 2.5 Patch 6 upgrade package:
    # wget http://www.psoft.net/shiv/HS/releases/U25.0/U25.0P6/U25.0P6
    # fetch http://www.psoft.net/shiv/HS/releases/U25.0/U25.0P6/U25.0P6
  3. Make sure that permissions to /usr/bin/wget are set to 0755 during the installation.
  4. Stop H-Sphere using one of the following commands:
    # /etc/rc.d/init.d/httpdcp stop
    # /usr/local/etc/rc.d/apachecp.sh stop
    Stop SiteStudio ImageMaker by running:
    # /hsphere/shared/SiteStudio/imaker.sh stop
  5. Run the update script:
    # sh ./U25.0P6

    You will see a help window with a prompt to enter update options.

  6. Update H-Sphere.
    • If one of the following conditions is met:

      1. if you have customized versions of H-Sphere *nix packages or other system packages that you update via native OS package manager;
      2. if your default config files (Apache, PHP, mail, FTP, databases) are customized not by means of config file templates;

      H-Sphere update will be as follows:

      1. Update H-Sphere core (templates, classes, jars):


      2. In case a, exclude respective packages from being updated by the H-Sphere update script. To do this, type:

        hspackages [ ips=<IP1>,<IP2>,...<IPN>] exclude=add:<pattern1>,<pattern2>,...<patternN> skip=preparing

        Here, <IPx> are physical server IPs, and <patternx> are packages to exclude. For detailed syntax see command line interface of the H-Sphere Updater wrapper.

        To make sure you have successfully excluded the packages, run:

        hspackages [ ips=<IP1>,<IP2>,...<IPN>] exclude=show skip=preparing

        Warning: Please be very careful in excluding the packages from the update list! You must have serious reasons to do this!

      3. In case b, type the following command to create default config file templates to be customized afterwards:

        hspackages ctemplates=php,httpd,ftpd,mysql,pgsql

        For syntax and details please thoroughly read about customizing config files by means of templates.

        Important: This command will create default config file templates in respective directories. After that, you should customize them according to the custom configuration you had before. Typical reasons for such customization may be the use of Zend Optimizer, ChiliASP, ColdFusion Apache modules, etc.

      4. Update H-Sphere related packages:


    • Otherwise, if neither a or b is met:

      • to update H-Sphere and Site Studio, type:


      • to update only H-Sphere, enter:


      • to update only Site Studio, enter:


    Note: After the update, you'll be able to add more servers or services to the cluster by following the Adding Servers and Services documentation.

  7. Update PostgreSQL:
    hspackages postgres
  8. Upgrade your Winbox to 2.5 Patch 6.
  9. H-Sphere update script will automatically launch H-Sphere CP after the update. Check if H-Sphere is running, and if not, start CP Apache:
    # /etc/rc.d/init.d/httpdcp start
    # /usr/local/etc/rc.d/apachecp.sh start
  10. Start ImageMaker if your H-Sphere is integrated with SiteStudio, for Linux & FreeBSD:
    # /hsphere/shared/SiteStudio/imaker.sh start
  11. Check the version of H-Sphere by executing the following command on your CP box:
    # cat ~cpanel/shiva/psoft_config/hsphere.properties | grep HS_VERSION

    You will see a line similar to this:

    2.5.0 is the version of H-Sphere,
    720 is the H-Sphere build.


Post-Update Issues

After you have updated H-Sphere, please make sure you meet the following requirements:

  • Winbox Update. Don't forget to upgrade Winbox to 2.5 Patch 6 if you haven't done this yet.

  • Customization. If you have custom H-Sphere templates, you may probably need to update them according to changes introduced in this version.
    Starting with HS 2.5 Beta 1, the check! client-side validation attribute is no longer supported in the input and textarea tags. Please update your custom templates with the check="${validation_variable}" construction everywhere instead of check!, where ${validation_variable} is a Freemarker variable which is evaluated to the real name of a validation function (regexp) during the template processing.

  • Ownership. In H-Sphere 2.5 RC 3 and up HTML pages, images, Javascript and CSS files and respective directories have cpanel:httpdcp ownership. H-Sphere updater checks and automatically sets correct ownership and permissions on respective default and custom files and directories. Please make sure however that newly created custom files have correct ownership and permissions (this does not relate to H-Sphere packages).

  • Web Payments. If you are updating from H-Sphere versions earlier than 2.5 Beta 1, please update the format of instant payment notification URL in affected Web payment systems' settings.

  • Web traffic calculation and log rotation. H-Sphere 2.5 Beta 1 and up introduces a completely different approach in Web traffic calculation and log rotation. Now it takes into account both incoming and outgoing traffic. Therefore, after you upgrade from versions earlier than 2.5 Beta 1, your clients may find their traffic increased.

  • VPS.

    1. If you host VPS on your H-Sphere and update from version 2.4.x to 2.5 and up, you must run the VPS converter tool with the --all option to convert all VPS plans and accounts to comply with VPS resource implementation in H-Sphere 2.5 and up.
    2. After you have updated H-Sphere, please also make sure you run Steps 3-9 of the H-Sphere VPS update instruction.
  • IMP Horde (Webmail). (HS 2.5 Patch 1+ or 2.4.3 Patch 12+) After package update make sure to migrate your Horde histories data into a separate table, located in Horde database (introduced in a new Horde version).

  • DBD::mysql Perl driver. (HS 2.5 Patch 1+) If you want to update DBD::mysql driver or system Perl version, make sure to execute the script that updates DBD::mysql driver.

  • DNS Zone Duplication. (Update from H-Sphere 2.4.x to 2.5 and up) If during the H-Sphere update DNS zone duplication takes place, Bind update from 8.x to 9.3.x will be skipped. Then, after the H-Sphere update is over, you need to resolve the DNS zone duplication problem, run the updater again and choose the hspackages option in the update script to update Bind.

  • Update MySQL v. 4.0 to 4.1 (HS 2.5 Patch 3+ or HS 2.5.1 Beta 2+) If your clients created databases/tables/fields in the tables with specific charset, please refer to the following documentation:
    - Character set upgrade
    - Connection Character Sets and Collations

  • Set up Kronolith Reminders (HS 2.5 Patch 3+ or HS 2.5.1 Beta 2+) If you use Kronolith reminders, make sure to set up them.

  • Starting with version 2.5 Patch 6 bayes_sql_override_username Spam Assassin parameter in local.cf is set by default. If you have tables starting with bayes_*, make sure to empty their content.

Copyright 1998-2018. Positive Software Corporation.
All rights reserved.