H-Sphere Sysadmin Guide

H-Sphere 2.5.1 Update and Installation

(2.5.1 Beta 2 and up)

Starting with H-Sphere 2.5.1 beta 2, 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:

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 2.5.1 Beta 2 run under root on Linux box:
# wget http://www.psoft.net/shiv/HS/releases/U25.1/U25.1b2/U25.1b2
Run script with corresponding option:
To update H-Sphere, run the script in the update mode:

# sh U25.1b2 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 U25.1b2 install

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

If you run:

# sh U25.1b2

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 ]

update - H-Sphere update, including system postgres and SiteStudio.

Options:

update           [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]
                 [ private ] [ strict ] [ nomd5 ] [ force ] [ skip=stage ]

sitestudio - SiteStudio update.

Options:

sitestudio       [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]

cpupdate - update only Control Panel packages, templates, jars, etc.

Options:
```
cpupdate         [ help ] [ ips=IP1,IP2,.. ] [ group=lgroup1,lgroup2,... ]
```
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 ]
```

hspackages - advanced mode to update H-Sphere related packages across H-Sphere cluster.

Options:

hspackages        [ help ] [ nomd5 ] [ force ] [ ips=IP1,IP2,.. ] [ subversion ]
                  [ help2 ] [ url=Link ] [ verbose ] [ skip=[check|preparing] ]
                  [ mode=[hsupdate|update|ipmigration|deploy] ]
                  [ exclude=[show|add:pattern1,pattern2,...|del:pattern1,pattern2,...|del:all ]]
                  [ strict ] [ sitestudio ] [ postgres ] [ private ]
                  [ ctemplates=php,httpd,ftpd,mysql,pgsql ]
                  [ edit=IP:/path/to/custom/template ]
                  [ group=lgroup1,lgroup2,... ]

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:

mode=[hsupdate|update|ipmigration|deploy] - choose in whichever update mode to update packages.
ips - specify comma-separated list of target boxes' IPs the update will be resricted to;
group - specify the list of comma-separated logical server groups to be affected by the update. Possible groups: mail, web, dns, mysql, pgsql, cp, vps (using common ips and group tags is allowed).
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;
strict - form package list based exclusively on package list. By default, downgrade to older package version is skipped.
subversion - there is global hsphere package list and its subversion differences.
help2 - get additional possibilities description.
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;
exclude=[show|add:pattern1,pattern2,...|del:pattern1,pattern2,...|del:all] - show, set or delete list of the package patterns to be skipped during update on all or specified list of H-Sphere boxes.
For example, to exclude hsphere-info-1-1 from the update on the 192.168.1.10 box, execute:
hspackages exclude=add:hsphere-info ips=192.168.1.10
i.e. package version must be left out.
* 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-Sphere package.
2. You update system packages, like MySQL server via native OS package manager, etc.
skip=[check|preparing]
- check - skip check-up and regeneration of the existing updater.
- preparing - skip config.xml regeneration on boxes during update.
sitestudio - update SiteStudio to last supported version.
postgres - update postgressql to the last supported version.
private - private update for testing purpose.
ctemplates=php,httpd,ftpd,mysql,pgsql - Place custom config file templates for comma-separated list of services into predefined locations if custom templates are not there already.
edit=IP:/path/to/custom/template - Edit custom config file template on a specified server in a specified location.
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 update 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').
======================================================================

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.

Options:
```
install xml=CONFIG_XML [ skip-sitestudio ]
```
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.

Options:
```
cpinstall  zone=SERVICE_ZONE ip=IP1
           [ ip2=IP2 ] [ natip=NAT_IP ] [ mask=MASK ]
```
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

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).