Parallels H-Sphere - 3.1 Upgrade Guide

Parallels®

Legal and Copyright Notice

ISBN: N/A
Parallels
660 SW 39th Street
Suite 205
Renton, Washington 98057
USA
Phone: [phone]
Fax: [phone]

© Copyright 2008,
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

Typographical Conventions ........................................................................................................... 5

Feedback ....................................................................................................................................... 6

About This Guide 7

Preparing for Upgrading Parallels H-Sphere 8

Upgrading Parallels H-Sphere 10

Step 1. Creating Update Profiles for Physical Servers ................................................................ 11

hsphere-update Package Reference ................................................................................ 13

Step 2. Updating Parallels H-Sphere Control Panel Core ........................................................... 14

Step 3. Updating H-Sphere Windows HsCore MSI Package ...................................................... 15

Windows HsCore Update Procedure ................................................................................ 16

Step 4. Updating Physical Boxes ................................................................................................ 17

Option 1. Updating Physical Boxes from the Interface ..................................................... 17

Option 2. Updating Physical Boxes from Command Line ................................................. 18

Step 5. Updating PostgreSQL ..................................................................................................... 26

Step 6. Starting Control Panel Apache ........................................................................................ 27

Step 7. Starting ImageMaker ....................................................................................................... 27

Step 8. Checking the Version of Parallels H-Sphere ................................................................... 27

Post-Upgrade Issues 28

Appendix A. Supported Operating Systems 29

Appendix B. HDD Partitioning 30

Appendix C. Customizing Server Configuration Files By Means of Templates 31

CP Apache ................................................................................................................................... 34

Extra CP Apache Configs ............................................................................................................ 35

Apache ......................................................................................................................................... 36

Customizing /hsphere/shared/apache/htdocs/index.html ................................................. 36

Extra Apache Configs .................................................................................................................. 37

PHP 4 .......................................................................................................................................... 38

PHP 5 .......................................................................................................................................... 39

FTP .............................................................................................................................................. 40

MySQL ......................................................................................................................................... 41

PostgreSQL ................................................................................................................................. 41

DNS ............................................................................................................................................. 42

etc/named.conf .................................................................................................................. 42

etc/resolv.conf ................................................................................................................... 43

Preface 4

Other Files Included into Parallels H-Sphere Packages ............................................................. 43

Appendix D. Download Locations 44

Mirror Server for Parallels H-Sphere Downloads ........................................................................ 46

In this chapter:

Typographical Conventions ............................................................................... 5

Feedback .......................................................................................................... 6

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.

C H A P T E R 1

Preface

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.

6 Preface

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 guide provides instructions on upgrading Parallels H-Sphere 2.4.3 Patch 11 or

C H A P T E R 2

About This Guide

higher to version 3.1 Patch 1. If you have an older version:

1 Update to Parallels H-Sphere 2.4.3 Patch 11 first or contact Parallels

H-Sphere support (http://www.parallels.com/support/hsphere/).

2 Run a separate PostgreSQL update script to update PostgreSQL to

7.4.x version as described at

http://hsphere.parallels.com/misc/postgres-7.4.17.html.

Consider this before you update Parallels H-Sphere:

C H A P T E R 3

Preparing for Upgrading Parallels
H-Sphere

 The upgrade will not work without a valid Parallels H-Sphere license to cover all

accounts in the system.

 Please refer to the list of operating systems (on page 29) supported by Parallels

H-Sphere.
Warnings:

1. Update to Parallels H-Sphere 2.5 and up is not recommended for Parallels
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. Parallels H-Sphere Winbox versions earlier than 2.5 won‟t work correctly with
Parallels H-Sphere 2.5 RC 1 and up. In the same way, Winbox 2.5 RC 1 and up
won‟t work with Parallels H-Sphere under 2.5.

3. Serv-U FTP is no longer supported in Parallels 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 as described in the Migration of Serv-U to MS-FTP section of Parallels
H-Sphere System Administrator Guide.

4. We currently don‟t recommend updating Parallels 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).

5. No update is any longer available for RedHat 7.3, RedHat AS/ES/WS,
FreeBSD 4.11. All Parallels H-Sphere servers under these operating systems
need to be migrated to other supported OS‟s before the update.

 Config files for Apache, FTP, PHP, DNS, MySQL, and PostgreSQL should be

customized indirectly via respective template files. Otherwise, all custom

changes in major default configuration files are removed with each Parallels
H-Sphere update. Please carefully follow the config file templates customization
instruction.

If you update to Parallels H-Sphere 3.1+ from Parallels H-Sphere 2.5 or 3.0, your
custom config file templates will be ignored. You need to recustomize them.

 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 Parallels H-Sphere content
to the /hsphere directory before you proceed with the update. Please refer to
Appendix B. HDD Partitioning (on page 30).

 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 that can be downloaded from

http://hsphere.parallels.com/downloads/libmap.conf.

Preparing for Upgrading Parallels H-Sphere 9

 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
Parallels H-Sphere support (http://www.parallels.com/support/hsphere/).

 Custom server groups for name (DNS) logical servers are no longer supported. If

you are upgrading from Parallels H-Sphere 2.4.3 or earlier versions, please remove
all custom name server groups (including all respective logical/physical servers).
Please refer to Server Groups section of Parallels H-Sphere Service Administrator
Guide at http://www.parallels.com/en/hsphere/docs/ for details.

 MySQL Updates.

 If you are running MySQL version 3.x, please update to the latest MySQL 4.x

version prior to updating Parallels H-Sphere.

 Update MySQL v. 4.0 to 4.1: If your clients created

databases/tables/fields in the tables with specific charset, please refer to
the following documentation:

 Character set upgrade (http://dev.mysql.com/doc/refman/4.1/en/charset-

upgrading.html).

 Connection Character Sets and Collations

(http://dev.mysql.com/doc/refman/4.1/en/charset-connection.html).

 The procedure of MySQL update from version 4.x to 5.0 is performed

automatically. But it is reasonable to refer to the following documentation:
 Upgrading from MySQL 4.1 to 5.0

(http://dev.mysql.com/doc/refman/5.0/en/upgrading-from-4-1.html).

 mysql_upgrade - Check Tables for MySQL Upgrade

(http://dev.mysql.com/doc/refman/5.0/en/mysql-upgrade.html).

 mysql_fix_privilege_tables - Upgrade MySQL System Tables

(http://dev.mysql.com/doc/refman/5.0/en/mysql-fix-privilege-tables.html).

 Since Parallels H-Sphere 3.0+, you can download installation/update script from our

mirror site at http://download2.hsphere.parallels.com. For more information refer to
Parallels H-Sphere install/update script options (on page 19) section.

 If you update from Parallels H-Sphere 3.1 Beta 1 or earlier, please make sure to

update EasyApp with the respective collection package built for Parallels H-Sphere

3.1+.

To upgrade Parallels H-Sphere, please perform the steps provided below in this

In this chapter:

Step 1. Creating Update Profiles for Physical Servers ....................................... 11

Step 2. Updating Parallels H-Sphere Control Panel Core .................................. 14

Step 3. Updating H-Sphere Windows HsCore MSI Package ............................. 15

Step 4. Updating Physical Boxes ....................................................................... 17

Step 5. Updating PostgreSQL ........................................................................... 26

Step 6. Starting Control Panel Apache .............................................................. 27

Step 7. Starting ImageMaker ............................................................................. 27

Step 8. Checking the Version of Parallels H-Sphere .......................................... 27

C H A P T E R 4

Upgrading Parallels H-Sphere

chapter.

Upgrading Parallels H-Sphere 11

Step 1. Creating Update Profiles for
Physical Servers

Physical server profiles are sets of rules for updating/installing physical boxes. By
default, Parallels H-Sphere includes the „DEFAULT‟ profile which can‟t be removed or
changed. If not set otherwise, the box is updated according to this DEFAULT profile.

You can create your own update profiles from the Parallels H-Sphere administrator
interface and assign them to specific boxes. In this case, the system will update the
server according to the profile it‟s assigned to.

 To create a profile:

1 Go to E.Manager -> Update -> Physical server profiles.
2 Choose the box (Unix/Windows) and click the Add button.
3 Name and configure your profile in the form that appears:

 Adding Unix profile: with some of the parameters refer to the section on

hsphere-update Package (on page 13).

 Adding Windows profile check if needed the following options:

 Update only pointed logical server groups. You can choose between three

hosting modes: Windows hosting only, MsSQL hosting only, or both
Windows and MsSQL hosting modes

 Source URL for packages download redefinition is the link to an alternative server

with MSI packages. If not set, default MSI location is

http://download.hsphere.parallels.com/shiv/HS/WINDOWS/.

 Location of user home directory. If it is not set there, H-Sphere Winbox installer

will automatically create it on NTFS partition with the largest free space.

 MAC address of network interface to host dedicated IP’s, etc. If not set there,

H-Sphere Winbox installer will automatically choose an address based on
the free IPs of a physical server.

 Name of MSSQL server instance. Give a name to a MsSQL server instance if

you want it to differ from a default one generated from a NetBIOS name of a
specific server.

4 Click Save to apply. The newly-created profile will appear in the list of

existing profiles.

5 Click the Assign Profiles to Physical Servers link to assign the profile to a

server.

Note: You can assign only one profile to a server. But one and the same profile can
be assigned by several servers.

6 Check a physical box and click Apply.
 To reassign a profile:

1 Go to E.Manager -> Servers -> P. Servers.

12 Upgrading Parallels H-Sphere

2 Click the physical server name you want to reassign a profile to.

In this section:

hsphere-update Package Reference ................................................................. 13

3 Click the Edit icon in the Physical Server Profile field.
4 Reassign the profile.

From now on, every time you update this physical box from CP interface, it will
update according to the profile.



Upgrading Parallels H-Sphere 13

hsphere-update Package Reference

The hsphere-update package is installed during Parallels H-Sphere installation on
each physical box. When updating Parallels H-Sphere, it runs the upackages script on
the CP box to update Parallels H-Sphere packages on each box to their latest version.

upackages Syntax

upackages [ -h ] [ -i ] [ -f ] [ -s ] [ -v version ] [ -V ] [ -e
show|add:pattern,...|del:pattern,...|del:all ] [ -p ] [ -w ] [ -m ] [ -j ] [-P] [-r ] [ -u ] [ -P ] [ -n ] [

-M ] [ -S ] [ -R ] [ -N ] [ -I ] [ -o ]
Where:

 h - help information.

-i - ignore md5 sum of the downloaded packages, only warning.

-f - force mode, update packages by force, when md5 sum of the installed hsphere

package differs from downloaded package.

-s - update only packages change, which takes place in the hsphere subversion

according to corresponding version.

-v version, format U[version]/U[subversion]. If not specified,

/hsphere/shared/etc/hsversion file is checked.

-V - verbose mode

-e - [show|add:pattern1,pattern2,...|del:pattern1,pattern2,...|del:all] - show, set

or delete the list of the package patterns, which must be skipped during update on
all or specific list of HS boxes.

Note: Use this carefully, as HS packages are connected with HS version. This may be
used if you have customized version of the specific HS package or if you update
system packages, like MySQL server, via native OS package manager, etc.

 p - PostgreSQL update (for new HS box this is done by default)

-w - Site Studio update

-m - MyDNS service is used instead of Bind 9.3.x, Update of the bind will be

skipped.

-j - required during IP migration

-r - package update strictly according to package list (by default update of packages

with higher version skipped)

-t [php,httpd,ftpd,mysql,pgsql,cphttpd,named] - place custom templates in the

required location for further editing

-P - private update (for testing purpose).

-u - Source URL for packages download redefinition.

-n - Skip restart of postgres and httpdcp at the end of update.

-M - update modes (presingle, hspresingle, postsingle, hspostsingle,

cpinstall, hsupdate, postgres, sitestudio, update, ipmigration,
deploy) :

 presingle - single server package mode
 hspresingle - „presingle‟ mode, except sitestudio installation
 postsingle - single server deploy mode
 hspostsingle - „postsingle‟ mode, except sitestudio postconf

14 Upgrading Parallels H-Sphere

 cpinstall - control panel preinstall procedure
 update - full update (all packages update)
 hsupdate - „update‟ mode, except sitestudio update
 postgres - postgres update
 sitestudio - sitestudio update
 ipmigration - reconfiguring IP dependent information
 deploy - deploy mode (general box post-reconfiguration)

 S - slave installation/update mode - provides installation/update of web or mail

slave box.

-R mask1[,mask2,...] - revert mode, provides downgrade of a set of packages with

mask1[,mask2,...]

-N - this option allows to force install/update for the deprecated OS/soft listed in

http://www.psoft.net/eol.html if possible.

-I - this option allows to get exclude package list from stdin (used in HS 3.1 for

different update profile configuration in CP interface). Retrieved package list is
merged with pre-configured exclude package list.

-o - skips pre-configured exclude package list during update.

For instance, to install packages for Parallels H-Sphere 2.5 Patch 6 with md5 sum of
the downloaded files ignored run:

upackages -i -v U25.0/U25.0P6

Step 2. Updating Parallels H-Sphere
Control Panel Core

 To update Parallels H-Sphere CP core:

1 Download the install/update script. For example, for 3.1 RC 1 (Build

903) run:

Linux:

# wget

http://download.hsphere.parallels.com/shiv/HS/releases/U31.0/U31.0P1/U3

1.0P1

FreeBSD:

# fetch

http://download.hsphere.parallels.com/shiv/HS/releases/U31.0/U31.0P1/U3

1.0P1

2 Stop Parallels H-Sphere using one of the following commands:

Linux:

# /etc/rc.d/init.d/httpdcp stop

FreeBSD:

# /usr/local/etc/rc.d/apachecp.sh stop

Stop Parallels SiteStudio ImageMaker by running:

Upgrading Parallels H-Sphere 15

# /hsphere/shared/SiteStudio/imaker.sh stop

In this section:

Windows HsCore Update Procedure ................................................................. 16

3 Run the update script:

# sh ./U31.0P1

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

4 Update Parallels H-Sphere core (templates, classes, jars):

cpupdate [OPTIONS]

Step 3. Updating H-Sphere Windows
HsCore MSI Package

Skip this step if your Parallels H-Sphere cluster contains a Windows server.
Upgrade Winbox to Parallels H-Sphere 3.1 Patch 1. Parallels H-Sphere Winboxes of

earlier versions are not compatible with Parallels H-Sphere Control Panel 3.1 and up.
Prior to the update, consider the following:

1 Parallels H-Sphere Windows 3.1 and up is not compatible with Parallels H-Sphere

Control Panel 3.0 or lower.
 Before you update Parallels H-Sphere Winbox, you must first update Parallels

H-Sphere to the respective 3.1+ version.

 When updating Parallels H-Sphere Winbox from version 2.4.3 or below, update

it first to 3.0 Patch 5 and only then to 3.1+.

2 Open SOAP port 10125 for data communication between Control Panel and

Windows server.

3 If you are going to use Microsoft Windows SharePoint Services, before upgrading

Parallels H-Sphere Winbox make sure to install SharePoint as described in the
section Setting Up SharePoint to Use MSSQL Server of Parallels H-Sphere System
Administrator Guide.

4 We currently don‟t recommend updating Parallels H-Sphere Winbox when there are

512 and more ColdFusion mappings on a Windows server (i.e., ColdFusion is
turned on for more than 511 user domains).