_group 

_subaccts group is being created for each account that has subaccounts  any subaccount of a particular account becomes a member of

_subaccts group  NTFS permissions to particular subaccount home directory are given explicitly for this subaccount in addition to existing NTFS permissions for this directory Windows Servers 289 IIS Security Management Features:  The FTP account login is not used anymore as anonymous web access for all sites owned by the user. Instead of this, for each virtual host a separate account with random password is being created during virtual host creation procedure.  The password synchronization IIS feature which requries 'LOCAL SYSTEM' identity for web application process is not used anymore. The reason for this is that this account and randomly generated password is registered in the metabase as anonymous for this particular virtual host.  An account is being added to HS_ACCTS, HS_IUSR_ACCTS and Parallels H-Sphere account group. Each anonymous login has the following format: _ where is Parallels H-Sphere FTP account title and is number of particular virtual web host owned by this Parallels H-Sphere account.  Now each IIS web application process is run under 'NETWORK SERVICE' identity. There is a number of Parallels H-Sphere modules run in IIS web processes which should perform some privileged operations such as read/write files or register keys protected by NTFS permissions. That is why Parallels H-Sphere creates a special 'HsISAPIAcct' account as a member of the 'Local Administrators' group. This account is used by Parallels H-Sphere IIS modules to perform such privileged operations. In addition, its password is being regenerated each time IIS is started for security reason. 290 Windows Servers NTFS permissions There are permission schemes which are used for Windows 2003 and Windows 2008. Windows 2003/2008 The following NTFS permissions are set for a user home directory:  Local Administrator group: FULL ACCESS  SYSTEM: FULL ACCESS  NETWORK SERVICE: READ ACCESS  _group local group: MODIFY,READ,WRITE,EXECUTE,LIST FOLDER CONTENT The following permissions are added to bin directory:  NETWORK SERVICE: READ,EXECUTE,LIST FOLDER CONTENT Relevant to both platforms The following NTFS permissions are used for ODBC DSN registry key:  Local Administrator group: FULL ACCESS  SYSTEM: FULL ACCESS  _group local group: QUERY VALUE,SET VALUE,CREATE SUBKEY,ENUMERATE SUBKEYS,NOTIFY FrontPage Server Extensions Management Notes The following changes were made to FPSE management as a part of a new scheme:  Anonymous access is assigned to Browser role for any FPSE enabled virtual host  _group local group is set as FPSE administrator for any FPSE enabled virtual host  HsAuth ISAPI filter is no more used for FPSE enabled virtual hosts Windows Servers 291 ASP.NET Management Notes  The ASP.NET management operations, which enable and disable ASP.NET service for a particular virtual web host, are based on the .NET framework configuration file machine.config.  The following fragment is added to the machine.config file for a particular virtual host if ASP.NET is being disabled for this virtual host: >  When ASP.NET service is enabled for a particular virtual host, it is being removed from machine.config file, if found. Migration Notes  During the Winbox upgrade, all existing accounts will be automatically migrated to a new security scheme. This process migrates account settings, web settings, NTFS permissions for home directories and ODBC DSNs, ASP.NET settings, FPSE settings and can take significant time.  The migration procedure is performed once. If it's necessary for some reason to repeat the migration, the NewSecurity line should be removed from bininstall.history file.  Migration process can be monitored using migration log which can be found in the update.log log file of upgrade tool. Important: during the migration, IIS servers will be automatically restarted on Windows 2003. Recovery Notes To perform server recovery (on page 384) or server to server movement, use the SetScrtNs.exe tool which is a new analogue of the SetScrt.exe tool. It has the same purpose as the older version, but sets the correct permissions for a new security scheme. Download SetScrtNs Tool: http://download.hsphere.parallels.com/shiv/WinBox/SetScrtNs20.exe 292 Windows Servers Calculating Winbox Traffic In Parallels H-Spherethe system writes winbox traffic data to XML logfiles:  YYYY-MM-DD.web.xml - http traffic,  YYYY-MM-DD.ftpg.xml - guest ftp traffic,  YYYY-MM-DD.ftpa.xml - anonymous ftp traffic. Example: 7782 39060 15 8 3493 38549 8 2 These xml files are saved to the C:\HSphere.NET\data\services\traffic\ directory. Once a day TrafficLoader (on page 37) parses these files using SOAP and writes statistic data into the translog table of the Parallels H-Sphere system database. After that these files are deleted and created anew on the next day. CHAPTER 19 Microsoft SQL Server Microsoft SQL, like other commercial third party products, is purchased and installed separately from Parallels H-Sphere. Microsoft SQL Server is a fully Web-enabled database with the ability to query the database through a browser and rich Extensible Markup Language (XML) support. In addition, Microsoft SQL Server holds benchmark records for scalability and reliability, both of which are crucial for the success of an enterprise database. For extensive coverage of Microsoft SQL Server, please refer to http://www.microsoft.com/sql/default.asp. In this chapter: Installing Microsoft SQL 2005 Server ................................................................ 294 Moving MS SQL Databases Across Servers ..................................................... 295 Moving MS SQL Databases to a New Location ................................................. 296 294 Microsoft SQL Server Installing Microsoft SQL 2005 Server This document explains how to install MS SQL database software and integrate it with the Parallels H-Sphere system. Parallels H-Sphere 2.5.0 and higher supports Microsoft SQL Server 2005 (http://www.microsoft.com/technet/prodtechnol/sql/2005/default.mspx). MS SQL server can be installed on Parallels H-Sphere Windows server. This means the server must have Parallels H-Sphere Windows software installed and be added to the Parallels H-Sphere configuration. To add MS SQL 2005 to winbox with Parallels H-Sphere installed: 1. Install ASP.NET 2.0 and check the version of ASP.NET. RootVer must be 2.0.XXXX, not 1.1.XXXX in the registry HKLM/Software/Microsoft/ASP.NET. If RootVer is 1.1.XXXX:  Go to C:\Windows\Microsoft.NET\Framework\v2.0.5xx\ through command line  Run from command line: aspnet_regiis -r  Restart IIS : iisreset /restart 2. Install MS SQL server following the directions of the installation wizard. If you installed SQL 2005, you should also install SQL Server Management Studio Express. 3. In SQL Server Managment Studio Express create login with system administrator privileges for the MS SQL server. As a rule, login 'sa' is used. 4. Configure Parallels H-Sphere connection settings to work with MS SQL server: Note: Parallels H-Sphere 3.0 + uses Windows authentication method to connect to MSSQL server. Therefore MSSQL server should be installed locally on the same server with Parallels H- Sphere. Go to /hsphere.net/bin/hsphere.config file and make sure the NAME_OF_YOUR_SQL_SERVER is set correctly in: prop name="server" value="NAME_OF_YOUR_SQL_SERVER" description="MSSQL server name or IP" 5. Go to SQLServer Properties -> Security. Chose SQL Server Authentication and Windows Authentication to allow Parallels H-Sphere and your customers to access MS SQL server remotely. Microsoft SQL Server 295 6. Make sure that MS SQL server IP set as a logical server IP in the E.Manager menu is set in Start -> Programs -> MSSQL 2005 Server -> Configuration Tools -> SQL Server Configuration Manager -> SQL Server Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP(enabled) -> Properties -> IP Addresses tab. Make sure this IP is there with Active and Enabled set to Yes. 7. In your CP add MS SQL server group to the physical winboxes with MS SQL installed. 8. Add logical MS SQL servers in CP and add IP addresses for it. 9. On winboxes run the following commands: net stop hsphere net start hsphere 10. Turn on MS SQL servers in the user's Plan Edit Wizard. After that, try creating MS SQL databases from user's CP. Moving MS SQL Databases Across Servers  To move the databases from one MS SQL server to another: 1. Install the new MS SQL server, keeping the same path to databases as for the old server. That means, databases on the new server should be located on the same disc and necessarily in the same directory as for the old server. For example, on the old server data is located on d:\mssql\data\, so the data on the new server should be located in the same directory. 2. Stop the new MS SQL server. 3. Copy all MS SQL database files including the "master" database which keeps all logins information and other necessary information. Important: All database files should be put into the same directory as for the old server. 4. Start the new MS SQL server. 5. Change the MS SQL logical server IP to the new MS SQL server IP in the Control Panel. 6. All resellers should reconfigure MS SQL server aliases to use the new IP for the MS SQL server. 296 Microsoft SQL Server Moving MS SQL Databases to a New Location This document describes how to change the location of the data and log files for any MS SQL database. There are two ways to move MS SQL databases: Method 1 (preferable) 1. Create new MS SQL data location (E:\MSSQL\data\) 2. Stop MS SQL server 3. Move all databases to a new location (move *.mdf and *.ldf files) 4. Create junction link between old and new MS SQL data folders. This can be done with Sysinternals Junction (http://download.hsphere.parallels.com/shiv/WinBox/linkmagic.exe ) or any other utility of this kind 5. Start MS SQL server In case you have some databases with different from default locations: 1. Detach these databases 2. Copy these databases from old location to a new location 3. Attach these databases from a new location Method 2 1. Go to MS SQL Enterprise Manager 2. Choose the MS SQL server Properties option. For this, go to Expand SQL Server Group > MS SQL server Microsoft SQL Server 297 298 Microsoft SQL Server 3. On the Database Settings tab, change New database location and set the path to:  Default data directory, i.e. a new logical disk (E:\MSSQL\DATA\)  Default log directory (E:\MSSQL\DATA\) Microsoft SQL Server 299 4. Create the following folder E:\MSSQL\DATA\ 5. Set the same NTFS permissions as in the folder [drive]:\Program Files\Microsoft SQL\Server\MSSQL\DATA (the path where DB's are located). 6. Go to MS SQL Enterprise Manager > Databases and right click on the Necessary database > All tasks > Detach Database with the option Update statistics prior detach. Make sure to check database and database log files locations before detaching a database. 300 Microsoft SQL Server 7. Go to [drive]:\Program Files\Microsoft SQL Server\MSSQL\DATA and copy Detached DB files (*.mdf and *.ldf) to a new folder E:\MSSQL\DATA\ 8. Go to MS SQL Enterprise Manager > Databases and right click Databases > Attach Database. 9. Put the path to the necessary database (E:\MSSQL\DATA\) and select hsadmin in Specify database owner field. Microsoft SQL Server 10. Re databases. eat steps 6-8 for the rest of All necessary information can be found in MS SQL documentation (http://www.microsoft.com/sql/default.mspx). 301 CHAPTER 20 Dedicated Servers This chapter tells you how to configure MRTG service for dedicated servers. In this chapter: Configuring MRTG ............................................................................................ 303 Dedicated Servers 303 Configuring MRTG In Parallels H-Sphere the MRTG software (http://mrtg.hdl.com/mrtg.html) is used for the dedicated hosting feature. This software is installed to Parallels H-Sphere as a logical server from hsphere-mrtg-rrd-X-X package, where X-X is the latest available version. Mrtg service is managed by supervise, similarly to clamd, spamd, ftpd, and bind. Apache service with configured VirtualHost for mrtg service is required which is provided by Apache configuration. Mrtg works with RRDtool (http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/) which improves its performance and graphing flexibility. RRDtool is used as the logger to MRTG. It stores data samples on each of the network switch interfaces (ports) in a separate RRD. To minimize size of the database files, RRD uses the consolidation mechanism. It guarantees that the database does not grow over time and that old data is automatically eliminated. However this leads to degradation of accuracy. For the sake of high degree of data accuracy, space for 10080 samples (35 days) is allocated. The DSBandwidthLoader daily cron acquires data from RRDs and stores it into the hsphere database. Managing MRTG Service For Linux: /etc/init.d/mrtg stop | start | restart | stat For FreeBSD: /usr/local/etc/rc.d/mrtg.sh stop | start | restart | stat Configuration Directory and File Mrtg configuration directory is /hsphere/local/config/mrtg. /hsphere/local/config/mrtg/mrtg.conf - mrtg configuration file. It has an include for /hsphere/local/config/mrtg/ports/index.conf which in its turn contains includes for files corresponding to each opeational switch port. Such files are generated dynamically via CP interface when switch ports are assigned to dedicated servers. Scripts Processing Data /hsphere/local/config/mrtg/scripts/getstatistics - gathers data from each port file. /hsphere/local/config/mrtg/scripts/setstartbill - sets the start billing period date. /hsphere/local/config/mrtg/scripts/formgraph - draws traffic graphs. 304 Dedicated Servers RRD Files Mrtg writes RRD files to /hsphere/local/config/mrtg/rrd directory. In its subdirectories image files with bandwidth representations for chosen periods are located:  ~httpd/htdocs/rrd/d - day  ~httpd/htdocs/rrd/w - week  ~httpd/htdocs/rrd/m - month  ~httpd/htdocs/rrd/y - year The Problem with Calculating Large (>100mbps) Bandwidth Traffic It is a known issue that MRTG with 32-bit counters doesn't calculate correctly the traffic when bandwidth exceeds 100 Mbps. A solution is to switch to 64-bit counter by choosing SNMPv2c/SNMPv3 protocols. This, however, may not work because some devices don't support these protocols.  To switch to SNMPv2c/SNMPv3, you need to manually customize: 1. Log into the CP server as cpanel user. 2. Copy the default template ~cpanel/shiva/shivatemplates/common/ds/mrtg_target.config to the custom ~/shiva/custom/shivatemplates/common/ds/mrtg_target.config location. Please carefully follow the template customization procedure described in Parallels H-Sphere Customization Guide. 3. Edit the first line with ${port}:${com_name}@${device}: according to the MRTG Reference (http://oss.oetiker.ch/mrtg/doc/mrtgreference.en.html). For example, to switch to SNMPv2c, the line will be like this: Target[${target}]: ${port}:${com_name}@${device}:::::2 For more advanced configuration please refer to MRTG Reference. 4. Restart Parallels H-Sphere to apply customization. CHAPTER 21 System Packages Parallels H-Sphere installation is modular, its packages independent and selfconfigurable. It is possible to use standard package managers (on page 26) like yum, up2date or apt-get for scheduled updates of Parallels H-Sphere services, instead of running occasional update scripts or updating Parallels H-Sphere versions. In this chapter: Common Packages ........................................................................................... 305 Parallels SiteStudio Packages ........................................................................... 332 Common Packages Common packages are those used for different types of H-Sphere servers. For example, hsphere-apache is installed on Web, mail, MySQL (for PhpMyAdmin), and PostgreSQL (for PhpPgAdmin) servers; and the hsphere-scripts package is installed on every Unix server. Below is the reference on some common packages. In this section: hsphere-info: Collecting Information About Parallels H-Sphere Servers into XML Configs 306 hsphere-update Package .................................................................................. 307 Parallels H-Sphere Perl Modules ....................................................................... 309 Parallels H-Sphere Apache ............................................................................... 311 Parallels H-Sphere PHP .................................................................................... 322 306 System Packages hsphere-info: Collecting Information About Parallels HSphere Servers into XML Configs Parallels H-Sphere includes the hsphere-info package installed on each Parallels H-Sphere Unix server. The package installs the /hsphere/shared/bin/hsinfo script on each server, and the script collects information about this server into the /hsphere/shared/etc/config.xml file. hsfinfo Usage: hsinfo [ -ame ] [ -p box IP ] [ -g group ] [ -t type ] [ -f xmlfile ] [ -s delimiter ] hsinfo -l [ -p box IP ] [ -g group ] [ -s delimiter ] [ -f xmlfile ] hsinfo -i [ -ame ] [ -g group ] [ -f xmlfile ] [ -s delimiter ] hsinfo -n [ -p box IP ] [ -g group ] [ -f xmlfile ] hsinfo -o a[ddress]|i[nterface]|n[umber] [ -f xmlfile ] hsinfo -d [ -f xmlfile ] hsinfo -v [ -f xmlfile ] hsinfo -G hsinfo -T hsinfo -h -l list of logical server names -i list of physical server IPs -n domain name of the logical server -d servise zone name -p phisical box IP (default: local physical box) -v hspere version -a show IP address -m show mask -e show external IP addreyyss -o show network interface name of the physical IP -G list of possible logical server groups -T list of possible IP types -h help by default show only IP addresses group: cp, mail, unix_hosting, windows_hosting, mysql, pgsql, mssql, dns, mrtg, system (default: all) type: system, service, shared, dedicated, resellerSSL, resellerDNS, all (default: service) xmlfile: XML file location (default: /hsphere/shared/etc/config.xml) The /hsphere/shared/etc/config.xml file contains information about physical and logical server names, IDs, IP addresses; system zones; current Parallels H-Sphere version, etc. Download sample config.xml from http://download.hsphere.parallels.com/HSdocumentation/xmls/config.xml. This sample XML is for NAT configured Parallels H-Sphere cluster (on page 29). Otherwise, if external IPs are used for H-Sphere logical and physical servers, the extIP attribute is omitted, for example: 11.22.33.44 255.255.255.0 System Packages 307 hsphere-update Package The hsphere-update package is installed on each Parallels H-Sphere 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 a list of the packages belonging to a service specified by pattern (patternN), which must be skipped during the update on all or particular HS boxes. The following services (patternN) are available for excluding: dns, mysql, postgresql. Note: Use this carefully as HS packages are connected with HS version. This may be used if you have a customized version of the specific HS package or if you update system packages, like MySQL server, via native OS package manager, etc. For example: hspackages exclude=add:mysql ips=192.168.1.10  -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   308 System Packages    -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  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://hsphere.parallels.com/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, install packages for Parallels H-Sphere 2.5 Patch 6 with md5 sum of the downloaded files ignored: upackages -i -v U25.0/U25.0P6  System Packages 309 Parallels H-Sphere Perl Modules All necessary Perl modules used by Parallels H-Sphere on supported OS are installed from a single package hsphere-perl-x-x. There is no need to update Parallels H-Sphere Perl modules by yourself, as when Perl version is updated/downgraded, the /hsphere/local/config/perl/hspmod.switch utility is used to switch Perl to a proper Parallels H-Sphere Perl modules version. hspmod.switch has the following syntax: hspmod.switch { -l | -v perl_version } Where: -l lists all possible Parallels H-Sphere perl module versions you may switch to. -v switches to the modules of proper perl_version, which must be specified in 0-9.09.0-9 format. The modules for both native OS perl and currently stable perl are included into the latest perl package update. To see the list of modules with their versions for the specific hsphere-perl package, run the following command (specify the build instead of x-x): rpm -q --provides hsphere-perl-x- x The above mentioned modules are installed with hsphere-perl and required for proper Parallels H-Sphere work. WARNING: Do not update or change any configuration of your system Perl, as it will most likely damage your Parallels H-Sphere installation. The topic below provides the list of supported Perl versions. In this section: Supported Perl Versions.................................................................................... 310 310 System Packages Supported Perl Versions Below is the list of Perl packages required for Parallels H-Sphere on supported operating systems. Please make sure that your operating system has the correct Perl version installed according to the following table. To check the version of Perl installed on your box, run: perl -V Operating System Supported Perl Versions RedHat EL 3, CentOS 3.x, White Box EL 3.x Perl 5.8.0; 5.8.7; 5.8.8; 5.10.0 RedHat EL 4, CentOS 4.x, White Box EL 4.x Perl 5.8.5; 5.8.7; 5.8.8; 5.10.0 RedHat EL 4, CentOS 4.x, White Box EL 4.x (x86_64) Perl 5.8.5; 5.8.7; 5.8.8; 5.10.0 RedHat EL 5, CentOS 5.x Perl 5.8.8; 5.10.0 RedHat EL 5, CentOS 5.x (x86_64) Perl 5.8.8; 5.10.0 FreeBSD 6.1 Perl 5.8.7; 5.8.8; 5.8.9; 5.10.0 FreeBSD 6.2 Perl 5.8.7; 5.8.8; 5.8.9; 5.10.0 FreeBSD 6.3 Perl 5.8.7; 5.8.8; 5.8.9; 5.10.0 FreeBSD 6.4 Perl 5.8.7; 5.8.8; 5.8.9; 5.10.0 FreeBSD 7.0 Perl 5.8.7; 5.8.8; 5.8.9; 5.10.0 FreeBSD 7.1 Perl 5.8.8; 5.8.9; 5.10.0 FreeBSD 7.2 Perl 5.8.9; 5.10.0 FreeBSD 7.3 Perl 5.10.1 System Packages 311 Parallels H-Sphere Apache In Parallels H-Sphere 3.1 Beta 1 the Web service functionality was greatly extended and improved to allow for more flexibility both in administering Unix web boxes and in end user Web settings. This chapter describes the main features of the Web service software and includes information on Apache configuration useful for Parallels H-Sphere system administrators. In this section: Web Service Packages ..................................................................................... 311 Support of Apache 2.2.x and 1.3.x .................................................................... 312 Tuning Web Service from the CP Interface........................................................ 313 Apache Modules................................................................................................ 316 Apache Configuration ........................................................................................ 319 Web Statistics Software..................................................................................... 321 Apache Logs and Web Traffic Calculation in Parallels H-Sphere....................... 321 Log Rotate Config File ....................................................................................... 321 Apache Suexec ................................................................................................. 322 Web Service Packages Apache 2.2 underwent significant changes since 1.3 version. Accordingly, there are PHP modules compatible with each particular Apache version that is indicated in the name of PHP package (1x or 2x). The cgi/cli part of PHP is assembled and works based on Apache 1.3. Only the pear part of PHP is common for the two Apache versions. Here is the list of web service software packages for Parallels H-Sphere 3.1 Beta 1 and up (note that versions are just examples that may differ from current ones): Package Description hsphere-apache2-h3.1-2.2.6-x Apache 2.2.x binaries, modules, libraries and headers hsphere-apache-h3.1-1.3.39-x Apache 1.3.x binaries, modules, libraries and headers hsphere-apache-shared-h3.11-x Configuration template files, scripts, startup files, etc. common for Apache 1.3.x and 2.2.x hsphere-apache-utils-h3.1-1x Utilities used when parsing apache logs, lynx browser, etc. hsphere-php4-1x-4.4.7-x libphp4 for Apache 1.3.x hsphere-php4-2x-4.4.7-x libphp4 for Apache 2.2.x hsphere-php4-cgi-4.4.7-x CLI and CGI php4 binaries hsphere-php4-pear-4.4.7-x PEAR for PHP4 312 System Packages hsphere-php4-plugins-4.4.7-x Set of plugins, their confs, which may work in pair with CLI, CGI or libphp4 hsphere-php5-1x-5.2.4-x libphp5 for Apache 1.3.x hsphere-php5-2x-5.2.4-x libphp5 for Apache 2.2.x hsphere-php5-cgi-5.2.4-x CLI and CGI php4 binaries hsphere-php5-pear-5.2.4-x PEAR for PHP5 hsphere-php5-plugins-5.2.4-x Set of plugins, their confs, which may work in pair with CLI, CGI or libphp5 Support of Apache 2.2.x and 1.3.x In addition to Apache 1.3.x, support of Apache 2.2.x is implemented. There are two modes of Apache 2.2.x:  MPM prefork (http://httpd.apache.org/docs/2.2/mod/prefork.html)  MPM worker (http://httpd.apache.org/docs/2.2/mod/worker.html) For the MPM worker mode, cgi requests are processed via mod_cgid. System Packages 313 Tuning Web Service from the CP Interface In Parallels H-Sphere 3.1 Beta 1 and up there is a possibility to choose some Web settings for a physical Web server right from administrator's cp interface:  switch between Apache versions Note: this setting is available for all physical boxes.   enable additional Apache modules when enabling apache_security module, set also mod_security options  set PHP configuration  when enabling fastcgi mode, configure its VirtualHost options  disable unnecessary PHP plugins Note: For more detailed information, refer to section Advanced Web Server Settings of Parallels H-Sphere Service Administrator Guide. All webbox related settings chosen from the cp interface are stored in the following file: /hsphere/shared/scripts/scripts.cfg Such changes are applied immediately by the script: /hsphere/shared/scripts/manage-service.sh httpd restart The settings are stored in the configuration file in the form of 'prefix_title=value. There are several groups of settings: In this section: Apache Settings ................................................................................................ 313 PHP Settings ..................................................................................................... 314 Fastcgi Settings ................................................................................................. 315 Apache Settings These are settings for enabling/disabling Apache modules. The prefix is apache. Here is the list of possible settings: Title Default Value apache_libphp 4 1 apache_libphp 5 0 apache_ssl 1 apache_scgi 0 apache_frontp age 0 Comments Ignored in Apache 2 314 System Packages apache_throttl e 0 Ignored in Apache 2 apache_status 0 apache_fastcgi 0 apache_securit y 0 apache_cache 0 apache_securit y2 0 Ignored in Apache 1 apache_versio n 1 Apache version. Only for Apache 2. apache_mpm prefork MPM mode: prefork or worker. Only for Apache 2 All independent modules are implemented via specific templates each allowing for customization. They have their own config files which are inserted in the main config file using the include directive. The main config file is also realized via independent templates for Apache 1.3.x and 2.2.x. PHP Settings For each Apache version/mode (Apache 1.3.x or 2.2.x MPM prefork and MPM worker) there is a possibility to operate PHP in 6 modes: libphp5, libphp4, cgi-php5, cgi-php4, fastcgi-php4, fastcgi-php5. The prefix is 'php'. Here is the list of possible settings: Title Default Value php_libph p4 2 php_fastc gi4 0 php_cgi4 1 php_libph p5 0 php_fastc gi5 2 php_cgi5 1 Comments Needs mod_fastcgi being enabled for Apache If the value is other than 0, the value for php_libphp4 has to be 0 System Packages 315 Fastcgi Settings Fastcgi (http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.htm), unlike the regular cgi, keeps the activated module e.g. php loaded for some time after the call. All further calls are carried out quicker that preserves time for programs being loaded. However, the number of programs that can be stored in the fastcgi operating memory is limited. All programs loaded by fastcgi are performed with the privileges of the user who owns the corresponding virtual host. That is why they can only serve calls to this particular virtual host. This means that if all users will have fastcgi, this may cause considerable delays and enormous increase in server load. We recommend selective approach to enabling fastcgi, i.e. after enabling it for heavily visited virtual hosts monitor the server load for several days. If after such monitoring the load is found permissible, enable fastcgi for more users and so on. The same is with with fastcgi parameters. They are set on the server level and can't be changed for a particular virtual host. There is not direct way to check effectiveness of these parameters - only indirect observance based on server operating. That is why change these parameters with precaution. The prefix is 'fcgi_'. Here is the list of possible settings: Title Default Value autoUpdate Comments There may be a serious problem when this option is used with -restart. flush 0 gainValue 0.5 idle-timeout 30 [seconds] initial-env FCGI_ROL E init-start-delay 1 [seconds] killInterval 300 [seconds] listen-queuedepth 100 maxClassProces ses 10 It must be <= to -maxProcesses (this is not programmatically enforced) maxProcesses 50 It must be >= to -maxClassProcesses (this is not programmatically enforced) minProcesses 5 multiThreshold 50 Allows to check which fastcgi setting is being used. RubyOnRails may need additional variables. If only one instance remains, singleThreshold is used instead 316 System Packages pass-header This option makes available the contents of headers which are normally not available (e.g. Authorization) priority 0 processSlack 5 restart Causes the process manager to restart dynamic applications upon failure (similar to static applications) restart-delay 5 [seconds] singleThreshold 0 Changing this is not recommended (especially if -appConnTimeout is set) startDelay 3 [seconds] Must be less than appConnTimeout to be effective updateInterval 300 [seconds] Apache Modules The core of hsphere-apache contains only two modules: http_core.c and mod_so.c. The rest are compiled as DSO, and their list can be obtained by running:  for Apache 1.3: ls /hsphere/shared/apache/libexec/  for Apache 2.2: ls /hsphere/shared/apache2/modules/ Modules in different Apache versions may have distinction in their titles and configuration directives. Apache 2.2 lacks some modules present in 1.3 version, their functionalities being substituted by other modules, except for mod_throttle and mod_frontpage which are not supported in 2.2 version. Compatibility of Apache 1.3 and 2.2 is achieved in Parallels H-Sphere via the mod_macro module. Apache 2.2 adds several new modules to extend functionality. See below the comparative list of modules (the titles correspond to *.so files): Apache 1.3 Apache 2.2 libphp4* libphp4* libphp5** libphp5** libproxy*** libssl mod_access mod_ssl System Packages mod_actions mod_actions mod_alias mod_alias mod_asis mod_auth mod_auth_anon mod_auth_basic mod_auth_db mod_auth_dbm mod_authz_dbm mod_auth_digest mod_auth_external mod_authnz_extern al mod_auth_kerb mod_auth_kerb mod_authn_anon mod_authn_dbd mod_authn_dbm mod_authn_default mod_authn_file mod_authz_default mod_authz_groupfil e mod_authz_host mod_authz_owner mod_authz_user mod_autoindex mod_autoindex mod_cache mod_cern_meta mod_cern_meta mod_cgi mod_cgi mod_cgid mod_dav mod_dav_fs mod_dbd mod_define mod_deflate mod_digest mod_dir mod_dir mod_disk_cache mod_dumpio mod_env mod_env 317 318 System Packages mod_expires mod_expires mod_ext_filter mod_extract_forwar ded mod_extract_forwar ded mod_fastcgi mod_fastcgi mod_filter mod_frontpage mod_gzip mod_headers mod_headers mod_ident mod_imagemap mod_imap mod_include mod_include mod_info mod_info mod_log_agent mod_log_config mod_log_config mod_log_forensic mod_log_forensic mod_log_referer mod_logio mod_macro mod_macro mod_mem_cache mod_mime mod_mime mod_mime_magic mod_mime_magic mod_mmap_static mod_negotiation mod_negotiation mod_psoft_traffic mod_rewrite mod_rewrite mod_scgi mod_scgi mod_security mod_security mod_security2 mod_setenvif mod_setenvif mod_speling mod_speling mod_status mod_status mod_suexec mod_throttle mod_unique_id mod_unique_id mod_userdir mod_userdir mod_usertrack mod_usertrack System Packages 319 mod_version mod_vhost_alias mod_vhost_alias Notes: *Part of the hsphere-php5-Xx- package where X is apache version (1 or 2). **Part of the hsphere-php4-Xx- package where X is apache version (1 or 2). ***This module provides for an HTTP 1.1 caching proxy server. Apache Configuration Apache 1.3 Apache 2.2 /hsphere/shared/apache /hsphere/shared/apache2 Comments: Apache home directory /hsphere/local/config/httpd /hsphere/local/config/httpd2 Comments: Apache configuration directory ~httpd/conf -> /hsphere/local/config/httpd Comments: The symlink from home directory Configuration File /hsphere/local/config/httpd/httpd .conf /hsphere/local/config/httpd2/httpd .conf Comments: This file contains server wide configuration (modules enabled, their parameters set etc.). We don't recommend that changes are made to this file. When Apache modules are enable/disabled from the interface, the configuration files are left unchanged. This interface feature is implemented via the comand line Apache using directives and corresponding global symbols. These files are customized using config file templates. More on config file template customization read in Appendix C of Parallels H-Sphere Installation Guide. Custom Configuration File /hsphere/local/config/httpd/custo m.conf /hsphere/local/config/httpd2/custo m.conf Comments: We recommend that this file is used for making changes to the wide configuration, and for enabling additional modules in particular. This may facilitate finding configuration errors in case the server cannot start. When Apache is launched, the custom configuration file is the second to be processed after httpd.conf. After that, virtual hosts configuration is picked up. System Virtual Hosts Config /hsphere/local/config/httpd/namev h.conf /hsphere/local/config/httpd2/namev h.conf 320 System Packages Comments: This file contains list of all system (not user!) virtual hosts. Apache supports virtual host of 3 types - name- based, IP-based and port-based. Parallels H-Sphere uses name-based virtual hosts by default but the other types can be used as well. The configuration file contains information on host type for each IP. This file is processed after custom.conf but before processing the configuration of virtual hosts. Virtual Hosts (Logical Servers) Configs /hsphere/local/config/httpd/conf/ lservers/ mail.conf, mrtg.conf, mysql.conf... /hsphere/local/config/httpd2/conf/ lservers/ mail.conf, mrtg.conf, mysql.conf... Comments: For each logical server a virtual host is created. Before, when accessing the box by its logical name it was possible to view, for instance, sources of phpMyAdmin. Now with each logical name having its own virtual host such a possibility is eliminated. These files are customized using templates. More on config file template customization read in Appendix C of Parallels H-Sphere Installation Guide. /hsphere/local/config/httpd/sites/ Comments: This directory contains files for user virtual hosts. A link to this directory is included to the configuration directory of Apache 2.2. This means that configuration files of user virtual host are common for the two Apache versions. Syntactical differences in directives between 1.3 and 2.2 versions are leveled by mod_macro module introduced in Parallels H-Sphere 3.1 and up, i.e. macros are used instead of configuration directives. mod_macro is a third-party module to the Apache Http Server distributed with a BSD-style license like Apache. It allows the definition and use of macros within Apache runtime configuration files. The syntax is a natural extension to apache htmllike configuration style. Macros are placed to ./macro of the Apache configuration directory. Macros for Apache 1.3 are different from those for Apache 2.2. System Packages 321 Web Statistics Software Apache 2.2.x General web statistics is gathered using general mod_log_config and mod_logio modules. mod_log_config is patched to provide logging to the server log even if custom logs are redefined at the virtual host level. For this purpose, AlwaysServerLogs directive is added. Apache 1.3.x General web statistics is gathered using the mod_psoft_traffic apache module. Apache Logs and Web Traffic Calculation in Parallels H-Sphere Apache logs are located in the /hsphere/local/var/httpd/logs/ directory. Also, each hosted Web domain has its own logs in the /hsphere/local/home//logs// directory (see Web traffic calculation (on page 143)). There are two types of Web traffic calculation in Parallels H-Sphere:  third-party traffic calculation - Parallels H-Sphere writes traffic log files to each domain's directory to make them available for third-party log analyzers: Webalizer, Modlogan, and AWStats  Parallels H-Sphere built-in traffic calculation - Parallels H-Sphere provides its own mechanism of traffic calculation used in billing. Please refer to a separate section on Web traffic calculation and log rotation (on page 143). Log Rotate Config File /hsphere/local/config/httpd/rotatelog.cfg - log rotate config file which includes all log confs located in the /hsphere/local/config/httpd/logrotate_conf/ directory:  .transferlog.conf - config file for transfer log rotation for a domain  .errorlog.conf - config file for error log rotation for a domain  .agentlog.conf - config file for agent log rotation for a domain  .referrerlog.conf - config file for referrer log rotation for a domain 322 System Packages Apache Suexec Parallels H-Sphere WebBox Apache suexec is configured to run users' CGI scripts only within the /hsphere/local/home/ directory, recursively. Thus, a user may run his/her own cgi scripts only if he/she has fourth nesting level within the Parallels HSphere user home directory, for example, /hsphere/local/home/user_home1. Parallels H-Sphere PHP PHP is assembled into separate Parallels H-Sphere packages: Package Description hsphere-php4-1x- libphp4 for Apache 1.3.x hsphere-php4-2x- libphp4 for Apache 2.2.x hsphere-php4-cgi- CLI and CGI php4 binaries hsphere-php4-pear- PEAR for PHP4 hsphere-php4-plugins- Set of plugins, their confs, which may work in pair with CLI, CGI or libphp4 hsphere-php5-1x- libphp5 for Apache 1.3.x hsphere-php5-2x- libphp5 for Apache 2.2.x hsphere-php5-cgi- CLI and CGI php4 binaries hsphere-php5-pear- PEAR for PHP5 hsphere-php5-plugins- set of plugins, their confs, which may work in pair with CLI, CGI or libphp5 In this section: Configuring PHP from the Interface ................................................................... 323 PHP Components.............................................................................................. 323 Objects in PHP 5 ............................................................................................... 323 PHP Test Page ................................................................................................. 324 Customizing php.ini Configuration File .............................................................. 324 PHP Modules Installed with Parallels H-Sphere PHP Packages........................ 324 Configuring PHP Safe Mode ............................................................................. 329 Adding PHP Extensions .................................................................................... 330 System Packages 323 Configuring PHP from the Interface In Parallels H-Sphere 3.1+ administrators have more capacity in configuring PHP while users can choose between PHP 4 and 5. Please refer to the section on Apache in Parallels H-Sphere 3.1+ (on page 311) where this functionality is described. PHP Components Ldap Ldap support has been included to php-core, which is one of the reasons why horde may start to slow down when sending mail. It happens because horde is trying to connect to available ldap servers that are very slow by themselves. Pear Another important peculiarity of the new PHP packages is support of pear. To view which packages from pear repository have been installed, run: /hsphere/shared/phpX/bin/pear list To view the list of all pear packages available in the repository, run: pear list-all To check which pear packages need to be upgraded, run: pear list-upgrades To upgrade all pear packages installed, run: pear upgrade-all Pecl As for the PECL repository, 2 packages from it (Fileinfo and SQLite) have been included to PHP4 and one (Fileinfo) to PHP5. In PHP5, SQLite is supported from phpcore. Objects in PHP 5 PHP5 has undergone some principal changes in the way it works with objects. That is why some programs that work fine with PHP4 may not work with PHP5. To ensure PHP5 support, all third-party products included to Parallels H-Sphere have been updated to the latest available version. 324 System Packages PHP Test Page New PHP packages have been assembled to perfectly fit mail web-interfaces, and horde in particular. This means that PHP test page can be obtained from http://horde/test.php. Here, pay attention to memory_limit value. We recommend that it is either -1 (disabled) or 8 MB. Customizing php.ini Configuration File If you want to customize PHP config files for PHP 4 and PHP 5, please refer to Appendix C. Customizing Server Configuration Files By Means of Templates of Parallels H-Sphere Installation Guide. PHP Modules Installed with Parallels H-Sphere PHP Packages Standard PHP Installation has the following modules enabled: PHP extensions php4 before 4.4.4 php5 4.4.4+ before 5.1.6 5.1.6+ System Packages bcmath bz2 calendar ctype curl date dba dbase dbx dom domxml exif fileinfo filepro ftp gd gettext gmp hash iconv imap ldap libxml mbstring mcal mcrypt so so so so so core so core so so so so core core core core so so so so - - core core core core core core so so so so so so - - - - core core so so - - so so - so so so so so so so so * so core so core so core so core so core so core so so so so - - core core so so so so so so so so core so core so - - core core core core core core so so - * so core so core 325 326 System Packages mhash mime_magic mnogosearch mysql mysqli ncurses odbc openssl overload pcntl pdf pcre PDO pgsql posix pspell Reflection session shmop SimpleXML soap sockets SPL sqlite standard swf so core so core core core core core so so so so so so so so - - - so so so so so so so so so core core core core core core - * so so so so so so - - core core core core - - core core so so so so core core core core so so so so - - core core core core core core so so so so - - core core - - so so core core so core - - core core so so core so core core core core removed - - - System Packages sysvmsg sysvsem sysvshm tokenizer xml xmlrpc xmlreader xmlwriter xsl xslt yp zip zlib so so so so so so so so so so so so core core core core core core core core so so so so - - core core - - core core - - core core so so - - so so - * so core - - core core core core 327 328 System Packages Detailed information on PHP modules find in PHP Manual, http://www.php.net/manual/en/ Notes:  mcal extension has been moved to the PECL repository (http://pecl.php.net/) and is no longer bundled with PHP as of version 5.0.0.  yp extension has been moved to the PECL repository and is no longer bundled with PHP as of version 5.1.0. filepro extension has been moved to the PECL repository and is no longer bundled with PHP since version 5.2.0.   overload extension: see the page http://www.php.net/manual/en/language.oop5.overloading.php for more information. PHP Modules Default Location To check php modules default location, run: # /hsphere/shared/php//bin/php-config --extension-dir This directory is linked to hsphere catalogue structure /hsphere/shared/apache/libexec/phpext To list installed so-modules, run: # ls /hsphere/shared/apache/libexec/phpext/*.so Enabling/Disabling PHP Modules Modules are added one by one with ini-files of the same name that can be found in /hsphere/local/config/httpd/php/php.d If an ini-file contains extension=extname.so line, php at startup loads a corresponding extension module. Mind, any text following an unquoted semicolon ";" is ignored, thus the module indicated in the line; extension=extname.so won't load. At updates coming after hsphere-php4-4.4.4-2 ini-files are not overwritten (as in earlier versions), but remain unchanged. Only for extensions that do not have corresponding ini-file, ini-files are created according to the procedure above. php.info php.info gathers info on php core, modules, apache environment etc. You can run it as console command: /hsphere/shared/php4/bin/php-cli -i |less or screen its output at Error! Hyperlink reference not valid. System Packages 329 Configuring PHP Safe Mode Important: PHP safe mode is not supported, you can use it at your own risk. PHP safe mode is turned off by default in the original Parallels H-Sphere configuration. To turn it on, set safe_mode=On in the php.ini file (usually, in the /usr/local/lib directory). Please note that php.ini must be customized by means of the respective custom config file template.  To use default Parallels H-Sphere configuration for PHP with safe mode on: 1. Take the default php.ini installed with standard Parallels H-Sphere PHP packages. 2. Turn the safe mode on. 3. Copy that file to the PHP installation directory (usually, /usr/local/lib). Read more on PHP safe mode configuration in PHP documentation (http://www.php.net/manual/en/features.safe-mode.php#ini.safe-mode). To turn the safe mode off for an individual account, edit/add the following directives in the /hsphere/local/config/httpd/httpd.conf Apache configuration file on the Web server. php_admin_flag safe_mode off php_admin_value upload_tmp_dir "/tmp" php_admin_value session.save_path "/tmp" php_admin_flag safe_mode off php_admin_value upload_tmp_dir "/tmp" php_admin_value session.save_path "/tmp" To have IMP Horde web mail (on page 162) working when the safe mode is on, set the following directive in /hsphere/local/config/httpd/httpd.conf on the Web server and make changes in the respective custom configuration file template): php_admin_flag safe_mode off php_admin_value upload_tmp_dir "/tmp" php_admin_value session.save_path "/tmp" php_admin_flag safe_mode off php_admin_value upload_tmp_dir "/tmp" php_admin_value session.save_path "/tmp" 330 System Packages To configure Webshell 4 (on page 136) so that it would work with the safe mode globally on: php_admin_flag safe_mode off php_admin_value upload_tmp_dir "/tmp" php_admin_value session.save_path "/tmp" php_admin_flag safe_mode off php_admin_value upload_tmp_dir "/tmp" php_admin_value session.save_path "/tmp" Restart Apache (on page 60) after performing necessary modifications. Adding PHP Extensions PHP 4 and PHP 5 packages include almost all commonly used extensions. So, before you start re-compiling PHP, make sure that an extension you need to add is indeed absent. See the list of modules included in PHP 4 and PHP 5 (on page 324). In this section: Compilation Requirements ................................................................................ 330 Adding New Extensions..................................................................................... 331 Adding PEAR Modules ...................................................................................... 331 Adding PECL Modules ...................................................................................... 331 Enabling/Disabling Built-in PHP Modules .......................................................... 332 Compilation Requirements Before the compilation, check that the following libraries are installed:  autoconf  automake  libtool  zlib-devel  mysql-devel  postgresql-devel Other required libraries are listed in the documentation to respective modules. Please also take into account that PHP 4 and PHP 5 have different module structures. For example, the domxml module of PHP 4 is absent in PHP 5. System Packages 331 Adding New Extensions PHP packages are built from modules. To include a new module, use phpize in the following way: # tar zxf your_module.tgz # cd your_module # /hsphere/shared/php4/bin/phpize # ./configure --with-php-config=/hsphere/shared//bin/phpconfig # make # make install is php4 or php5, depending on PHP version. To find out where a new extension is compiled to and where all other PHP extensions are located, run: # /hsphere/shared//bin/php-config --extension-dir Aslo you can use additional options in configuration string, for example: ./configure --with-php-config=/hsphere/shared/php4/bin/php-config -with-mssql=/usr/local/freetds --enable-msdblib Adding PEAR Modules To install PEAR modules, run: # /hsphere/shared//bin/pear install your_module Read the PEAR Command line installer (http://pear.php.net/manual/en/installation.cli.php) documentation for details. Adding PECL Modules PECL modules can be installed either by phpize or by pear. See Installation of PECL extensions (http://www.php.net/manual/en/install.pecl.php) in PHP Guide. 332 System Packages Enabling/Disabling Built-in PHP Modules Modules that are installed with PHP packages are enabled by default.  To disable (or enable) a module: 1. Go to the directory where respective .ini file for a module is located: # cd /hsphere/local/config/httpd//php.d/ Here, is php4 or php5. 2. Open the .ini file for edit. See the list of PHP modules (on page 324). 3. Comment the line extension=.so to disable the module: ; extension=.so Uncomment this line to enable the module. 4. Restart Apache (on page 60) on the Web server to apply changes. Parallels SiteStudio Packages Parallels SiteStudio is installed in two separate Parallels H-Sphere packages:  hsphere-sitestudio-core- hsphere-sitestudio-templates- To install Parallels SiteStudio packages, go to /hsphere/install and run: make ss-install This command launches the script which downloads and installs the necessary packages (e.g. xorg-x11-libs) and then installs Parallels SiteStudio. Imaker is run under the imaker user (not root!). If previous Parallels SiteStudio version was installed from a .tgz archive, the new one is installed over it without uninstalling the older version. CHAPTER 22 Load Balancing It is possible to add load balanced (LB) Web and mail clusters to Parallels H-Sphere. Load balancing implies balancing server traffic amongst multiple computers (LB cluster) which Parallels H-Sphere regards and operates with as a single server. Load balanced cluster solution in Parallels H-Sphere requires 4 or more physical servers:  Load Balancer: any solution like Cytrix® NetScaler (http://www.citrix.com/English/ps2/products/subfeature.asp?contentID=22314) for balancing traffic across the web/mail servers. Load Balancer directs traffic to another server if the first one is currently overloaded. It can also allow the service to continue even if one of the servers is down.  One master and one or more slave servers form a load balanced Web/mail cluster. All these servers are being added to Parallels H-Sphere as physical servers, with all related packages installed, but Parallels H-Sphere logical servers are created only on master servers, and Parallels H-Sphere operates with load balanced cluster only via master server.  NAS (Network Attached Storage): shared storage for master and slave servers. NAS is a highly reliable server with enough space for storing data. Web/mail content directories are mounted to the NAS where the content is actually stored. Web and mail servers can jointly use one NAS or have their own NAS for Web and for mail. Figure 1: Simple Load Balanced system with one Web cluster: 334 Load Balancing Figure 2: More complex Load Balanced system with two mail and two web clusters: Load Balancing 335 Load Balancers You need to purchase, install and configure any load balancer solution, for example, Cytrix® NetScaler (http://www.citrix.com/English/ps2/products/subfeature.asp?contentID=22314). This task is beyond the scope of Parallels H-Sphere documentation. Supported NAS The following file storage systems (on page 352) are supported by Parallels H-Sphere: NAS Notation Supported in Parallels H-Sphere Generic Linux NFS (on page 342) UNIX 3.0 RC 1 and up RedHat GFS (on page 342) UNIX 3.0 RC 4 and up NetApp (http://www.netapp.com/prod ucts/filer/) NET_APP 2.3 and up to 2.5 3.0 RC 1 and up BlueArc (http://www.bluearc.com/) BLUE_ARC 2.4.3 Patch 10 and up 2.5 Beta 5 and up EMC Celerra (http://www.emc.com/product s/networking/servers/index.js p) EMC_CELERRA 2.4.3 Patch 10 and up 2.5 Beta 5 and up Note: All Parallels H-Sphere customers will be recommended to choose shared Linux NFS as the most simple and reliable solution. Load Balanced Cluster Loab balanced cluster consists of one master and one or more slave servers regarded by Parallels H-Sphere as a single server.  Master and slave servers are added to Parallels H-Sphere as physical servers.  Master-slave relations between these servers are set in admin CP.  Only master server is added as Web/mail logical server to Parallels H-Sphere. CP communicates only with master server. 336 Load Balancing  Requests are passed to external IPs routed by the load balancer. Load balancer distributes requests evenly across the master and slave servers (internal IPs corresponding to external IP). For this purpose, NAT must be properly configured on load balanced cluster servers.  Master and slave server share the same Parallels H-Sphere related directories where all user content, scripts, and the majority of Parallels H-Sphere related binaries are located. These directories are actually stored on the NAS and mounted from master and slave servers via NFS.  Along with shared storage, master and slave servers have their own unique IPspecific logs and configs which are synchronized by special cron scripts run on these servers. See load balanced cluster scheme with generic Linux NFS shared storage (on page 336). In this chapter: Implementation of Load Balanced Cluster in Parallels H-Sphere ....................... 336 Load Balancing Support in Parallels H-Sphere .................................................. 342 Installing Load Balanced Web/Mail Clusters in Parallels H-Sphere ................... 342 Quota Managers................................................................................................ 352 Implementation of Load Balanced Cluster in Parallels H-Sphere This section describes load balanced Web/mail cluster scheme for generic Linux NFS (on page 342) NAS. In this section: Load Balanced Cluster in CP ............................................................................ 337 Distribution of Requests Across Load Balanced Cluster ................................... 337 Shared Content ................................................................................................. 337 Specific Master/Slave Content .......................................................................... 338 Synchronization Between Master and Slave Servers ........................................ 338 Traffic Calculation ............................................................................................. 339 Load Balanced Cluster Map .............................................................................. 340 NAT Configuration for Load Balanced Clusters ................................................. 341 Load Balancing 337 Load Balanced Cluster in CP  Master and slave servers are added to Parallels H-Sphere as physical servers.  Master-slave relations between these servers are set in admin CP.  Only master server is added as Web/mail logical server to Parallels H-Sphere. CP communicates only with master server. Distribution of Requests Across Load Balanced Cluster Parallels H-Sphere regards Web or mail load balanced cluster as a single server. Requests are passed to external IPs routed by the load balancer. Load balancer distributes requests evenly across the master and slave servers (internal IPs corresponding to external IP). Shared Content Master and slave servers share the same /hsphere directory mounted by NFS to the /filer/_/ directory on the NAS where load balanced cluster content is actually stored. Here, is mail or web, and is cluster id - there may be multiple load balanced clusters mounted to the NAS: 01, 02, ... (See the illustration (on page 333) for 2 Web and 2 mail clusters.) All user content, scripts, and the majority of Parallels H-Sphere related binaries are installed into the /hsphere directory and shared by master and all slaves. Follow the Adding Load Balanced Clusters on Shared Linux NFS (on page 342) instructions to learn how to correctly mount the shared storage on the NAS to the master and slave servers. 338 Load Balancing Specific Master/Slave Content Along with the common shared storage, master and slave servers have their own Parallels H-Sphere specific (Apache, FTP) and IP-dependent (network) logs and configuration:  Both master and slave servers have unique Apache logs stored locally in the /var/log/hsphere/httpd directory instead of the default /hsphere/local/var/httpd/logs directory.  On the master server, Apache, FTP and network configuration is located in the /hsphere directory (which is a mountpoint to the NAS and is common for the master and the slave servers): /hsphere/local/config/httpd/ /hsphere/local/config/ftpd/ /hsphere/local/network/ On slave servers, however, this data is unique and is stored locally in the /etc/hsphere directory: /etc/hsphere/httpd/ /etc/hsphere/ftpd/ /etc/hsphere/network/ Parallels H-Sphere updater running with the hspackages slaves=web|mail|all option creates the /etc/hsphere directory data on slave servers. Synchronization Between Master and Slave Servers The special cron script /hsphere/shared/scripts/cron/lb_sync.sh runs each minute on each slave server to synchronize data on master and slave servers. It parses and synchronizes:  User Apache/ProFTPd config files /etc/hsphere/[httpd|ftpd]/sites/*.conf, and /etc/hsphere/network/ips  the /etc/passwd, /etc/shadow, /etc/group files. Load Balancing 339 Traffic Calculation User logs are located in the /hsphere/local/home//logs/domain.com/ directory. On master server, log filenames look like: {domain.name} referrer_log access_log error_log Slave servers write the following logs: {domain.name}_SRV-N referrer_log_SRV-N access_log_SRV-N error_log_SRV-N where N is slave server id: 1, 2, ... The /hsphere/shared/scripts/cron/cron-rotate.pl script has been adapted to calculate statistics on load balanced cluster. It runs on master and slave servers by the following scheme:  on slave servers (e.g., 1:30am):  synchronizes logrotate conf files on master and slaves: It parses log rotate configs in the /hsphere/local/config/httpd/logrotate_confs/ directory on the master server. They point to the user logs located in the /hsphere/local/home//logs/domain.com/ directory. On master server, log filenames look like: {domain.name} referrer_log access_log error_log Slave servers write the following logs: {domain.name}-SRV-N referrer_log-SRV-N access_log-SRV-N error_log_SRV-N where N is slave server id: 1, 2, ... cron-rotate.pl merges data and synchronizes respective master and slave logs.   rotates logs on slave servers  restarts Apache on master server (e.g., 2:00am):  rotates logs on the master  restarts Apache  merges master and slave logs  launches log analyzers (Webalizer, AWStats, ModLogAn) 340 Load Balancing Load Balanced Cluster Map The following two files construct load balanced cluster map. At the moment, they need to be created manually on master and slave servers:  /hsphere/local/config/lb.map - created on the master server and has the following format: ||...| The lines of the same format should be also added for each dedicated IP bound on the cluster: ||...|  /etc/hsphere/lb.id - created on both the master and slave servers and contains the following line: | where is mail or web; is LB server id: 0 for master, 1 for the first slave, 2 for the second slave, etc. For example, for slave server with in LB Web cluster the lb.id file will look like: web|2 Load Balancing 341 NAT Configuration for Load Balanced Clusters To configure load balanced Web/mail cluster with NAT, you must have NAT turned on (on page 29) in Parallels H-Sphere and put external Web/mail server IP routed by the Load Balancer into correspondence with the master server's internal IP. For example, for a load balanced Web cluster with one master and 4 slave servers, where the master Web server's internal IP 192.168.0.100 corresponds to the external IP 12.34.56.100 bound to the Load Balancer.  In the ~cpanel/shiva/psoft_config/ips-map.xml file on the CP server there should be the following record: . . . . . .  All dedicated IPs on the master server must be also associated with corresponding IPs on the Load Balancer and similar records must be added to the ip-map.xml file:  Also, you should have external IP in the E.Manager -> DNS Manager -> Service Zone menu in admin CP. For example: www.test.com 3600 IN A 12.34.56.100 mail.test.com 3600 IN MX 12.34.56.111 342 Load Balancing Load Balancing Support in Parallels HSphere This document explains functionality of the scripts that enable distribution of load balance between Apache and Virtual FTP servers.  apache-confsynch.pl accounts for synchronization of Apache config files on slave servers. Amount of slave servers and their IDs are set at master server in the /hsphere/local/config/slaves.conf file. The script, also, creates need_restart.txt on each slave to mark it as liable to restart.  apache-need-restart.pl runs on slave servers, checks if need_restart.txt is available there and marks them as liable to restart. In other words this script servers as a layer between LB apache restart and standard apache-restart.   apache-reconfig.pl is a modification of a standard apache-reconfig script/file(?) that is executed on slaves and is only different from it in that it sets required level of restart for slaves (either gracefull or force). apache-repair.pl is a modification of a standard apache-repair.pl script and is only different in that it sets exclusive lock for /etc/passwd, /etc/shadow, /etc/groups so to ensure these files are not locked by rsync and so a user can be started. Otherwise, all files will be marked as bad. ftp_anlz.pl gathers and analyses statistics  ftp_anlz_user.pl gathers and analyses user statistics.  ftp-confsynch.pl accounts for the same as apache-confsynch.pl on Virtual FTP severs. ftp-need-restart.pl accounts for the same as apache-need-restart.pl on Virtual FTP severs. ftp-restart.pl is the same as Apache, but for Virtual FTP     master-ipsynch.pl runs on a master server and formats data for slave servers so IPs are up according to IP mapping set in the /hsphere/local/config/map_table.txt file on each slave.  slave-ipupdate.pl puts up IPs formed by the master-ipsynch.pl script. As of now Apache and Virtual FTP config files synchronization is executed on master server, yet it is expected to be moved onto slave servers. Installing Load Balanced Web/Mail Clusters in Parallels H-Sphere Load balanced cluster solution requires 3 or more physical servers: Load Balancing 343  Load Balancer: any solution like Cytrix® NetScaler (http://www.citrix.com/English/ps2/products/subfeature.asp?contentID=22314) for load balancing across the web/mail servers. Load Balancer directs traffic to another server if the first one is currently overloaded.  NAS (aka Filer): Server/client shared storage solution for web/mail content. NAS may be installed on the same server with load balancer or on a separate server. Also, Web and mail servers can jointly use one NAS or have their own NAS one for Web and one for mail. In this documentation we consider the following NAS's:   Generic Linux NFS  NetApp Filer hardware  RedHat GFS At least two boxes (master and slave) for web/mail servers. Load balanced solution implies one master server and one or more slave servers.  To create Web/mail load balanced clusters integrated into Parallels HSphere: 1. Install and configure Load Balancer (on page 343) 2. Prepare NAS (on page 344) 3. Prepare master and slave Web/mail boxes (on page 349) 4. Install Parallels H-Sphere to load balanced Web/mail clusters (on page 351) In this section: Step 1. Install and Configure Load Balancer ..................................................... 343 Step 2. Prepare NAS ........................................................................................ 344 Step 3. Prepare Master and Slave Web/Mail Boxes .......................................... 349 Step 4. Install Parallels H-Sphere to Load Balanced Parallels H-Sphere Clusters 351 Step 1. Install and Configure Load Balancer Purchase, install and configure load balancer solution like Cytrix® NetScaler. 344 Load Balancing Step 2. Prepare NAS Follow procedures below for:  NetApp hardware (on page 342)   Linux NFS shared storage (on page 342) RedHat GFS (on page 342) In this section: NetApp Hardware .............................................................................................. 345 Generic Linux NFS ............................................................................................ 346 RedHat GFS...................................................................................................... 348 Load Balancing 345 NetApp Hardware 1. Purchase NetApp NAS from www.netapp.com, install and configure the NAS according to the NetApp Documentation (http://www.netapp.com/products/filer/). Create volumes/qtrees on the box where NetApp NAS is to be installed. 2. Configure your NetApp NAS to add load balanced cluster in Parallels H Sphere (read the NetApp Manual at http://ecserv1.uwaterloo.ca/netapp/man/ for commands): 1. Telnet to the NetApp NAS: telnet Here, is the NetApp NAS IP. 2. Get the list of the NAS partitions with the qtree command: # qtree 3. To enable disk quota management, export the /etc directory on the NetApp NAS and allow to mount it only from the CP box: # exportfs -o access=,root=,rw= /etc Here, is the CP server IP. 4. To enable user disk space management on the web/mail servers, export the user storage directory on the NetApp NAS allow to mount it from the physical web/mail boxes: # exportfs -o access=:[::...],root=:[:...],rw=:[:...] Here, :[::...] is the list of master and slave web/mail server IPs separated with colon (:), is the user storage directory. 5. Exit telnet session on the NetApp NAS. 3. Prepare NetApp NAS to Work With Parallels H-Sphere 1. Grant rsh access to the NetApp NAS from the CP box to root and cpanel user. 2. Grant nfs access to the /etc directory for the CP box in rw mode. 3. Grant nfs access to the home directory on the storage partition (e.g., /vol/vol0/home) for the CP box in rw mode with root privileges (e.g., access=192.168.0.9:192.168.0.10, root=192.168.0.8:192.168.0.9:192.168.0.10). 4. On CP server, set the QUOTA_MANAGER property in ~cpanel/shiva/psoft_config/hsphere.properties to support NetApp quota manager on LB cluster: QUOTA_MANAGER = NET_APP More about external quota manager support in Parallels H-Sphere (on page 352). 346 Load Balancing Generic Linux NFS Important: For correct load balanced cluster implementation, NFS must be of version 3. 1. Login as root to a new Linux server assigned for NAS and create a separate partition for shared file storage. This partition must be on a separate hard drive on a separate controller and must not be /var or /usr. We recommend naming it /filer to avoid possible confusion. 2. Install/update the quota-3.x package from the following location: # rpm -Uvh http://download.hsphere.parallels.com/shiv/HS//sysuti ls/quota-3.xx-x.i386.rpm where is a mnemonic code for operating system supported by Parallels H-Sphere (see OSCODE notation in Appendix D of Parallels H-Sphere Update Guide). Important: The quota package includes NFS support, which is essential for load balanced cluster implementation. Generic quota package has NFS support disabled by default! 3. Add the "usrquota" option to the /filer partition in /etc/fstab: LABEL=/filer /filer ext3 defaults,usrquota 1 1 To apply changes, run: # mount -o remount /filer # quotacheck -m /filer # quotaon /filer 4. On the /filer partition, create directories for load balanced cluster file storage: # mkdir -p /filer/_/hsphere where is web or mail, and is a cluster id (there may be multiple clusters mounted to the same NAS). For example, for the first Web cluster it will be /filer/web_01/hsphere. 5. Stop all services except ssh, portmap, and nfs related services. Check the status by the chkconfig command: # chkconfig --list 6. To enable user disk space management on the web/mail servers, export the user storage directory on the generic Linux NAS. For this, add the following lines for all clusters to the /etc/exports file on the NAS server: Load Balancing 347 /filer/_/hsphere (rw,async,no_wdelay,insecure,no_root_squash) /filer/_/hsphere (rw,async,no_wdelay,insecure,no_root_squash) /filer/_/hsphere (rw,async,no_wdelay,insecure,no_root_squash) ... To apply changes, run: # exportfs -a 7. Skip this step for mail server clusters. Edit the /etc/init.d/nfs file. Find the line with daemon rpc.rquotad and add the -S option to the end of the line, like this: daemon rpc.rquotad $RPCRQUOTADOPTS -S After that, restart NFS: # chkconfig --level 345 nfs on # /etc/init.d/nfs restart Important: NFS configuration on the NAS may differ depending on the hardware parameters, the number of clusters, quota and load on the servers. To properly configure NAS please refer to the following guides: https://www.redhat.com/f/pdf/rhel4/NFSv4WP.pdf http://www.citi.umich.edu/projects/nfs-perf/results/cel/dnlc.html http://www.oreilly.com/catalog/nfs2/chapter/ch15.html 348 Load Balancing RedHat GFS  To prepare NAS for RedHat GFS filer (http://www.redhat.com/software/rha/gfs/): 1. Install and configure RedHat GFS cluster on a filer according to the following documentation: http://www.redhat.com/docs/manuals/csgfs/browse/rh-gfs-en/index.html http://www.redhat.com/docs/manuals/csgfs/browse/rh-cs-en/index.html http://www.tldp.org/HOWTO/LVM-HOWTO/index.html 2. Setup GFS file system type on a logical volume on the filer, like this: # gfs_mkfs -p lock_type -t cluster_name:gnbd_device -j 2 /dev/vg_name/lv_name where lock_type is a GFS locking type, cluster_name is a GFS cluster name, gnbd_device is a GNBD device name, vg_name is a volume group name, and lv_name is a logical volume name. Further on in the document we will use the following example: # gfs_mkfs -p lock_dlm -t alpha_cluster:gfs1 -j 2 /dev/vg01/lv01 3. Start GNBD server: # gnbd_serv Upon successful start, you'll get the following output: gnbd_serv: startup succeeded 4. Export logical volume with GFS file system: # gnbd_export -d /dev/vg01/lv01 -e gfs1 You should get the following output: gnbd_clusterd: connected gnbd_export: created GNBD gfs1 serving file /dev/vg01/lv01 Load Balancing 349 Step 3. Prepare Master and Slave Web/Mail Boxes Before you install Parallels H-Sphere packages to master and slave servers, please make sure to meet the following requirements for correct load balancing:  All boxes in LB cluster must have the same OS version installed on. For RedHat GFS, all servers must be RedHat servers. In case of generic Linux NFS or NetApp, master/slave servers under FreeBSD are supported in HS 3.0 RC 4 and up.  The /hsphere directory on a Web server should not be created a separate partition! The operations on master and slave servers are made under root. 1. Create the /hsphere directory on the master and all slave servers: # mkdir /hsphere 2. If you are using GFS, run on each master and slave servers: 1. Load kernel module: # modprobe gnbd 2. Import GFS file system from the NAS server: # gnbd_import -i FILER_NAME where FILER_NAME is the NAS server domain name. You should get the following output: gnbd_import: created gnbd device gfs1 gnbd_monitor: gnbd_monitor started. Monitoring device #0 gnbd_recvd: gnbd_recvd started 3. Mount the storage directory on the NAS server to /hsphere directory on the master and all slave servers. a For RedHat GFS: Add the following mountpoint to /etc/fstab on the master and all slave servers: /dev/gnbd/gfs1 /hsphere gfs defaults 0 0 Mount the GFS logical volume on the master and all slave servers: # mount -t gfs /dev/gnbd/gfs1 /hsphere b For generic Linux NFS or NetApp: Add the following mountpoint to /etc/fstab on the master and all slave servers: :/filer/_/hsphere /hsphere nfs defaults,nfsvers=3,rsize=32768,wsize=32768 0 0 For mail server cluster, also add these mountpoints on all servers: :/filer/_/users /var/qmail/users nfs defaults,nfsvers=3 0 0 :/filer/_/control /var/qmail/control nfs defaults,nfsvers=3 0 0 To mount the directory, run: 350 Load Balancing # mount -a && mount 4. On the master server, create the /hsphere/local/config/lb.map file of the following format: ||...| Note: The lines of the same format should be also added for each dedicated IP bound on the cluster: ||...| 5. On every master and slave server, create the /etc/hsphere/lb.id file with the line of the following format: | where is mail or web; is LB server id: 0 for master, 1 for the first slave, 2 for the second slave, etc. For example, for slave server with in LB Web cluster the lb.id file will look like: web|2 6. Generate SSH keys to access the master's root from each slave server without password. 1. Log into each slave server as root. 2. Create public key on each slave server: # ssh-keygen -t dsa 3. Log from each slave server to the master server as root and insert the contents of the /root/.ssh/id_dsa.pub file from each slave server into the /root/.ssh/authorized_keys2 file of the master server. 4. Log from the each slave server into the master server as root once again to ensure slave servers are able to log into the master without password: # ssh root@ Answer yes to all prompts. This will add the master server to the list of known hosts (/root/.ssh/known_hosts) of a slave server. After that, load balancing synchronization scripts will work without password prompts. 7. Important: To make sure Parallels H-Sphere related data is correctly synchronized on master and slave servers, add time synchronization (on page 33) to the master and slave servers' crontabs. Load Balancing 351 Step 4. Install Parallels H-Sphere to Load Balanced Parallels H-Sphere Clusters 1. Log into Parallels H-Sphere admin CP (it is assumed you have Parallels H-Sphere 3.0 and up already installed). 2. Add master and all slave servers as physical servers to Parallels HSphere. 3. Set master-slave relations between master and slave physical servers. This is described in the section Load Balanced Server Clusters of Parallels H-Sphere Service Administrator Guide. 4. Add Web/mail logical server only to master physical server. Do not add logical servers to slave servers! In logical server options you need to set Load Balancer Server Parameters:  File Server Type: file storage OS type (on page 333), like UNIX for generic Linux NFS  File Server: file storage volume location, like :/filer/_/ in the above example  File Path: (optional) file storage path to Parallels H-Sphere installation directory, like /filer/_/hsphere in the above example  File server Volume ID: file storage volume ID, like _ in the above example. 5. For mail LB cluster, it is required to configure Horde Webmail frontend (on page 167) to use external Web server and external MySQL database server, and also to configure SpamAssassin (on page 195) to external MySQL database. 6. Configure NAT for LB Web/mail clusters Parallels H-Sphere Control Panel works with only one logical server (that is, master server) for each load balanced Web cluster. To configure load balanced Web/mail cluster with NAT, you must have NAT turned on (on page 29) in Parallels H-Sphere and put external Web/mail server IP routed by the Load Balancer into correspondence with the master server's internal IP. For example, for a load balanced Web cluster with one master and 4 slave servers, where the master Web server's internal IP 192.168.0.100 corresponds to the external IP 12.34.56.100 bound to the Load Balancer. In the ~cpanel/shiva/psoft_config/ips-map.xml file on the CP server there should be the following record: . . . . . .  352 Load Balancing  All dedicated IPs on the master server must be also associated with corresponding IPs on the Load Balancer and similar records must be added to the ip-map.xml file: Also, you should have external IP in the E.Manager -> DNS Manager -> Service Zone menu in admin CP. For example: www.test.com 3600 IN A 12.34.56.100 mail.test.com 3600 IN MX 12.34.56.111  7. Download the latest Parallels H-Sphere updater of Parallels H-Sphere 3.0 RC 1 and up and follow the instructions on adding new servers into Parallels H-Sphere to install Parallels H-Sphere related packages only on master server. 8. In the updater's command line, run one of the following commands to complete installation and configuration on slave servers: hspackages slaves=web hspackages slaves=mail hspackages slaves=all More about updater options read in Parallels H-Sphere Update Guide. Quota Managers Parallels H-Sphere supports quota management for third party file storage systems like BlueArc or NetApp for load balanced Web/mail clusters (on page 333). If not specified otherwise, Parallels H-Sphere uses generic Linux/FreeBSD server quota manager. To set a third party NAS quota manager, add the QUOTA_MANAGER variable in ~cpanel/shiva/psoft_config/hsphere.properties, for example, like this: QUOTA_MANAGER = BLUE_ARC The following quota managers are supported:  UNIX - generic Linux/FreeBSD quota manager (default)  NET_APP - NetApp quota manager (http://www.netapp.com/products/filer/)  BLUE_ARC - BlueArc quota manager (http://www.bluearc.com/)  EMC_CELERRA - EMC Celerra quota manager (http://www.emc.com/products/networking/servers/index.jsp) CHAPTER 23 Resources Migration This chapter explains how to migrate resources into Parallels H-Sphere from Parallels H-Sphere and other control panels using XML-structured data. It can also serve as a guide to setting up a large number of Parallels H- Sphere users at a time. You are expected to have an installed and configured Parallels H-Sphere control panel on the target server. Migratable Resources Users can be migrated with the following resources:  User contact and billing info  Domains (with or without DNS)  DNS: custom A, MX, CNAME records; domain vhost aliases; domain aliases with their DNS and mail configuration  Web: settings, FrontPage, CGI, CGIDir, MIME, PHP, SSI, ErrorDoc, ErrorLog, TransferLog, Webalizer, ModLogAn, RefferrerLog, AgentLog, Vhost alias, Directory indexes, Redirect, Urchin3, Urchin4, ASP, ASP.NET, ColdFusion, MSSQLManager Mail: Mailboxes, Autoresponder for mailboxes, Mailforwards, Mailing lists   FTP: resources: virtual hosts, anonymous virtual hosts, virtual host directories with permissions, virtual host users, FTP subaccounts (Unix) MySQL: users, databases with user permissions  PostgreSQL: users, databases   MSSQL: users, logins, databases ODBC: dsn records with params  Crontab: crontab records for users The following resources are NOT YET implemented in XML migration mechanism:  DNS: instant access domain alias  Web: SSL, Shared SSL, MivaEmpresa, MivaCart, osCommerce, PhpBB In this chapter: Migration Procedure .......................................................................................... 354 354 Resources Migration Migration Procedure The migration procedure takes the steps below. In this section: Step 1. Create XML File Containing User Data ................................................. 354 Step 2. Create XML File Containing Reseller Plan Data .................................... 360 Step 3. Prepare The Target Control Panel......................................................... 366 Step 4. Create Reseller Plans ........................................................................... 366 Step 5. Create Resellers ................................................................................... 366 Step 6. Create End Users.................................................................................. 367 Troubleshooting................................................................................................. 367 Step 1. Create XML File Containing User Data Create xml and dtd files to migrate resellers and end users or end users without resellers. If you are moving users from Parallels H-Sphere, do it with the UserInfoExtractor utility as suggested in Creating User Migration XMLs in Parallels H-Sphere (on page 355). If you are moving users from a different control panel, follow the instruction on Creating User Migration XMLs Outside Parallels H-Sphere (on page 359). In this section: Creating User Migration XMLs in Parallels H-Sphere ........................................ 355 Creating User Migration XMLs Outside Parallels H-Sphere ............................... 359 Resources Migration 355 Creating User Migration XMLs in Parallels H-Sphere This document explains how to create XML files with Parallels H-Sphere reseller and end user data for migration to a different Parallels H-Sphere cluster. User info can be obtained and formatted with the UsersInfoExtractor utility executed under Control Panel user (on page 71). UsersInfoExtractor extracts resellers into the migrate_resellers.xml, and their end users separately into migrate_users.xml. UsersInfoExtractor runs with the following parameters:  -resellers - extracts only resellers into the migrate_resellers.xml file: java psoft.hsphere.migrator.UsersInfoExtractor [-force] resellers OPTIONS where OPTIONS include:  -resellersbynames - extract listed resellers: java psoft.hsphere.migrator.UsersInfoExtractor [-force] resellers -resellersbynames ...  -resellersfromfile - extract resellers listed in a plain text file: java psoft.hsphere.migrator.UsersInfoExtractor [-force] resellers -resellersfromfile /home/resellers.txt  -usersbynames - extract resellers for listed individual users: java psoft.hsphere.migrator.UsersInfoExtractor [-force] resellers -usersbynames ...  -usersfromfile - extract resellers for individual users listed in a plain text file: java psoft.hsphere.migrator.UsersInfoExtractor [-force] resellers -usersfromfile /home/users.txt -usersbylserver - extract resellers for all users located on a specified logical server: java psoft.hsphere.migrator.UsersInfoExtractor [-force] resellers -usersbylserver   -users - extracts end users into the migrate_users.xml file. This option is meant by default if both -resellers and -users options are omitted in the command: java psoft.hsphere.migrator.UsersInfoExtractor [-force] [users] OPTIONS where OPTIONS include:  -usersbynames - extract listed end users by usernames: java psoft.hsphere.migrator.UsersInfoExtractor [-force] users -usersbynames ...  -usersfromfile - extract users by usernames listed in a plain text file: java psoft.hsphere.migrator.UsersInfoExtractor [-force] users -usersfromfile /home/users.txt 356 Resources Migration  -resellersbynames - extract users that belong to listed resellers: java psoft.hsphere.migrator.UsersInfoExtractor [-force] users -resellersbynames ... -resellersfromfile - extract users that belong to resellers listed in a plain text file: java psoft.hsphere.migrator.UsersInfoExtractor [-force] users -resellersfromfile /home/resellers.txt   -usersbylserver - extract users located on a certain logical server: java psoft.hsphere.migrator.UsersInfoExtractor [-force] users -usersbylserver Use the force parameter to ignore errors. Error messages will be written to migrate_errors.log. Important: Note that you must specify user and reseller names, not ids! Important: If you are migrating master admin's end users, you just extract them into migrate_users.xml without extracting master admin as reseller. See also:  Sample xml file with reseller data: http://hsphere.parallels.com/HSdocumentation/xmls/migrate_resellers_25.xml  Sample xml file with end user data: http://hsphere.parallels.com/HSdocumentation/xmls/migrate_users_25.xml  Sample dtd file for resellers: http://hsphere.parallels.com/HSdocumentation/xmls/resellers.dtd   Explanations to dtd file for resellers (on page 357) Sample dtd file for end users: http://hsphere.parallels.com/HSdocumentation/xmls/users.dtd  Explanations to dtd file for end users: http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ In this section: DTD Structure of Reseller XML Migration File ................................................... 357 Resources Migration DTD Structure of Reseller XML Migration File Data Type Definitions Here is the DTD structure defined in resellers.dtd: %users_rules; DTD Chart The above structure may be represented graphically in the following chart: resellers / ... reseller | ____________/| / | / / \ / / \ info / \ | administrator zone | | item instantalias Attributes Description  reseller:  login - reseller login  password - reseller password  plan - the plan the reseller is signed up for 357 358 Resources Migration  info (contact/billing signup information): (see signup fields description in the section User Signup Customization of Parallels H-Sphere Customization Guide)     type="_ci_" (contact info) or type="_bi_" (billing info) administrator:  login - reseller admin cp login  password - reseller admin cp password  email - reseller admin email address zone:  name - the name of the reseller service zone  email - email for the reseller service zone (for example, if it is reseller@example.com, it must be set as reseller.example.com) instantalias:  prefix - prefix to be added to instant aliases for this zone (for example, u)  tag - shared IP tag for the instant alias (usually, 2) XML example with reseller data: http://hsphere.parallels.com/HSdocumentation/xmls/migrate_resellers_25.xml Resources Migration Creating User Migration XMLs Outside Parallels H-Sphere This section explains how to format user data for migration from third party hosting systems into Parallels H-Sphere. Use it to:   migrate direct end users, resellers, and resellers' end users; migrate only direct end users if you don't have resellers. Files Create the following files:     resellers.dtd - data type definitions for resellers  example: http://hsphere.parallels.com/HSdocumentation/xmls/resellers.dtd  explanation (on page 357) users.dtd - data type definitions for end users  example: http://hsphere.parallels.com/HSdocumentation/xmls/users.dtd  explanation: http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ migrate_resellers.xml - XML file containing reseller data only  example: http://hsphere.parallels.com/HSdocumentation/xmls/migrate_resellers_25.xml  explanation (on page 357) migrate_users.xml - XML file containing user data only  example: http://hsphere.parallels.com/HSdocumentation/xmls/migrate_users_25.xml  explanation: http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ You may have data for hundreds and thousands of users in the xml file. Alternatively, you may set DTD definitions directly within the XML file: . . . We recommend defining DTD externally, using our latest DTD: DTD files help ensure that all XMLs are formatted the right way. But please note that XML files will be created no matter DTD file exists or not. Warning: If you make a mistake in DTD definitions, migration may fail. 359 360 Resources Migration XML Validation Once you have created the XML, please do the following: 1. Validate the user data xml files with any xml validation software. 2. Make sure the xml file does not contain user with the login "admin". 3. Make sure that mail sections of each user don't contain mail loops. 4. Ensure that the billing period starting date has the MM/DD/YY format. 5. Make sure that in the user tag the value of the login attribute is unique and doesn't begin with a number (this value will be used as the Parallels H-Sphere control panel login name). Now you are ready to create the accounts. Step 2. Create XML File Containing Reseller Plan Data Note: Skip this step if you are migrating only master admin's end users. Create XML files for the reseller plans to be migrated. If you migrate from Parallels HSphere, use the PlanExtractor utility. Otherwise, create plan XML according to our documentation. Please refer to Migrating Plans with XML (on page 361) for details. In this section: Migrating Plans with XML .................................................................................. 361 Resources Migration 361 Migrating Plans with XML Plan settings are stored in XML format, which allows extracting and moving them to other locations. Migratable Plans. Migratable plans include all non-reseller plans, namely: Unix, Windows, Admin, MySQL, E-Mail, Unix Real Server, Windows Real Media. All end user plans, including those of master admin and resellers, are migratable. Migration Tools. Plans are migrated with two Java classes, PlanExtractor and PlanCreator, located in the ~cpanel/shiva/psoft/hsphere/migrator/ directory. 1) PlanExtractor is a Java utility to extract Parallels H-Sphere plans into XML format. Extracted plans are stored in the plans.xml file. 2) PlanCreator is a tool for importing plans to a new CP from the file plans.xml with plans extracted by PlanExtractor. Also, you'll need to place the following files in the ~cpanel/shiva/psoft/hsphere/migrator/ directory:  plans.xml (http://hsphere.parallels.com/HSdocumentation/xmls/plans.xml) - XMLformatted information about plans extracted by PlanExtractor.  plans.dtd (http://hsphere.parallels.com/HSdocumentation/xmls/plans.dtd) - DTD scheme for plans.xml.  migrate_plans.log - messages about errors occurred during plan extraction. In this section: Plan Extractor.................................................................................................... 362 Plan Creator ...................................................................................................... 362 XML Document Structure .................................................................................. 363 XML Elements and Attributes ............................................................................ 364 362 Resources Migration Plan Extractor Log into CP server as cpanel (on page 71) and run PlanExtractor: java psoft.hsphere.migrator.PlanExtractor [-force] -resellername res_name [-plans the list of plan names] [-ids the list of plan ids] Options:  The -force option is used to ignore all possible errors while extracting plans.  The -resellername option requires the username of the reseller whose plans are extracted. To extract plans for master admin, use option -resellername admin.  The -plans option requires names of plans to be extracted for this reseller. If a plan name contains spaces, it must be quoted, e.g.: -plans Unix1 'Reseller 2' WinBest33 If you omit both -plans and -ids, all plans will be extracted.  The -ids option requires IDs of plans to be extracted for this reseller. If you omit both -plans and -ids, all plans will be extracted. Examples: java psoft.hsphere.migrator.PlanExtractor -plans silver 'unix gold' java psoft.hsphere.migrator.PlanExtractor -ids 7564 7675 java psoft.hsphere.migrator.PlanExtractor java psoft.hsphere.migrator.PlanExtractor silver -resellername RESELLER -ids 7564 -force -resellername RESELLER -force -resellername RESELLER -force -resellername RESELLER -resellername admin -plans PlanExtractor writes error messages to migrate_plans.log. Plan Creator Run PlanCreator as cpanel with the following syntax: java psoft.hsphere.migrator.PlanCreator [-active] -d plans.xml [createprices] Options:  -active - if possible, activate plans after they are created.  -d plans.xml - specify plan XML file to be taken.  -createprices - create prices for plans. Make sure to restart Parallels H-Sphere (on page 59) after running PlanCreator. PlanCreator writes error messages to migrate_plans.log. Resources Migration 363 XML Document Structure The structure of plans.xml looks as follows: plans / ... plan ____________/\_________________________ / | \ periods options \ ... / ... | ... _________/\______________________________ period /|\ / | | \ _____/ | \____ resource ifresource ifgroup LogicalGroup / | \ | | ... | ... / | \ | ... __|__ ___|___ / | \ | / \ / \ customparam postparam param____|____ resource ifgroup resource LogicalGroup / | \ | | ... | special fields price... ___|___ ... | ... / \ special resource LogicalGroup | ... Example of plans.xml: http://hsphere.parallels.com/HSdocumentation/xmls/plans.xml DTD Scheme: http://hsphere.parallels.com/HSdocumentation/xmls/plans.dtd 364 Resources Migration XML Elements and Attributes 1. plan - plan description:  name - plan name  reseller - reseller name (if not avaliable, admin is assumed)  wizard - wizard name 2. period - plan periods:  id - period id  size - period duration  type - period type (DAY, WEEK, MONTH, YEAR)  discountusage - usage discount (%)  discountsetup - setup discount (%)  discountunit - recurrent discount (%) 3. param - plan parameters used for the plan creation:  name - parameter name value - parameter value Parameters:  trial - billing type: 0 - Without billing, 1 - Paid, 2 - Trial  trial_duration - trial period for the billing type trial  trial_credit - credit limit for the billing type trial  hard_credit - credit limit  send_invoice - enable e-mail invoice notification  mixedip - default IP type (shared or dedicated)  shared_ip_tag - shared IP Tag  calias - instant alias for the given shared IP tag  stopgapalias - stopgap domain for the given shared IP tag  money_back - enable money back  money_back_days - money back guarantee in days  periods - the number of plan periods 4. postparam - parameters to be set after the plan creation:  name - parameter name value - parameter value Parameters:  contactinfo - enable contact info  billinginfo - enable billing info  _template - default template Resources Migration  365 _TEMPLATES_DIR - template directory 5. customparam - custom parameters to be set after the plan creation:  name - parameter name  value - parameter value 6. resource - resources available for the plan. Check corresponding plan wizard XML documents in the ~cpanel/psoft/hsphere/plan/wizard/xml/ directory for the list of available resources and the way they are set:  name - resource name  enable - is resource enabled  include - is resource included  active - is resource activated 7. price - resource price:  id - price id  freeunits - free units  setup - setup units  unit - monthly units  usage - extra units 8. LogicalGroup - the plan's logical group:  name - logical group name  type - logical group type  groupid - logical group id 9. special - special resource parameters:  name - special field name  value - special field value 366 Resources Migration Step 3. Prepare The Target Control Panel Before you start creating accounts from the xml files, log as cpanel user (on page 71), go to the target Parallels H-Sphere control panel and do the following: 1. Make sure that the names of the plans are exactly the same as those in your user data xml file. To get a list of all reseller and user plans in the system, run: java psoft.hsphere.migrator.ResellerUserCreator -d migrate_resellers.xml -dl -pp 2. In the xml file, find users that have empty or filled mysql tag. In the control panel, enable MySQL resource for the plans you are migrating these users to. 3. If you intend to migrate the existent user content into Parallels HSphere, include but deactivate FrontPage in all plans you are migrating your customers to, and in which FrontPage will be used. 4. If you want to preserve original billing period start date, make sure that the billing periods have the same duration and go in the same order as those in your old control panel. Step 4. Create Reseller Plans Note: Skip this step if you don't have resellers. If you have resellers, run PlanCreator to create reseller plans on the target Parallels HSphere installation, for example: java psoft.hsphere.migrator.PlanCreator -active -d plans.xml Please refer to Migrating Plans with XML (on page 361) for details. Step 5. Create Resellers To create resellers, run ResellerUserCreator: java psoft.hsphere.migrator.ResellerUserCreator -d migrate_resellers.xml -l migrate.log -dl Resources Migration 367 Step 6. Create End Users To migrate end users, run CommonUserCreator: java psoft.hsphere.migrator.CommonUserCreator -d migrate_users.xml -l migrate.log -dl Note: To prevent double charges for resources billed on the monthly basis, such as Traffic and Disk Usage, CommonUserCreator shifts start date for them to the day before the date of migration. Troubleshooting If the migration software fails to create a reseller/end user account, it will return an error and stop the migration. In this case, read the messages on the screen to find which user caused the failure, read the log file and try to remove the cause of the error. Note: If the domain tag of this user in the XML file contains the ip attribute and if the IP in this user's domain was created before the error occurred, go to the Parallels HSphere control panel and delete this IP. Then, proceed with the migration using the above command plus one of these two options:  -r user_login - proceed with the migration starting with the user with this login name;  -rc user_login - delete this user and then proceed with the migration starting with this user. The full command must look like this: a) for a reseller's end user: java psoft.hsphere.migrator.ResellerUserCreator -d migrate_resellers.xml -l migrate.log -dl -r user_login b) for a direct end user: java psoft.hsphere.migrator.CommonUserCreator -d migrate_users.xml -l migrate.log -dl -r user_login CHAPTER 24 Backup and Recovery This chapter explains how to back up Parallels H-Sphere system and user data. Backup of the Control Panel server with the PostgreSQL system database is done by the Parallels H-Sphere backup script. It requires PostgreSQL client version 7.3 or higher installed and the psql program available in the system paths on the CP server. Backing up content on the Unix servers is performed manually. See the backup and recovery list (on page 370) of Parallels H-Sphere related directories and files. We recommend that you set up a separate server to store backup archives. In this chapter: Backing Up Parallels H-Sphere Control Panel Server ....................................... 369 Parallels H-Sphere Backup and Recovery List .................................................. 370 Recovering Parallels H-Sphere Control Panel ................................................... 372 Recovering Unix Hosted Parallels H-Sphere Servers ........................................ 374 Restoring Files and Directories from Backup ..................................................... 377 Restoring the Parallels H-Sphere System Database From Backup.................... 377 Fixing Crashed Parallels H-Sphere Database ................................................... 381 Backing Up Winbox ........................................................................................... 382 Recovering Winbox ........................................................................................... 384 Recovering Winbox Quota ................................................................................. 390 Backup and Recovery 369 Backing Up Parallels H-Sphere Control Panel Server This section explains how to back up the Control Panel server with the system database by means of the backup script. The backup script located in the /hsphere/shared/backup directory. The script includes the following files:  hs_bck - the main script file  hs_bck.cfg - custom configuration file. This is the file to store the list of directories to back up.  hs_bck.cfg.org - default configuration file. It can be overwritten with Parallels HSphere updates. This is where you can find the updated list of parameters to the hs_bck script if it has been changed in a new version.  hs_bck.txt - description/readme file. You need to configure the script by editing the hs_bck.cfg file.  To back up Parallels H-Sphere CP server: 1. Log into the CP server as root: su - 2. cd into the backup script directory: cd /hsphere/shared/backup 3. Make sure the files hs_bck.cfg and hs_bck.cfg.org are identical in what is not your custom settings. The format of the hs_bck.cfg.org file may change with Parallels H-Sphere updates, and it is important to ensure that the backup script is launched with correct parameters. 4. In hs_bck.cfg, edit the list of directories and databases to back up. See the backup and recovery list (on page 370). 5. In hs_bck.cfg, edit the the backup storage directory, the number of latest backups to be stored (7 by default), the log file, etc. 6. Run the backup script.  For regular automatic backups, add the execution of the hs_bck file into the CP server crontab configuration (on page 34), e.g.: /hsphere/shared/backup/hs_bck hs_bck.cfg 2>&1 > /dev/null For example, to run the backup script every day at 6:13 AM, add the following line: 370 Backup and Recovery 13 6 * * * /hsphere/shared/backup/hs_bck /hsphere/shared/backup/hs_bck.cfg 2>&1 > /dev/null  For additional parameters to this script, please run: /hsphere/shared/backup/hs_bck System DB Dump In addition to backing up the pgsql directory on the CP server, the backup script can also create a dump of Parallels H-Sphere system database and Parallels SiteStudio databases. For this, make sure the following directories are listed: PROP_FILE /hsphere/local/home/cpanel/shiva/psoft_config/hsphere.properties PROP_FILE /hsphere/shared/SiteStudio/psoft_config/counter.properties PROP_FILE /hsphere/shared/SiteStudio/psoft_config/poll.properties PROP_FILE /hsphere/shared/SiteStudio/psoft_config/guestbook.properties If Parallels H-Sphere database is large, the dump can take several hours to complete. You can speed it up by setting fsync=off in postgresql.conf. When you are done, unset this option back for safety reasons. Parallels H-Sphere Backup and Recovery List Following is the list of directories and files to back up and recover. Backup can be done by means of the Parallels H-Sphere backup script (on page 369) on the CP server or manually on other Parallels H-Sphere servers. Item Comment Control Panel Server /hsphere/local/home/cpanel/hsphere/WEB -INF/classes/psoft_config/ Parallels H-Sphere configuration and properties files /hsphere/shared/SiteStudio/studio/WEBINF/classes/psoft_config/ Parallels SiteStudio configuration and properties files /hsphere/local/home/cpanel/apache/etc/ Apache configuration and properties files /hsphere/local/home/cpanel/hsphere/WEB -INF/classes/shiva-templates/IMAGES/ Control Panel icons and images /hsphere/local/home/cpanel/hsphere/WEB -INF/classes/custom/ Custom Control Panel templates, etc. /hsphere/shared/SiteStudio/var/website s/ Parallels SiteStudio user data /var/lib/pgsql/ Parallels H-Sphere and Parallels SiteStudio system databases and database settings Backup and Recovery /hsphere/local/home/cpanel/.kb/ /hsphere/local/home/cpanel/.attachment s/ Parallels H-Sphere knowledge bases /hsphere/local/home/cpanel/shiva/packa ges Parallels H-Sphere packages 371 Web Server /hsphere/local/home/ User Home Directories /usr/local/frontpage/ FrontPage Extensions settings /hsphere/local/config/ httpd and ftp configs /var/spool/cron/ (Linux) /var/cron/tabs/ (FreeBSD) Customer Crontabs /hsphere/shared/apache/htdocs/phpMyAdm in/config.inc.php phpMyAdmin configuration file /hsphere/shared/apache/htdocs/phpPgAdm in/conf/config.inc.php phpPgAdmin configuration file /hsphere/local/network/ ips file, etc. /hsphere/shared/awstats/wwwroot/cgibin/ AWS configs et al. Mail Server /hsphere/local/var/vpopmail/etc/ vpopmail settings /hsphere/local/var/vpopmail/domains/ Mail domains /var/qmail/control/ Settings for qmail addons /var/qmail/users/ qmail users /hsphere/local/config/ httpd and ftp configs /var/lib/mysql/ (Linux) /var/db/mysql/ (FreeBSD) MySQL databases (used to store user settings for integrated antispam and antivirus software) /hsphere/shared/apache/htdocs/horde/co nfig/conf.php Horde settings DNS Server /etc/named.conf /etc/rndc.conf Main DNS config files /hsphere/local/var/named/ DNS zone files MySQL Server /var/lib/mysql/ (Linux) /var/db/mysql/ (FreeBSD) MySQL settings and databases User PostgreSQL Server /var/lib/pgsql/ (Linux) /usr/local/pgsql/ (FreeBSD) User postgres settings and databases 372 Backup and Recovery Recovering Parallels H-Sphere Control Panel This document provides a general outline on how to recover Parallels H-Sphere Control Panel to a new server if the old one has crashed due to hardware or other problems. We will be looking into two situations:  You have been having hardware problems that didn't affect the HDD, and you can access the HDD. This also applies to hacked servers. In this case, you'll have to mount the HDD of the crashed server to the new server to copy below system data from it.  You've had a HDD failure and/or the HDD is inaccessible. In this case, you'll have to restore below system data from a backup (on page 369). In either case it is presumed that your old server is down and no Parallels H-Sphere servers are running. This instruction doesn't give file/directory locations for FreeBSD, because Linux is the recommended operating system for the CP server. Step 1. Prepare for the Recovery 1. On the target server, install exactly the same version of Parallels H Sphere Control Panel as on the source server. 2. Make sure the source and target servers have the same versions of all software packages. For example, make sure that the target server has the same version of PostgreSQL as the source server. 3. Stop Parallels H-Sphere CP (on page 59) and stop PostgreSQL service (on page 60) on the target server. Step 2. Recover System Data 1. Log into the target server as root. 2. Copy files and directories in the table below from the source server or backup to the target server.  If you are recovering from a backup made by the backup script (on page 369), untar the backup archive copy the below directories.  If you are recovering data from the HDD of the crashed server, just copy the below directories: rsync -arlpogvzt -e ssh SOURCE_SERVER_IP:DIRECTORY_PATH TARGET_DIRECTORY_PATH Backup and Recovery 373 3. Restore the backed up SSH keys from the ~cpanel/.ssh/identity.pub and ~cpanel/.ssh/id_dsa.pub into the /root/.ssh/authorized_keys and /root/.ssh/authorized_keys2, respectively, instead of the new keys generated on the target server after Step 1. Please refer the Generating SSH Keys for Parallels H-Sphere Servers (on page 119) document for details. 4. On multiserver Parallels H-Sphere cluster, test inter-server communication via SSH without login. For example: su -l cpanel ssh root@cp_server_ip exit ssh root@second_server_ip exit and so on. 5. Sometimes, in order to restore some core templates and images, you may need to run the Parallels H-Sphere update script for this version with the hsonlycpupdate option. 6. Start Parallels H-Sphere CP (on page 59) and PostgreSQL (on page 60) on the target server. Note: If PostgreSQL does not run smoothly after its start, remove the the postmaster.pid file in /var/lib/pgsql 7. You may test the Parallels H-Sphere database by running: su -l cpanel -c 'psql hsphere' This should result in a successful log into the database from the command line. Files and Directories To Be Recovered Item Comment ~cpanel/shiva/psoft_config/ Parallels H-Sphere configuration and properties files /hsphere/shared/SiteStudio/psoft_c onfig/ Parallels SiteStudio configuration and properties files ~cpanel/apache/etc/ Apache configuration and properties files ~cpanel/shiva/shivatemplates/IMAGES Control Panel icons and images ~cpanel/shiva/custom Custom Control Panel templates, etc. /hsphere/shared/SiteStudio/var/web sites Parallels SiteStudio user data /var/lib/pgsql (on Linux) /usr/local/pgsql (on FreeBSD) Parallels H-Sphere and Parallels SiteStudio system databases and database settings 374 Backup and Recovery ~cpanel/.kb/ ~cpanel/.attachments/ Parallels H-Sphere knowledge bases ~cpanel/.ssh/identity.pub ~cpanel/.ssh/id_dsa.pub SSH keys to be restored into the /root/.ssh/authorized_keys and /root/.ssh/authorized_keys2, respectively, instead of the new keys generated on the target server after Step 1 (fresh Parallels H-Sphere installation). Recovering Unix Hosted Parallels HSphere Servers This document explains how to recover non-CP Linux/FreeBSD boxes. If you are restoring CP, see Recovering Control Panel (on page 372). Important: To successfully recover a crashed server, you must meet the following requirements: 1. You must have all user content and configuration files previously backed up (on page 369). 2. You must have the physical and logical server structure of the crashed server preserved in the administrator CP in the E.Manager menu. We suggest the procedure below. In this section: Step 1. Prepare Crashed Server for Recovery .................................................. 375 Step 2. Run Parallels H-Sphere Updater ........................................................... 375 Step 3. Run the Recovery Tool.......................................................................... 375 Step 4. Restore User Content............................................................................ 376 Backup and Recovery 375 Step 1. Prepare Crashed Server for Recovery 1. Prepare the server where the crashed box's services and content are to be restored, according to Parallels H-Sphere installation requirements described in the Installation Guide. 2. Make sure this "blank" server is bound to the same IP the crashed server had. 3. Place the cpanel user's public SSH keys (on page 119) from the CP server to the server to be recovered so that you can connect via SSH from CP server's root to the new box without password. Step 2. Run Parallels H-Sphere Updater 1. Log into the CP server as root: $ su -l 2. Download the update script of the Parallels H-Sphere version you were running on the crashed server. If you already have an older version of the updater in the current directory, please remove or rename this file before the download. 3. Run the updater on the directory where you have downloaded it. See the Update Guide for details. 4. Restore the crashed server software by typing in the following command in the updater's command line prompt: hspackages ips= Step 3. Run the Recovery Tool Web, Mail, MySQL, PgSQL servers: To restore your Parallels H-Sphere physical resources (Unix users and configuration), log in as the cpanel user (on page 71) and run PhysicalCreator (on page 78). Note: Do not confuse the account ID with the server ID you used when generating configuration files. Account IDs could be found in the accounts table of the Parallels HSphere system database. DNS server: For DNS servers, log in as the cpanel user (on page 71) and run DNS Creator (on page 229): java psoft.hsphere.tools.DNSCreator -m db 376 Backup and Recovery Step 4. Restore User Content To restore data from the backup, check with the backup and recovery list (on page 370) for for this server. Restore listed directories from /var/backup/.tgz or custom backup directory into the appropriate locations. More on backup recovery (on page 377). Backup and Recovery 377 Restoring Files and Directories from Backup This document explains how to recover Parallels H-Sphere user and system data you have backed up according to the manual on backing up Parallels H-Sphere (on page 369). Parallels H-Sphere backup location is set in the /hsphere/shared/backup/hs_bck.cfg config file. The default location is /var/backup. hs_bck stores the system data backup (with user content if configured in hs_bck.cfg) in the following files in the BCK_DIR directory:  .tgz - the latest backup; is the name of the backup file set in hs_bck.cfg. This is the default name: BACKUP hs_bck Older backup files are named .1.tgz, .2.tgz, ...  hsphere.sql - the Parallels H-Sphere system database backup  counter.sql, poll.sql, guestbook.sql - Parallels SiteStudio system databases are also backed up if Parallels SiteStudio is set up with Parallels HSphere. To restore data from the backup, check with the backup and recovery list (on page 370) for the directories that need to be recovered for this server. Restore these directories from .tgz into the appropriate locations on the server. Restoring the Parallels H-Sphere System Database From Backup This documentation explains how to restore the Parallels H-Sphere system database from a backup made by the Parallels H-Sphere hs_bck (on page 369) script. If you back up your system PostgreSQL database manually using pg_dump, the procedure would be basically the same, except for the backup names and locations. The backup destination directory for the /hsphere/shared/backup/hs_bck script is set in the /hsphere/shared/backup/hs_bck.cfg config file. The default location is: BCK_DIR /var/backup hs_bck stores the system data backup in the following files in the BCK_DIR directory:  .tgz - the system data content; is the name of the backup file set in hs_bck.cfg: BACKUP hs_bck 378 Backup and Recovery Older backup files are named .1.tgz, .2.tgz, ...  hsphere.sql - backup of the Parallels H-Sphere system database  counter.sql, poll.sql, guestbook.sql - Parallels SiteStudio system databases are also backed up if Parallels SiteStudio is integrated with Parallels HSphere. Below are two cases restoring the database depending on PostgreSQL installed or not on the server. In this section: Restoring the Parallels H-Sphere Database on a Server with PostgreSQL Not Installed Restoring the Parallels H-Sphere Database Content if PostgreSQL Is Installed: 380 379 Backup and Recovery 379 Restoring the Parallels H-Sphere Database on a Server with PostgreSQL Not Installed 1. Log into the erver as root: su - 2. Install PostgreSQL to the server. 3. Start PostgreSQL for the first time: On RedHat servers: /etc/rc.d/init.d/postgresql start On FreeBSD servers, you need to initiate the PostgreSQL service database manually before you start Postgres: su - pgsql -c initdb /usr/local/etc/rc.d/010.pgsql.sh start 4. Log in as PosgreSQL user: On RedHat servers (the PostgreSQL service database is initiated automatically on login): su - postgres On FreeBSD servers: su - pgsql 5. Create the user wwwuser: createuser wwwuser Answer yes to all prompts. 6. Enter the PostgreSQL service database: psql template1 7. Restore the wwwuser password: alter user wwwuser with password 'old_password'; alter user pgsql with password 'old_password'; Here, old_password is the wwwuser password to be restored. 8. Quit from PostgreSQL: \q 9. Configure PostgreSQL passwords in the ~pgsql/data/pg_hba.conf file, according to instructions provided in this file. 10. Optimize Postgres (on page 111) for better PostgreSQL performance on powerful servers, esp. when the database is large (more than 1GB). 380 Backup and Recovery Note: It is helpful to set fsync=false in postgresql.conf for the time of recovery. This allows to speed up the process. However, please beware that this may damage the database integrity, and we recommend using this option only on reliable hardware! Don't forget to return to fsync=true after the recovery is complete! 11. Restart PostgreSQL (on page 60). 12. Create Parallels H-Sphere database by running: createdb -E UNICODE -U wwwuser hsphere Parallels SiteStudio databases are created in the similar way. 13. Import the database content from the backup: psql -U wwwuser -f /hsphere.sql hsphere where is the backup directory. Parallels SiteStudio databases are imported in the similar way. Restoring the Parallels H-Sphere Database Content if PostgreSQL Is Installed: 1. Log in to the CP server as root: su - 2. Drop the Parallels H-Sphere database: dropdb -U wwwuser hsphere 3. Create the Parallels H-Sphere database: createdb -E UNICODE -U wwwuser hsphere 4. Optimize Postgres (on page 111) for better PostgreSQL performance on powerful servers, esp. when the database is large (more than 1GB). Note: It is helpful setting fsync=false in postgresql.conf for the time of recovery. This allows to speed up the process. However, please beware that this may damage the database integrity, and we recommend using this option only on reliable hardware! Don't forget to return to fsync=true after the recovery is complete! 5. Import the database content from the backup: psql -U wwwuser -f /hsphere.sql hsphere where is the backup directory. Parallels SiteStudio databases are restored in the same way. Backup and Recovery 381 Fixing Crashed Parallels H-Sphere Database Sometimes PostgreSQL database can get corrupted to the point of no return. That might manifest itself in things like: hsphere=# VACUUM ; ERROR: Relation 71343 does not exist This usually means that index is corrupted.  To recover from the problem: 1. Login as root: su - 2. Stop Postgres (on page 59) if it is running. 3. Make sure that no Postgres processes are running using the command: ps auxw | grep post If any of them are running, kill them. 4. Remove Postgres' pid file: rm -f PGSQL_HOME/data/postmaster.pid From now on, we note PGSQL_HOME as the Postgres home directory which is /var/lib/pgsql on RedHat servers, and /usr/local/pgsql on FreeBSD. 5. Switch to Postgres user: # su - postgres (on RedHat) # su - pgsql (on FreeBSD) 6. Backup PostgreSQL database stored in the PGSQL_HOME/data directory: cp -r PGSQL_HOME/data pgdata.backup 7. Try to connect to the Parallels H-Sphere database in single mode: postgres -D PGSQL_HOME/data -O -P hsphere There can be errors like: FindExec: found "/usr/bin/postmaster" using argv[0] 2002-03-22 13:42:46 [6002] DEBUG: database system was shut down at 2002-03-22 11:46:11 CET 2002-03-22 13:42:46 [6002] DEBUG: ReadRecord: invalid resource manager id 157 at (0, 561372168) 2002-03-22 13:42:46 [6002] DEBUG: Invalid primary checkPoint record 2002-03-22 13:42:46 [6002] DEBUG: Invalid RMID in secondary checkPoint record 382 Backup and Recovery 2002-03-22 13:42:46 [6002] FATAL 2: Unable to locate a valid CheckPoint record 2002-03-22 13:42:46 [6002] DEBUG: proc_exit(2) 2002-03-22 13:42:46 [6002] DEBUG: shmem_exit(2) 2002-03-22 13:42:46 [6002] DEBUG: exit(2) /usr/bin/postmaster: reaping dead processes... /usr/bin/postmaster: Startup proc 6002 exited with ... The messages like: ReadRecord: invalid resource manager and other are culprit of the error. In case of the above errors, do the following: 1. Execute: pg_resetxlog PGSQL_HOME/data (this will reset the write-ahead log and other control information of a PostgreSQL database cluster; they are important but this is the only way to recover). 2. Try to log into Postgres again in single mode: postgres -D PGSQL_HOME/data -O -P hsphere 3. Once you are in, type: reindex database hsphere; 4. Exit the database: \q 5. Finally, start Postgres (on page 59) and see if everything is working. Here, two Postgres tools are used:  reindex database to recover corrupted indexes  pg_resetxlogs to reset write-ahead log files and the state of Postgres. Backing Up Winbox This document explains how to back up your   Windows server settings stored in the MetaBase, MS SQL database  user content In this section: Backing Up the Metabase ................................................................................. 383 Backing Up MS SQL Databases ....................................................................... 383 Backing Up User Content.................................................................................. 383 Backup and Recovery 383 Backing Up the Metabase 1. Go to Start -> Programs -> Administrative Tools -> Computer Management. 2. In the left tree, unfold Services and Applications. 3. Right-click Internet Information Services and select Backup/Restore Configuration. 4. In the window that appears, click Create Backup. Usually, IIS metabase backup files are located in the following directory: C:\WINNT\system32\inetsrv\MetaBack\ Backing Up MS SQL Databases 1. Go to Start -> Programs -> Microsoft SQL Server -> Enterprise Manager. 2. Unfold the left menu tree until you see the name of the logical server. Click it. 3. Click Tools on the toolbar and select Backup Database. Backing Up User Content 1. Go to Start -> Programs -> Accessories -> System Tools -> Backup. 2. Select Backup Wizard 3. On the first step of the wizard, select Back up selected files, drives, or network data. 384 Backup and Recovery Recovering Winbox This document explains how to restore Parallels H-Sphere Winbox configuration using the Physical Creator (on page 78) utility. If you have access to user homes, you can recover user content from this directory. If you don't, you'll need an earlier backup (on page 382) with preserved directory structure (on page 259). We suggest the recovery procedure below. In this section: Step 1. Back Up User Content........................................................................... 384 Step 2. Install Parallels H-Sphere ...................................................................... 385 Step 3. Set Up Dedicated IPs ............................................................................ 385 Step 4. Prepare Target Winbox for Physical Creator ......................................... 385 Step 5. Run PhysicalCreator on the CP Box...................................................... 386 Step 6. Restore Content from Backup ............................................................... 387 Step 7. Install Shared SSL ................................................................................ 388 Step 8. Set Correct NTFS Permissions and Owner for the Home Directory ....... 389 Step 1. Back Up User Content 1. Stop IIS by running the following commands from the command prompt: iisreset /stop net stop w3svc net stop ftp 2. Rename the directory containing Parallels H-Sphere user homes. It will be used later to recover user content. If you don't have access to user homes, you'll have to recover user content from a backup. 3. Start IIS: iisreset /start 4. Create an empty HSHOME directory Backup and Recovery 385 Step 2. Install Parallels H-Sphere 1. Make sure to have IIS (WebService) and FTP (IIS or Serv-U) installed. For information on IIS, run from the command prompt: %SystemRoot%\System32\Inetsrv\iis.msc For information on Serv-U FTP, check the task manager or Service Managere (full name : Serv-U FTP Server, short name: servu) FTP can be missing if the server is running only MS SQL. 2. Follow Winbox preinstallation procedure as suggested in the Winbox Installation Guide. 3. Follow Winbox installation procedure. 4. After the installation, set up WebShell4. Step 3. Set Up Dedicated IPs 1. Go to the Parallels H-Sphere admin control panel and select the Winbox in L.Servers of the E.Manager -> Servers menu. 2. Copy all Busy Dedicated IPs and their netmasks from the list of IPs into a text file the IPs to create a file with the following format: 192.0.34.166 255.255.255.0 160.79.224.130 255.255.255.0 81.3.94.100 255.255.255.0 3. Download IpCreator: http://download.hsphere.parallels.com/shiv/WinBox/ipcreator.exe . 4. Bind IPs using the IpCreator utility, passing the file with IPs as a parameter: IpCreator.exe FILE_WITH_IPS > log.txt Step 4. Prepare Target Winbox for Physical Creator In the command prompt of the Winbox server, run: net stop HsQuotas 386 Backup and Recovery Step 5. Run PhysicalCreator on the CP Box 1. Go to the Parallels H-Sphere admin control panel, select P.Servers of the E.Manager -> Servers menu, and click server info for the Winbox in question. 2. Check if server info shows on the page that appears. If not, the CP server can't communicate with the Winbox; make sure to fix this issu e before proceeding. 3. Downolad tail utility for Windows (http://download.hsphere.parallels.com/shiv/WinBox/tail.exe) and put it into the WINDOWS (win2003) or WINNT (win2000) directory. 4. Log into the system database (on page 71) and run the following DB query to find out the number of domains to create: select count(*) from iis_vhost i,parent_child p,accounts a,user_account ua where i.id=p.child_id and p.account_id = a.id and a.deleted is null and ua.account_id = a.id and (a.demo <> 1 OR demo IS NULL) and host_id = ???; replacing ??? with the ID of the logical server you are recovering. 5. Run PhysicalCreator as the cpanel user (on page 71): java -Xms64M -Xmx512M psoft.hsphere.tools.PhysicalCreator -rg winweb -co -lid LOGICAL_SERVER_ID > creator.log 2>&1 & 6. In the command line on the Winbox, run tail -f action.log to monitor the creation of Winbox resources. 7. In another command line window, periodically check the number of created domains by running: find "CreateWebHost(" \logs\action.log /c for example: find "CreateWebHost(" d:\hsphere\logs\action.log /c Backup and Recovery Step 6. Restore Content from Backup 1. Update Parallels H-Sphere to restore original skeleton and renamed scripts. 2. Back up IIS metabase using built-in IIS backup tools. 3. Stop IIS: iisreset /stop net stop w3svc net stop ftp 4. Copy user content to the directory for user homes. 5. Start IIS: iisreset /start 6. In the command prompt of the Winbox server, run: net start HsQuotas 387 388 Backup and Recovery Step 7. Install Shared SSL 1. In the admin control panel, install completely new Certificate key and file pair as described in Parallels H-Sphere Service Administrator Guide. You can get them in /hsphere/shared/apache/conf/ssl.shared// on any Unix/Linux web server. This will repost the wildcard certificate on all servers, including the Winbox you are recovering. 2. Download Recreation scripts (http://download.hsphere.parallels.com/shiv/WinBox/ReCreateAddScript s.zip) in a zip archive and unpack them to a separate directory on the Winbox, for example recreation_scripts. 3. Log into the system database (on page 71) and run the following DB query to select the domain names with shared SSL enabled: select s.name,hostnum,d.name from shared_ssl s, parent_child p1, parent_child p2, domains d, iis_vhost h where s.id = p1.child_id and p1.parent_id = p2.child_id and p2.parent_id = d.id and p2.child_id = h.id and h.host_id= ???; replacing ??? with the ID of the logical server you are recovering. 4. Copy results of the query into a text file in the recreation_scripts directory and name it, for instance, S_SSL.txt. It will have the following format: sname1 | hostnum1 | domain_name1 sname2 | hostnum2 | domain_name2 ... snameN | hostnumN | domain_nameN where: snameX is the third level domain secured with the wildcard certificate, e.g. user22.yourdomain.com hostnumX is the domain ID in IIS domain_nameX is the corresponding second level domain, e.g. user22.com. 5. Enter the recreation_scripts directory and run the following command: sslprepare.bat %1 %2 %3 %4 %5 > SetSSL.txt where: rem %1 is the file name you have created (e.g. S_SSL.txt) rem %2 - Winbox IP rem %3 - Service domain used for shared SSL rem %4 - Parallels H-Sphere login used at Winbox installation rem %5 - Parallels H-Sphere password used at Winbox installation. 6. Open SetSSL.txt and remove the first part leaving only the list of links. Backup and Recovery 7. Run the following command: WGET.EXE -i SetSSL.txt This will recreate all Shared SSL resources on the Winbox. Step 8. Set Correct NTFS Permissions and Owner for the Home Directory 1. Download SetScrt Tool: http://download.hsphere.parallels.com/shiv/WinBox/SetScrtNs20.exe 2. Run it to set correct owner and NTFS permissions on user home directories: SetScrtNs20 /ftp: /users: where: ftp - default Parallels H-Sphere ftp host number users - user list file 3. Check the log files for report. Note: Read on NTFS Permissions (on page 287) 389 390 Backup and Recovery Recovering Winbox Quota  To recover Winbox quota: 1. Download Recreation scripts (http://download.hsphere.parallels.com/shiv/WinBox/ReCreateAddScript s.zip) in a zip archive and unpack them to a separate directory on the Winbox, for example recreation_scripts. 2. Log into the system database (on page 71) and run the following DB query to select the users and their space limit: select unix_user.login, quotas.size_mb from unix_user, parent_child, quotas where hostid=??? and parent_child.parent_id=unix_user.id and parent_child.child_id=quotas.id and parent_child.child_type=4001; replacing ??? with the ID of the logical server you are recovering. 3. Copy results of the query into a text file in the recreation_scripts directory and name it, for instance, quotat.txt. 4. Enter the recreation_scripts directory and run the following command: Rquota.bat %1 %2 %3 %4 > quota.txt where: rem %1 - file name, e.g. quota.txt rem %2 - Winbox IP rem %3 - Parallels H-Sphere login used at Winbox installation rem %4 - Parallels H-Sphere password used at Winbox installation 5. Open quota.txt and remove the first part leaving only the list of links. 6. Run the following command: WGET.EXE -i quota.txt This will recreate quota resource on the Winbox. CHAPTER 25 Miva Like all third party commercial products, Miva Empresa and Miva Merchant are purchased and installed separately from Parallels H-Sphere. Miva Merchant (http://www.miva.com/products/merchant) requires Miva Empresa (http://www.miva.com/products/empresa) also known as Miva Virtual Machine or 'mivavm' for web server XML scripting, e-commerce and database capabilities.  Miva Merchant 5.x is supported starting with Parallels H-Sphere 2.4.3 Patch 1 inclusive. It requires Miva Empresa 5.02 and higher.  Miva Merchant 4.14 and later is supported from Parallels H-Sphere 2.3 RC 4 inclusive. It requires Miva Empresa 4.02 and higher. For extensive coverage of Miva products, please visit http://www.miva.com/products. In this chapter: Miva Installation for *nix..................................................................................... 391 Miva Installation for Windows ............................................................................ 396 Updating Miva 4 to Miva 5 ................................................................................. 397 Miva Installation for *nix Requirements  Installed and properly configured Parallels H-Sphere system.  One valid Miva Empresa license.  At least one valid Miva Merchant license. In this section: Miva Empresa Installation ................................................................................. 392 Miva Merchant Installation ................................................................................ 395 392 Miva Miva Empresa Installation  To install Miva Empresa: 1. Log into the web server as root. 2. Change directory to /hsphere/shared/miva. If you don't have this directory, create it first and set ownership to root:root and permissions to 755: mkdir /hsphere/shared/miva chown root:root /hsphere/shared/miva chmod 755 /hsphere/shared/miva 3. Download Miva virtual machine distribution file from http://www.miva.com/products/empresa/download/ to /hsphere/shared/miva. Linux: mivavm-vX.XX-linux_glibc2.tar.gz FreeBSD: mivavm-vX.XX-freebsd_45.tar.gz Here, mivavm is the product name, vX.XX its version name, linux_glibc2 is Linux glibc2 package, freebsd_45 is FreeBSD 4.5 operation system. 4. Untar the unloaded file: tar xfz 5. Move the content of the directory mivavm-vX.XX to /hsphere/shared/miva: mv mivavm-vX.XX/* . rm -rf mivavm-vX.XX 6. Set ownership to root:root on the content of the directory /hsphere/shared/miva: chown -R root:root /hsphere/shared/miva 7. Move file cgi-bin/mivavm-vX.XX to directory /hsphere/shared/miva: mv cgi-bin/mivavm-vX.XX mivavm 8. If you need to use commerce libraries you got from Miva, copy them to directory lib/commerce, then create links to them as follows: ln -s /hsphere/shared/miva/lib/commerce/uupsrss-vX.XX-linuxglibc2.so /hsphere/shared/miva/lib/commerce/uupsrss.so ln -s /hsphere/shared/miva/lib/commerce/cybercash-vX.XXlinux-glibc2.so /hsphere/shared/miva/lib/commerce/cybercash.so ln -s /hsphere/shared/miva/lib/commerce/ics2-vX.XX-linuxglibc2.so /hsphere/shared/miva/lib/commerce/ics2.so ln -s /hsphere/shared/miva/lib/commerce/linkpoint-vX.XXlinux-glibc2.so Miva 393 /hsphere/shared/miva/lib/commerce/linkpoint.so ln -s /hsphere/shared/miva/lib/commerce/authnet-vX.XX-linuxglibc2.so /hsphere/shared/miva/lib/commerce/authnet.so 9. If you have more than one web server, repeat the above steps for all web servers where you want to have Miva installed. When the Miva Empresa resource is turned on:  In the domain home directory (/hsphere/local/home///), the cgi-bin is createdthe mivavm and mivavm.conf files are copied to this cgi-bin directory  the libmivaconfig.so symlink to /hsphere/shared/miva/lib/config/3x.so is created there  In the user home directory (/hsphere/local/home//), create the mivadata directory, and the subdirectory there, with the same name as the domain subdirectory in the user home directory.  In the Apache configuration file for this domain, the Miva compiled script MIME type is added: application/x-miva-compiled .mvc Here, - mivavm is a CGI application that executes complied Miva scripts; - mivavm.conf is the Miva Empresa configuration file. The mivavm.conf file may look like this: mivaroot=&[document_root] stdmodedatadir=/hsphere/local/home/miva/mivadata/miva.com securityoptions=15 394 Miva cadir=/hsphere/shared/miva/certs openssl=/usr/lib/libssl.so openssl_crypto=/usr/lib/libcrypto.so where:  mivaroot is the Miva Web root directory, the same as the domain's DocumentRoot directory  stdmodedatadir is a directory where Miva Empresa data is stored  COMMERCE-LIB METHOD is a Payment Instrument, a commercial library to support automatic payments from credit cards via merchant gateway  BUILTIN-LIB LIBRARY is a standard (built-in) library that contains basic system functions  cadir is a directory with SSL certificates  openssl is the path to the OpenSSL library  openssl_crypto is the path to encryption libraries Miva 395 Miva Merchant Installation  To install Miva Merchant: 1. Log into the web server as root. 2. Copy file Merchant-vY.YY-bundle.tar.gz to /hsphere/shared/miva. vY.YY is Miva Merchant version. 3. Create a link to Merchant-vY.YY-bundle.tar.gz: ln -s /hsphere/shared/miva/Merchant-vY.YY-bundle.tar.gz Merchant-bundle 4. In the admin control panel, select Globals in the Plans menu and make sure Miva Empresa Engine and MIVA Resource are enabled. 5. Select L.Servers in the E.Manager -> Servers menu, then click the web server, and at the bottom of the page that appears select the version of Miva Merchant: 6. If you have more than one web server, repeat the above steps for all web servers where you want to have Miva installed. 7. Log into your admin Control Panel, select Miva Merchant Lic. in the 3rd party Tools menu and enter your Miva Merchant licenses: Notes:  Login and Password for Miva admin interface are the same as for FTP unless a user has activated the original Miva Merchant setup.  If Miva is enabled, the user can't remove the cgi-bin directory and CGI handler with the .cgi extension in Parallels H-Sphere.  mivadata and all its content is not removed when Miva resource is removed.  To make Miva work via SSL (htpps), an SSL certificate is required. If a user cannot connect to Miva site by SSL (https://), log into your Miva Merchant control panel via http, go to the Domain Settings page -> Site configuration tab and check secure URLs.  You can install two instances of Miva on one logical server, one version 4.12 and older, the other 4.14 or later.  To enable Miva Merchant Follow Symlinks in mivaroot and stddatadir, you need to add the following line into the miva.conf file: securityoptions=15 396 Miva Miva Installation for Windows It is recommended to install Miva products prior to Parallels H-Sphere Winbox software. If you choose to do so, simply install Miva Empresa and Miva Merchant following Miva documentation. Afterwards, install Parallels H- Sphere winbox software, and the installation wizard will guide you through the Miva configuration procedure.  To install Miva on a running Winbox: 1. Install Miva Empresa VM as described at http://docs.mivamerchant.com/enUS/merchant/WebHost/webhelp/install_miva_empresa_vm_on_windows _2000_server.htm. 2. Install Miva Merchant as described in Miva documentation at http://docs.mivamerchant.com/enUS/merchant/WebHost/webhelp/web_host_resources.htm. Note: Since version 3.1, Parallels H-Sphere supports only Miva 5 for Windows platforms. If you move to Miva 5 and need to upgrade Miva Merchant stores, follow the instructions at http://docs.mivamerchant.com/enUS/merchant/WebHost/webhelp/upgrade_to_merchant_5_from_merchant_4.htm. 3. Go to your admin control panel, select E.Manager -> L.Servers, click the Windows server, and at the bottom of the page that appears specify the version of Miva Merchant. Specify also its location on your box: Miva 397 4. Run Parallels H-Sphere Update Wizard from the administrator control panel. 5. Optionally, install miva commerce libraries. 6. Log into your admin Control Panel, select Miva Merchant Lic. in the 3rd party Tools menu and enter your Miva Merchant licenses. 7. Enable Miva in your hosting plans. Once you have enabled Miva, users can turn them on in their control panels. User's miva login and password are same as for FTP. Updating Miva 4 to Miva 5 We do not support Miva 4 and Miva 5 running on the same web server. To upgrade Miva Merchant and Miva Empresa, you need to uninstall version 4 and then set up version 5.0. Since these two versions use different system libraries, customer stores also need to be updated to Miva 5. To update the stores, please use Miva tools, as we do not provide any update utilities. CHAPTER 26 Urchin This chapter describes how to install Urchin 4 and Urchin 5 on your Parallels H-Sphere servers. Urchin 4 and 5 can be installed on any Parallels H-Sphere *nix server. It does not require any special configuration and once installed, can poll statistics from all web servers and winboxes. In this chapter: Urchin 4 and 5 Installation on Unix .................................................................... 399 Urchin 4 and 5 Installation on Windows ............................................................. 401 Urchin 4 And Urchin 5 Database Utilities ........................................................... 402 Urchin 399 Urchin 4 and 5 Installation on Unix  To install Urchin: 1. Go to the Urchin home page (http://www.google.com/urchin/index.html) and click the Download link. 2. Select the installer that most closely matches your platform. The name of the installer includes the Urchin version and the operating system type (e.g., urchin4100_redhat6x.sh). Note: Currently, only versions 5.7.03 and below are supported. If necessary, upload the installer to a temporary location on the system where you are installing Urchin. If you are not on the console, telnet (or use ssh if available) to the system and cd to the directory where the installer is located. 3. From the command line, type the name of the installer. For example: ./urchin4100_redhat7x.sh This unpacks the files that comprise the installation kit. 4. From the command line, execute the main installation script by typing: ./install.sh The script prompts you for input as needed; just follow the instructions. 5. Following the instructions of the manual, configure Urchin in the directory /hsphere/local/urchin. Note: Urchin port and owner can be set by default (9999, nobody). 6. Create directory /hsphere/local/urchin/var/logs by running: mkdir /hsphere/local/urchin/var/logs 7. Set directory owner the same as for Urchin on step 5: chown nobody:nobody /hsphere/local/urchin/var/logs Important: Make steps 8-12 on all web boxes. 8. Check httpd.conf for Script Alias directive in the shared IP Virtual Host (usually /hsphere/local/sqwebmail directory). If this directory doesn't exist - create it with 755 permissions. 9. Copy print-log.pl script from the /hsphere/shared/scripts directory: cp /hsphere/shared/scripts/print-log.pl /hsphere/local/sqwebmail/cgi-bin/ 10. Set 755 permissions for this script: chmod 755 /hsphere/local/sqwebmail/cgi-bin/print-log.pl 400 Urchin 11. Create loglist file: touch /hsphere/local/sqwebmail/cgi-bin/loglist 12. Set owner and group for this file to httpd: chown httpd:httpd /hsphere/local/sqwebmail/cgi-bin/loglist 13. In the hsphere.properties file, configure the following variables:  URCHIN_SERVER_ID = [URCHIN_SERVER_ID] ID of the logical server where Urchin is installed. You can get the logical server ID in E.Manager  URCHIN_PORT = [URCHIN_PORT] the port taken by Urchin  URCHIN_SCHEDULER_START = [URCHIN_SCHEDULER_START]  URCHIN_SCHEDULER_FINISH = [SCHEDULER_FINISH] the hours when statistics is collected. e.g, 2 and 4 means statistics will be collected between 2 and 4 AM  URCHIN_PROTOCOL = [URCHIN_PROTOCOL] the protocol to connect to the Urchin control panel, can be http or https. The default is http  URCHIN_SERVERNAME = [URCHIN_SERVERNAME] Urchin server URL, should be set in addition to URCHIN_SERVER_ID on systems with NAT support (on page 29) (the Urchin server in this case has a local IP). In other cases, you should comment out or skip setting this parameter. 14. Restart Parallels H-Sphere (on page 59) for changes to take effect. Urchin 401 Urchin 4 and 5 Installation on Windows 1. Install Urchin as instructed by the Urchin Installation Guide (Windows) at http://www.google.com/support/urchin45/bin/answer.py?answer=28546& topic=7372. 2. Log in to Parallels H-Sphere control panel server as root. 3. In the hsphere.properties file, configure the following variables:  URCHIN_SERVER_ID = ID of the logical server where Urchin4 is installed  URCHIN_PORT = port where Urchin is installed  URCHIN_SCHEDULER_START =  URCHIN_SCHEDULER_FINISH = the hours when statistics is collected, e.g. between 2 and 4  URCHIN_PROTOCOL = the protocol to connect to the Urchin control panel, e.g., http or https. 4. Restart HSphere (on page 59) for changes to take effect. 402 Urchin Urchin 4 And Urchin 5 Database Utilities Urchin Database Utilities Urchin 4/5 installation includes utilities to insert, edit, and delete records in Urchin database. The only two ways to change data in Urchin internal database are through Urchin Control Panel or by the means of Urchin database utilities. The following Urchin database utilities are located in the util subdirectory of the Urchin installation directory (/hsphere/shared/urchin for Unix, C:\Program Files\Urchin for Windows):  uconf-import (not used for Parallels H-Sphere Windows accounts) is a utility that imports XML data to Urchin database. XML data may be transferred to the standard input or taken from an XML file. For more details on uconf-import options, see the manual on the Urchin Documentation Center at http://help.urchin.com/index.cgi?id=1489  uconf-driver (uconf-driver.exe for Windows) is a utility that allows inserting, deleting or updating database tables. Visit Urchin Documentation Center for the uconf-driver options at http://help.urchin.com/index.cgi?id=1051. Urchin Database Tables 1. Logfile is the table that holds log file locations. In Parallels H-Sphere, Urchin log files are accessed remotely via HTTP protocol. Log file is returned by the printlog.pl script. Here is an example of XML representaion of a Logfile table record: ct_name=urchin.com cr_type=remote ct_loglocation=/hsphere/local/urchin/var/logs/ cr_protocol=http ct_server=63.212.171.4 ct_port=80 ct_remotelocation=cgi-bin/printlog.pl?urchin&urchin.com&xgyvijmuxpuad07p1w/nuw==&.gz cs_logformat=ncsa Field description: Field name XML Representation Description Name Record name, coincides with the domain nam in Parallels H-Sphere. Urchin 403 ct_name ct_name=urchin.c om The name of a domain where statistics is collected. cr_type cr_type=remote Type of access to log files; it is always "remo in Parallels H-Sphere ct_loglocati on ct_loglocation=/ hsphere/local/ur chin/var/logs/ On remote access to this directory, log files with Web boxes' collected statistics are taken cr_protocol cr_protocol=http Protocol used to access log files; it is always "http" in Parallels H-Sphere; ct_server ct_server=63.212 .171.4 IP of the logical server where log files are located. ct_remoteloc ation ct_remotelocatio n= cgibin/printlog.pl?urchin&ur chin.com&xgyvijm uxpuad07p1w/nuw= =&.gz Location of log files; in Parallels H-Sphere, it set as the URI of a CGI script that collects statistics from remote log files, with a query string containing the script parameters. cs_logformat cs_logformat=ncs a Log file format: ncsa for Unix, w3c for Windows. 2. Profile is a table used to access statistics in the form of charts, diagrams, etc. Here is an example of XML representation of a Profile table record: ct_name=urchin.com ct_website=http://urchin.com ct_reportdomains=urchin.com,www.urchin.com cs_llist="urchin.com" Table field description: Field name XML Representation Description Name Record name, coinsides with the domain name in Parallels H-Sphe ct_name ct_name=urchin.com The name of a domain where statistics is being collected. ct_website ct_website=http://urchi n.com Web site URL. ct_reportdoma ins ct_reportdomains=urchin .com,www.urchin.com Possible ways to access domain, domain names separated with commas cs_llist cs_llist="urchin.com" The domain where log file is locat this field is used to link this table t Logfile table. 3. User is the table where the list of users is stored. User names are identical to Parallels H-Sphere account names. Access to reports is also set in this table. Here is an example of XML representation of a Users table record: ct_name=Urchin 404 Urchin ct_password=USCC|3980261512 cs_rlist="urchin.com" Table field description: Field name XML Representation Description Name Record name, coincides with the domai name in Parallels H-Sphere. ct_name ct_name=Urchin User name. ct_passwo rd ct_password=USCC|398026 1512 User's password. cs_rlist cs_rlist="urchin.com" The list of available reports. 4. Task is the table that contains tasks for collecting statistics. Here is an example of XML representation of a Task table record: ct_name=urchin.com cr_frequency=5 cs_hour=4 cs_minute=0 Field name XML Representation Description Name Record name, coincides with the domain na in Parallels H-Sphere. ct_name ct_name=urchin.com Domain name. cr_frequ ency cr_frequency=5 Task launching frequency; 5 means it would launch every 24 hours. cs_hour cs_minut e cs_hour=4, cs_minute=0 Task launching time. CHAPTER 27 RealServer Parallels H-Sphere supports all versions of RealServer that have ISPHosting support. If your license does not support ISPHosting, contact your RealServer account representative to obtain a license key that has the same number of streams and properly enables ISP hosting. In this chapter: RealServer Installation for Unix ......................................................................... 406 RealServer Installation for Windows .................................................................. 412 RealServer Config File Example ........................................................................ 412 406 RealServer RealServer Installation for Unix RealServer can be installed on a web box or a separate box with apache.  To install RealServer for Unix: 1. Install RealServer with ISPHosting support on a web box or a separate box into /hsphere/shared/RealServer as instructed by RealServer documentation at http://www.realnetworks.com/products/server/. If you set it up on a web box, specify 8080 port instead of the default 80, which is used by apache. During the installation, note the following data, as you will need them on subsequent steps:  RealServer IP  RealServer Admin Port  Administrator Login  Administrator Password 2. Add the following line to the RealServer crontab: 0 7 * * * nice -15 /hsphere/shared/scripts/cron/rmserver_analyze.pl 3. Launch RealServer with the following command: /hsphere/shared/RealServer/Bin/rmserver rmserver.cfg & 4. Log into your RealServer interface using administrator login and password. To get there, type this URL in address field of your browser: http://RS_IP:ADMIN_PORT/admin/index.html replacing RS_IP and ADMIN_PORT with the RealServer IP and admin port you were given during the installation. 5. In the left menu, select Server Setup -> Mount Points. 6. In the form that appears, add mount point /shiva/ -> /hsphere/local/home: RealServer 407 408 RealServer 7. Click Apply. The status window will open: Close this window. 8. Click Restart Server in the upper right corner of the browser window to restart RealServer: RealServer 9. Select Content Management -> ISP Hosting in the left menu: 409 410 RealServer 10. In the ISP Hosting form, add the following settings: Translation Mounts: user User List File Name: /hsphere/local/config/RealServer/user.list Description: users Mount Point: /shiva/ User Path: /shiva/ RealServer 11. Click Apply. The status window will open: Close this window. 12. Click About in the upper left corner of the browser window: 411 412 RealServer You will get a window with information about your license. 13. Go to the admin control panel and add the box to Parallels H-Sphere as suggested in Adding Servers Step-By-Step of the Service Administrator Guide. 14. Now you can proceed to RealServer settings that are not related to Parallels H-Sphere. Here is an example of RealServer configuration file: http://hsphere.parallels.com/HSdocumentation/sysadmin/rmserver.cfg.html. RealServer Installation for Windows  To install RealServer for Windows: 1. Install RealServer with ISPHosting support 2. Add mount point /shiva/ -> /user's_home_directory *You can learn your home directory in the conf.inc file, next to the UserHome line. 3. Restart RealServer. 4. After that, at the ISPHosting page in the Translation Mounts window: add users (Description: users; Mount Point: /shiva/; User Path: /shiva/) add user list (Edit User List File Name in the directory where Parallels H-Sphere is installed: /HSPhere/RealServer/user.list) RealServer Config File Example RealServer 413 414 RealServer RealServer 415 416 RealServer RealServer 417 418 RealServer RealServer 419 CHAPTER 28 Softaculous Softaculous (http://www.softaculous.com/) is an auto installer of web applications. It is a third-party software that can be installed on H-Sphere-managed web servers. Only UNIX boxes are supported. In this chapter: Softaculous Installation for Unix ........................................................................ 421 Softaculous 421 Softaculous Installation for Unix There are two steps in Softaculous installation. First you need to install Softaculous on each UNIX box. This process is described in documentation provided by Softaculous. At the second step, you should enable Softaculous support in H-Sphere.  To install Softaculous: 1. Enable PHP and set PHP 5 as default PHP version on all Unix web servers on page Enterprise Manager / Physical Servers / / “Physical Server Parameters” button / PHP Configuration. 2. Follow the Softaculous installation instructions and install Softaculous on each of the UNIX boxes separetely. Installation should be done in the directory , value can be found in config files /hsphere/shared/apache/conf/lservers/web_.conf /hsphere/shared/apache2/conf/lservers/web_.conf , depending on apache version. Normally setting is /hsphere/shared/apache/htdocs. 3. Enable Softaculous in H-Sphere:  Log into your CP server as the cpanel user (see page 71).  Open hsphere.properties file: vi ~cpanel/shiva/psoft_config/hsphere.properties  Uncomment the Softaculous settings as displayed below: SOFTACULOUS_URL=softaculous/ SOFTACULOUS_ADMIN_URL=softaculous-admin/ , where SOFTACULOUS_URL and SOFTACULOUS_ADMIN_URL is the path on UNIX box document root to Softaculous user and administrator interface respectively.  Open the config file allow_access.properties: vi ~cpanel/shiva/psoft_config/allow_access.properties  Allow access to H-Sphere XML API from the Unix boxes where Softaculous has been enabled. Add the following line: ACCESS_ALLOW = ;;<...> (see page http://www.psoft.net/HSdocumentation/devel/hs_xml_api_security.html#access_ allow for details)  Restart the H-Sphere control panel (see page 59). 4. Log in as a site administrator and verify that Softaculous button is displayed on page Enterprise Manager / Logical Servers / / Additional options. 422 Softaculous 5. Log in as a site user and verify that Softaculous button is displayed on page Web Options.