Parallels H-Sphere Documentation System Administrator Guide


H-Sphere Apache

(H-Sphere 3.1 Beta 1 and up)

Related Docs:   Web Server Configuration H-Sphere PHP

Last modified: 27 Dec 2007


WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the official Parallels site.

In H-Sphere 3.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 document describes the main changes in the Web service software and includes information on Apache configuration important for H-Sphere system administrators.


Web Service Packages in H-Sphere 3.1+

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 H-Sphere 3.1 Beta 1 and up (note that versions are just examples that may differ from current ones):

Package Description Comment
hsphere-apache2-h3.1-2.2.6-x Apache 2.2.x binaries, modules, libraries and headers Package updates
hsphere-apache-h3.1-1.3.39-x Apache 1.3.x binaries, modules, libraries and headers Package updates
hsphere-apache-shared-h3.1-1-x Configuration template files, scripts, startup files, etc. common for Apache 1.3.x and 2.2.x Package updates
hsphere-apache-utils-h3.1-1-x Utilities used when parsing apache logs, lynx browser, etc. Package updates
hsphere-php4-1x-4.4.7-x libphp4 for Apache 1.3.x Package updates
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
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 Package updates
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:

For the MPM worker mode, cgi requests are processed via mod_cgid.


Tuning Web Service from the CP Interface

In 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:

All webbox related settings chosen from the cp interface are stored in the following file:

Such changes are applied immediately by the script:
/hsphere/shared/scripts/ httpd restart

The settings are stored in the configuration file in the form of 'prefix_title=value. There are several groups of settings:


Apache Settings

These are settings for enabling/disabling Apache modules. The prefix is apache. Here is the list of possible settings:

Title Default Value Comments
apache_libphp4 1  
apache_libphp5 0  
apache_ssl 1  
apache_scgi 0  
apache_frontpage 0 Ignored in Apache 2
apache_throttle 0 Ignored in Apache 2
apache_status 0  
apache_fastcgi 0  
apache_security 0  
apache_cache 0  
apache_security2 0 Ignored in Apache 1
apache_version 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 Comments
php_libphp4 2  
php_fastcgi4 0 Needs mod_fastcgi being enabled for Apache
php_cgi4 1  
php_libphp5 0 If the value is other than 0, the value for php_libphp4 has to be 0
php_fastcgi5 2  
php_cgi5 1  


Fastcgi Settings

Fastcgi, 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 Comments
autoUpdate   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_ROLE Allows to check which fastcgi setting is being used. RubyOnRails may need additional variables.
init-start-delay 1 [seconds]  
killInterval 300 [seconds]  
listen-queue-depth 100  
maxClassProcesses 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 If only one instance remains, singleThreshold is used instead
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

As in H-Sphere 2.5, 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:

ls /hsphere/shared/apache/libexec/ - for Apache 1.3
ls /hsphere/shared/apache2/modules/ - for Apache 2.2

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 H-Sphere via the mod_macro module. Apache 2.2 adds several new modules to extend functionality.

[-] Click + to see the comparative list of modules (the titles correspond to *.so files).
Apache 1.3 Apache 2.2
libphp4* libphp4*
libphp5** libphp5**
libssl mod_ssl
mod_actions mod_actions
mod_alias mod_alias
mod_auth_dbm mod_authz_dbm
mod_auth_external mod_authnz_external
mod_auth_kerb mod_auth_kerb
mod_autoindex mod_autoindex
mod_cern_meta mod_cern_meta
mod_cgi mod_cgi
mod_dir mod_dir
mod_env mod_env
mod_expires mod_expires
mod_extract_forwarded mod_extract_forwarded
mod_fastcgi mod_fastcgi
mod_headers mod_headers
mod_include mod_include
mod_info mod_info
mod_log_config mod_log_config
mod_log_forensic mod_log_forensic
mod_macro mod_macro
mod_mime mod_mime
mod_mime_magic mod_mime_magic
mod_negotiation mod_negotiation
mod_rewrite mod_rewrite
mod_scgi mod_scgi
mod_security mod_security
mod_setenvif mod_setenvif
mod_speling mod_speling
mod_status mod_status
mod_unique_id mod_unique_id
mod_userdir mod_userdir
mod_usertrack mod_usertrack
mod_vhost_alias mod_vhost_alias

*Part of the hsphere-php5-Xx-{PHPVER} package where X is apache version (1 or 2).
**Part of the hsphere-php4-Xx-{PHPVER} 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 Comments
/hsphere/shared/apache /hsphere/shared/apache2 Apache home directory
/hsphere/local/config/httpd /hsphere/local/config/httpd2 Apache configuration directory
~httpd/conf -> /hsphere/local/config/httpd   The symlink from home directory
Configuration File
/hsphere/local/config/httpd/httpd.conf /hsphere/local/config/httpd2/httpd.conf This file contains server wide configuration (modules enabled, their parameters set etc.). We don't recommend making changes 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 <IfDefine ...> directives and corresponding global symbols.
These files are customized using config file templates.
Read more on config file template customization
Custom Configuration File
/hsphere/local/config/httpd/custom.conf /hsphere/local/config/httpd2/custom.conf We recommend using this file 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/namevh.conf /hsphere/local/config/httpd2/namevh.conf 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. 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
mail.conf, mrtg.conf, mysql.conf...
mail.conf, mrtg.conf, mysql.conf...
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.
Read more on config file template customization
/hsphere/local/config/httpd/sites/ 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 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 html-like 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.


Changes in 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 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/{user}/logs/{}/ directory (see Web traffic calculation).

There are two types of Web traffic calculation in H-Sphere:

Please refer to a separate document on Web traffic calculation and log rotation in H-Sphere for version 2.5 and up and for versions before 2.5.


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


Apache Suexec

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 H-Sphere user home directory, for example, /hsphere/local/home/user_home1.

Related Docs:   Web Server Configuration H-Sphere PHP

© Copyright 2017. Parallels Holdings. All rights reserved.