Parallels H-Sphere Documentation System Administrator Guide

 

H-Sphere 3.0 Update and Installation

 
 

Related Docs:   H-Sphere Updater hsphere-info (HS 2.5+)

Last modified: 26 Aug 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.

In H-Sphere 3.0, H-Sphere installation and update is performed by a common script. This script brings about more flexibility in the process of installation, update and post-configuration, and introduces a variety of advanced features and improvements.

Before running H-Sphere updater/installer:

  1. Download the install/update script - it is actually located and run in a similar way as the update script in lower versions. For example, for H-Sphere 3.0 RC4 run under root on Linux box:

    # wget http://www.psoft.net/shiv/HS/releases/U30.0/U30.0RC4/U30.0RC4

  2. Run script with corresponding option:
    • To update H-Sphere, run the script in the update mode:
    • # sh U30.0RC4 update

      You will get the list of update modes, each having its own options.

    • To install H-Sphere, run the script in the install mode:
    • # sh U30.0RC4 install

      You will get the list of installation modes, each having its own options.

    • If you run:
    • # sh U30.0RC4

      the script will choose to update or install, according to what is available on the server:

      • CP Unix user cpanel
      • the hsphere.properties file
      • consistent H-Sphere system PostgreSQL database
      • H-Sphere related software (if user ran updater mistakenly on a non-CP box)

Important: It is highly recommended to run script with specified update or install mode.

 

Update Modes and Options

After running the script with update mode, you will get the below menu with the choice of update options:

==========================================================================
                               UPDATE
==========================================================================
 (1) hsupdate    -- update H-Sphere cluster, except SiteStudio.
                    (for more details, type '1').
==========================================================================
 (2) update      -- update H-Sphere cluster including SiteStudio.
                    (for more details, type '2').
==========================================================================
 (3) sitestudio  -- update SiteStudio on the Control Panel box.
                    (for more details, type '3').
==========================================================================
 (4) cpupdate    -- update H-Sphere core and related packages only.
                    (for more details, type '4').
==========================================================================
 (5) deploy      -- H-Sphere cluster post-update configuration.
                    (for more details, type '5').
==========================================================================
 (6) hspackages  -- H-Sphere cluster update in custom mode; additional
                    update options (forming custom configuration files,
                    maintaining exclude package lists, skipping CP update,
                    etc.)
                    (for more details, type '6').
==========================================================================
 (7) 3rdpackages -- install missing files for H-Sphere 'hsp'
                    packages on physical boxes.
                    (for more details, type '7').
==========================================================================
 (8) revert      -- downgrade packages to previous versions.
                    (for more details, type '8').
==========================================================================

If you want more info on every mode, simply type its number in the command line.

Update modes:

  • hsupdate - common H-Sphere update, excluding system postgres and SiteStudio.

    Options:

    hsupdate          [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]
                      [ private ] [ strict ] [ nomd5 ] [ force ] [ skip=stage ] [ url=Link ]
                      [ mirror=mirror_number ]
  • update - H-Sphere update, including system postgres and SiteStudio.

    Options:

    update           [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]
                     [ private ] [ strict ] [ nomd5 ] [ force ] [ skip=stage ] [ url=Link ]
                     [ mirror=mirror_number ]
  • sitestudio - SiteStudio update.

    Options:

    sitestudio       [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ] [ url=Link ]
                     [ mirror=mirror_number ]
  • cpupdate - update only Control Panel packages, templates, jars, etc.

    Options:

    cpupdate         [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ] [ url=Link ] [ mirror=mirror_number ]
  • deploy - the so-called "deploy" mode is run after all the system packages are installed/updated. In the deploy mode H-Sphere updater downloads and installs post-configuration scripts that perform general H-Sphere post-install/post-update configuration. H-Sphere install/update script runs in the deploy mode to complete Single Server Edition H-Sphere installation in the the postsingle mode.

    Options:

    deploy           [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]
                     [ private ] [ strict ] [ nomd5 ] [ force ] [ skip=stage ] [ url=Link ] [ mirror=mirror_number ]
  • hspackages - advanced mode to update H-Sphere related packages across H-Sphere cluster.

    Options:

    hspackages         [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]
                       [ private ] [ strict ] [ nomd5 ] [ force ] [ skip=stage ]
                       [ reconfig=front-end|spamassassin|all ]
                       [ mode=modename ] [ oscode ] [ mirror=mirror_number ]
                       [ exclude=[show|add:pattern1,...|del:pattern1,...|del:all] |
                       exclude-mysql=show|add|del | exclude-postgresql=show|add|del | exclude-dns=show|add|del ]
                       [ sitestudio ] [ postgres ] [ url=Link ] [ verbose ]
                       [ ctemplates=php,httpd,ftpd,mysql,pgsql,httpdcp,named ]
                       [ edit=IP:/path/to/custom/template ] [ skip-exclude ]
                       [ old-platform ]

    Read more about hspackages options.

  • 3rdpackages - install missing files for H-Sphere 'hsp' packages on physical boxes.

    3rdpackages       [ help ] 

    This is a long term operation. To examine the output of the script use tail -f logfile command.

  • revert - downgrade packages to previous versions. (More..)
  • Options:

    revert pkgs=[ list | package_name,package_name2,.. ] [ help ]

Options description:

  • ips - only specific list of the target boxes from HS cluster may be pointed instead of provide check update for all IPs in HS cluster;
  • group - the list of logical server groups, separated by comma. Possible groups: mail, web, dns, mysql, pgsql, cp, vps (using common ips and group tags is allowed).
  • private - private update for testing purpose.
  • strict - form package list based exclusively on package list. By default, downgrade to older package version is skipped.
  • nomd5 - update is not critical for wrong md5 sum, only warning;
  • force - check md5 sum of the installed packages with the same version too, if wrong md5 sum, install new package by force;
  • skip=[check|preparing]
    • check - skip check-up and regeneration of the existing updater.
    • preparing - skip config.xml regeneration on boxes during update.
  • reconfig=front-end|spamassassin|all (3.0 RC4+) - this option is used in the case of front-end (Horde, PhpMyAdmin, PhpPgAdmin) or SpamAssassin DB location redefinition. It provides the list of boxes allocation where update and/or related reconfiguration is required.
  • mode=[hsupdate|update|ipmigration|deploy] (in HS 3.0+) - set update mode with one of the options:
    • hsupdate - common update without postgres and sitestudio;
    • update - hsupdate including postgres and sitestudio;
    • ipmigration - reconfiguring IP dependent information;
    • deploy - deploy mode (post-install general box reconfiguration).
  • oscode - shows OS code of each box during update preparation.
  • mirror (HS 3.0+) - allow to set another mirror instead of the default one. At this moment available are the following HS servers:
    N  Host             Location   Status
    --------------------------------------
    0  psoft.net        (USA)      default
    1  mirror.psoft.net (Europe)
    
  • (3.0 RC4+) exclude-mysql=show|add|del | exclude-postgresql=show|add|del | exclude-dns=show|add|del - you can configure H-Sphere to use custom PostgreSQL/MySQL versions instead of installing their HS 3.0 default versions. In this case HS updater allows excluding related package from the H-Sphere update leaving the possibility to update them via native system package managers. Example:

    hspackages exclude-mysql=add ips=192.168.1.10

    (NEW HS 3.1+) the exclude-dns= option allows to exclude standard Bind server in order to use MyDNS server or other custom DNS servers (like djbdns) instead.

  • skip-exclude (HS 3.0 Patch 1+) - skip pre-configured exclude package list during current update. Skip pre-defined exclude list that was previously set via exclude
  • exclude=[show|add:pattern1,pattern2,...|del:pattern1,pattern2,...|del:all |] (Note: absent in HS 3.1+) - show, set or delete list of the package patterns to be skipped during update on all or specified list of H-Sphere boxes.
    Explanation:
    hspackages exclude=add:hsphere-php - adds hsphere-php pattern (case insensitive) to an exclude list that is permanently stored in a file on a server. This command does not perform the update
    hspackages exclude=show - shows the exclude list from the file stored on the server
    hspackages exclude=del:hsphere-php - removes the hsphere-php pattern from the exclude list and doesn't update the package
    hspackages exclude=del:all - clears the whole exclude list
    To include the list, run:

    hspackages

    The path to the exclude list stored on the server is /hsphere/shared/etc/excludepkglist
    Pattern - the whole word or a part of a word (case insensitive), e.g. pattern hspackages exclude=add:php excludes all php packages: phpMyAdmin, phpPgAdmin, etc.
    Examples:

    hspackages exclude=add:hsphere-bind ips=192.168.1.10
    hspackages exclude=add:mysql-server ips=192.168.1.10

    * Use this carefully, as H-Sphere packages have direct correlation with H-Sphere version. This may be used in the the following cases: 1) You have customized version of the specific H-Spshere package; or 2) you update system packages, like MySQL server via native OS package manager, etc.
  • sitestudio - update SiteStudio to last supported version.
  • postgres - update postgressql to the last supported version.
  • url=Link - alternative path for package download (instead of http://www.psoft.net/shiv/HS);
  • verbose - inform whether package was installed by force or with nodeps;
  • ctemplates=php,httpd,httpd2,cphttpd,httpd_extra,httpd2_extra,cphttpd_extra,ftpd,mysql,pgsql,named - Place custom config file templates for comma-separated list of services into predefined locations if custom templates are not there already.

    (NEW HS 3.1+) the httpd_extra, httpd2_extra, and cphttpd_extra options are used to customize some extra config files respectively for Web server's Apache 1.x and 2.x and for CP Apache. Also the httpd2 option is introduced for Apache 2.2.

  • edit=IP:/path/to/custom/template - Edit custom config file template on a specified server in a specified location.
  • old-platform (HS 3.0 Patch 1+) - this option allows to force install/update for the deprecated OS/soft listed in http://www.psoft.net/HSdocumentation/admin/eol.html.
  • subversion - there is global hsphere package list and its subversion differences.
  • help2 - get additional possibilities description.
  • This key allow to check only subversion check to speed up update (of course, update to corresponding hsphere version is required before);
  • slaves=web|mail|all (HS 3.0+) - choose this option to install/update packages on slave servers of load balanced Web/mail clusters.
  • help2 - get additional possibilities description.
  • This key allow to check only subversion check to speed up update (of course, update to corresponding hsphere version is required before);
  • pkgs=[ list | package_name1,package_name2,.. ] - revert (downgrade) packages separated by comma. For example: revert=hsphere-webmails,mysql,hsphere-mnogosearch
    Using pkgs=list will display the list of all packages you can downgrade. Choose from the list. (Read more about Downgrading Packages to the Previous Version.

 

Installation Options

After running the script with install mode, you will get the below menu with the choice of installation options:

======================================================================
                           H-SPHERE INSTALLATION
======================================================================
 (1) install     -- Full installation mode. Requires prepared
                    config.xml with H-Sphere cluster configuration.
                    (for more details, type '1').
======================================================================
 (2) cpinstall   -- Control Panel installation mode.
                    Afterwards, log into H-Sphere Control Panel
                    Web interface, go through Pre-Configuration
                    wizard, and then complete installation in mode (3).
                    (for more details, type '2').
======================================================================
 (3) postinstall -- post-installation H-Sphere cluster configuration,
                    to be run after mode (2).
                    (for more details, type '3').
======================================================================
 (4) sitestudio -- install SiteStudio on the Control Panel box.
                   (for more details, type '4').
======================================================================

If you want more info on every mode, simply type its number in the command line.

Install modes:

  • install - H-Sphere installation from the prepared config.xml file with configuration of H-Sphere cluster to be installed. config.xml contains information about H-Sphere physical and logical servers, with root passwords to physical server where H-Sphere is to be installed (see sample config.xml). During the installation this file is temporarily stored in the ~cpanel/.settings directory. You can also use the cpinstall mode and run H-Sphere Pre-Configuration Wizard in admin CP to create and import/export config.xml.

    install xml=CONFIG_XML [ skip-sitestudio ] [ url=Link ]
                           [ mirror=mirror_number ]
  • cpinstall - install only system PostgreSQL and packages to be able to run Control Panel. Later on, you need to log into admin CP and go through H-Sphere Pre-Configuration Wizard to shape your H-Sphere cluster, and finally, run the installer in the postinstall mode.

    cpinstall zone=SERVICE_ZONE ip=IP1 [ ip2=IP2 ]
              [ natip=NAT_IP ] [ mask=MASK ] [ url=Link ]
              [ mirror=mirror_number ]
  • postinstall - run this mode to complete H-Sphere installation after cpinstall and after adding servers and services in the H-Sphere Pre-Configuration mode in admin CP.

    postinstall

  • sitestudio - install SiteStudio on the Control Panel box.

    sitestudio  [ url=Link ] [ mirror=mirror_number ]

Where:

Obligatory parameters:
  • xml - the path to config.xml file. This path should not be /hsphere/shared/etc/config.xml
  • zone - service domain name (e.g., samplehosting.com).
  • ip - service zone IP - IP of Control Panel box.
Optional parameters:
  • ip2 - the IP of the second DNS logical server (ns2). If ip2 is not set, the ns2 logical server will not be created.
  • natip - the external server IP for NAT mapping.
  • mask - the network mask. If mask is not set, the default value (255.255.255.0) is used.
  • skip-sitestudio - install H-Sphere without SiteStudio.
  • group - comma-separated list of logical servers to be installed. Possible groups: mail, web, dns, mysql, pgsql, cp, vps (using common ips and group tags is allowed).
  • url - alternative path to package download, this option differs from 'mirror', which includes predefined list of the maintained HS mirrors. Package lists are downloaded from default location or mirror, pointed via mirror option. (Default path is http://www.psoft.net/shiv/HS)
  • mirror (in HS 3.0+)- allows setting another mirror instead of the default one. At this moment available the following HS servers: [0] - psoft.net (USA, default) and [1] - mirror.psoft.net (Europe).

Related Docs:   H-Sphere Updater hsphere-info (HS 2.5+)



© Copyright 2017. Parallels Holdings. All rights reserved.