Parallels H-Sphere Documentation System Administrator Guide

 

Customizing Server Configuration Files By Means Of Templates

(H-Sphere 2.5 and up; revised for H-Sphere 3.1)
 
 

Related Docs:   H-Sphere Updater

Last modified: 04 Aug 2008

 

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

Starting with H-Sphere 2.5, you can't customize some major service configuration files (for Web, mail, DNS, databases, etc.) directly, as your changes in these files will be overwritten with a consequent H-Sphere update! Instead, you need to create config file templates by means of the hsphere-update wrapper or with H-Sphere 2.5+ update script and customize these templates instead of default config files.

IMPORTANT:
config file templates are automatically created with H-Sphere 2.5+ installation. You need to create them by the H-Sphere updater only if you've just updated your H-Sphere from 2.4.3 to 2.5+ version, or if you update from 2.5/3.0 to 3.1+.

Service ctemplates option Default Templates Custom Templates
CP Apache httpdcp
/hsphere/pkg/scripts/templates/cpapache/httpd.conf.tmpl.default
/hsphere/local/home/cpanel/apache/etc/httpd.conf.tmpl.custom
CP Apache Extra Configs (HS 3.1+)
httpdcp_extra /hsphere/local/home/cpanel/apache/conf/extra/*.conf.tmpl.default
/hsphere/local/home/cpanel/apache/conf/extra/*.conf.tmpl.custom
Web Apache httpd
httpd2

For H-Sphere 2.5 and 3.0:

/hsphere/pkg/scripts/templates/apache/httpd.conf.tmpl.default
/hsphere/pkg/scripts/templates/apache/lsrv.conf.tmpl.default

For H-Sphere 3.1:

/hsphere/pkg/scripts/templates/hs-31/apache/httpd.conf.tmpl.default
/hsphere/pkg/scripts/templates/hs-31/apache/httpd2.conf.tmpl.default
/hsphere/pkg/scripts/templates/hs-31apache/lsrv.conf.tmpl.default

/hsphere/local/config/httpd/lsrv.conf.tmpl.custom
/hsphere/local/config/httpd/httpd.conf.tmpl.custom
/hsphere/local/config/httpd2/lsrv.conf.tmpl.custom
/hsphere/local/config/httpd2/httpd.conf.tmpl.custom
Extra Configs (HS 3.1+) httpd_extra
httpd2_extra
Apache 1.3: /hsphere/pkg/scripts/templates/hs-31/apache/extra.default/*.conf.tmpl.default
Apache 2.2: /hsphere/pkg/scripts/templates/hs-31/apache/extra2.default/*.conf.tmpl.default
Apache 1.3: /hsphere/local/config/httpd/extra/*.conf.tmpl.custom Apache 2.2: /hsphere/local/config/httpd2/extra/*.conf.tmpl.custom
PHP 4 php /hsphere/local/config/httpd/php5/php.ini.tmpl
/hsphere/local/config/httpd2/php5/php.ini.tmpl
/hsphere/local/config/httpd/php4/php.ini.tmpl.custom
/hsphere/local/config/httpd2/php4/php.ini.tmpl.custom
PHP 5 php /hsphere/local/config/httpd/php5/php.ini.tmpl
/hsphere/local/config/httpd2/php5/php.ini.tmpl
/hsphere/local/config/httpd/php5/php.ini.tmpl.custom
/hsphere/local/config/httpd2/php5/php.ini.tmpl.custom
FTP ftpd /hsphere/pkg/scripts/templates/proftpd/shared.proftpd.conf.tmpl.default
/hsphere/pkg/scripts/templates/proftpd/local.proftpd.conf.tmpl.default
/hsphere/local/config/ftpd/proftpd.conf.tmpl.custom
/hsphere/shared/config/ftpd/proftpd.conf.tmpl.custom
MySQL mysql Linux: /hsphere/pkg/scripts/templates/Linux/my.cnf_tmpl.default
FreeBSD: /hsphere/pkg/scripts/templates/FreeBSD/my.cnf_tmpl.default
/hsphere/local/config/mysql/my.cnf_tmpl.custom
PostgreSQL pgsql Linux: /hsphere/pkg/scripts/templates/Linux/postgresql.conf_tmpl.default
FreeBSD: /hsphere/pkg/scripts/templates/FreeBSD/postgresql.conf_tmpl.default
/hsphere/local/config/pgsql/postgresql.conf_tmpl.custom
DNS named /hsphere/pkg/scripts/templates/named/named.conf.tmpl.default
/etc/named.conf.tmpl.custom
/etc/resolv.conf.custom

Note: In Bind versions before 9.3.3rc1, custom template for /etc/resolv.conf is to be touched manually.

You can customize config file templates by means of H-Sphere updater, provided you have not customized your templates already. For this purpose two new options are added to the hspackages wrapper of the H-Sphere update script:

  • hspackages ctemplates=[OPTIONS] - Place custom templates for comma-separated list of services into predefined locations if custom templates are not there already.
  • hspackages edit=IP:/path/to/custom/template - Edit custom template on a specified server in a specified location.

Important:

  • If you run the hspackages ctemplates command without options, it will create custom templates on all related servers of the H-Sphere cluster! To specify particular servers where custom config templates should be created, please use the extended syntax of the hspackages command. For example, to create PHP custom config templates only on the physical boxes 192.168.1.10 and 192.168.1.11, run:

    hspackages ctemplates=php ips=192.168.1.10,192.168.1.11

  • The hspackages ctemplates command should be run only once, in order to create custom config templates! Then you customize these files according to your needs. Next time you run it, it will prompt re-creating your custom config templates, thus you may lose your customization!
    Note: The only exclusion when you need to run hspackages ctemplates again is when a coming version of the hsphere-update package contains updates of default config templates. You will be specially notified of this in the respective update notes.

 

CP Apache

Default CP Apache httpd.conf template is included into the hsphere-update and installed here:

/hsphere/pkg/scripts/templates/cpapache/httpd.conf.tmpl.default

To customize the template:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=httpdcp option:

      hspackages ctemplates=httpdcp [OPTIONS]

      Custom template will be placed into the following location:
      /hsphere/local/home/cpanel/apache/etc/httpd.conf.tmpl.custom

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the /hsphere/local/home/cpanel/apache/etc/httpd.conf.tmpl.custom file according to your needs.
  3. To immediately apply changes, run the conf file generating script which is as a rule executed in the postinstall section of the package:

    H-Sphere 2.5 and 3.0:

    /hsphere/local/home/cpanel/apache/bin/conf_httpdcp

    H-Sphere 3.1+:

    /hsphere/shared/scripts/apache-restart

Note: After H-Sphere 3.1 update previously customized templates will be ignored! You need to re-customize them according to the above described procedure.

 

Extra CP Apache Configs

(HS 3.1+)

H-Sphere 3.1 and up allows to customize some extra Apache config files for CP. They are located in the /hsphere/local/home/cpanel/apache/conf/extra/ directory:

  • httpd-autoindex.conf - directives controlling the display of server-generated directory listings
  • httpd-cache.conf - directived providing HTTP content cache configuration
  • httpd-info.conf - Apache status-related directive blocks
  • httpd-languages.conf - directives which the provide mod_mime and mod_negotiation modules global configuration
  • vh-ssl-default.conf - Global SSL default VirtualHost configuration

These extra config files are provided for easier configuration of Apache modules, such as mod_cache, mod_security, etc.

After the config file customization, the correspondent *.tmpl.custom files will be created in the same directory:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for H-Sphere 3.1 version, e.g.:

      wget http://www.psoft.net/shiv/HS/releases/U31.0/U31.0b1/U30.0b1

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U31.0b1

    3. Execute the hspackages wrapper with the ctemplates=httpdcp_extra option:

      hspackages ctemplates=httpdcp_extra [OPTIONS]

      After that, custom templates /hsphere/local/home/cpanel/apache/conf/extra/*.tmpl.custom will be created.

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the /hsphere/local/home/cpanel/apache/conf/extra/*.tmpl.custom files according to your needs:
  3. To immediately apply changes, restart Apache:

    /hsphere/shared/scripts/apache-restart

 

Apache

Default config Apache templates are included into the hsphere-update package and installed in the following locations:

For H-Sphere 2.5 and 3.0:

/hsphere/pkg/scripts/templates/apache/httpd.conf.tmpl.default
/hsphere/pkg/scripts/templates/apache/lsrv.conf.tmpl.default

For H-Sphere 3.1:

/hsphere/pkg/scripts/templates/hs-31/apache/httpd.conf.tmpl.default
/hsphere/pkg/scripts/templates/hs-31/apache/httpd2.conf.tmpl.default
/hsphere/pkg/scripts/templates/hs-31apache/lsrv.conf.tmpl.default

To customize them, perform:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=httpd option for Apache 1.3 and/or ctemplates=httpd2 option for Apache 2.2:

      hspackages ctemplates=httpd [OPTIONS]

      Custom templates will be placed into the following locations:
      /hsphere/local/config/httpd/lsrv.conf.tmpl.custom
      /hsphere/local/config/httpd/httpd.conf.tmpl.custom
      /hsphere/local/config/httpd2/lsrv.conf.tmpl.custom
      /hsphere/local/config/httpd2/httpd.conf.tmpl.custom

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the .custom files according to your needs:
    /hsphere/local/config/httpd/lsrv.conf.tmpl.custom
    /hsphere/local/config/httpd/httpd.conf.tmpl.custom
  3. To immediately apply changes, run the conf file generating script which is as a rule executed in the postinstall section of the package:

    For H-Sphere 2.5 or 3.0:

    /hsphere/shared/apache/bin/conf_httpd

    For H-Sphere 3.1 and up:

    /hsphere/shared/scripts/apache-restart

Note: After H-Sphere 3.1 update previously customized templates will be ignored! You need to re-customize them according to the above described procedure.

 

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

If you need to leave /hsphere/shared/apache/htdocs/index.html unchanged after the update, create the following file:

touch /hsphere/local/config/httpd/index.html.custom

If the latter file exists, then you can customize your index.html file without the risk of its being overwritten.

 

Extra Apache Configs

(HS 3.1+)

H-Sphere 3.1 and up allows to customize some extra Apache config files, such as:

  • httpd-autoindex.conf - directives controlling the display of server-generated directory listings
  • httpd-cache.conf - directived providing HTTP content cache configuration (Apache 2.2 only)
  • httpd-gzip.conf - directives for global settings provided by the mod_gzip module (Apache 1.3 only)
  • httpd-info.conf - Apache status-related directives
  • httpd-languages.conf - directives which the provide mod_mime and mod_negotiation modules global configuration
  • httpd-security.conf - ModSecurity configuration options
  • httpd-security2.conf - ModSecurity v.2 configuration options (Apache 2.2 only)
  • vh-ssl-default.conf - global SSL default VirtualHost configuration

Default templates *.tmpl.defaiult for these config files are installed with hsphere-updater to the following directories:

Apache 1.3: /hsphere/pkg/scripts/templates/hs-31/apache/extra.default/
Apache 2.2: /hsphere/pkg/scripts/templates/hs-31/apache/extra2.default/

After H-Sphere 3.1 update, the respective custom .tmpl.custom files will be created in the following directories:

Apache 1.3: /hsphere/local/config/httpd/extra/ Apache 2.2: /hsphere/local/config/httpd2/extra/

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for H-Sphere 3.1 version, e.g.:

      wget http://www.psoft.net/shiv/HS/releases/U31.0/U31.0b1/U30.0b1

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U31.0b1

    3. Execute the hspackages wrapper with the ctemplates=httpd_extra option:

      hspackages ctemplates=httpd_extra [OPTIONS]

      After that, custom templates *.tmpl.custom will be created in respective directories.

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the *.tmpl.custom files according to your needs:

    Apache 1.3: /hsphere/local/config/httpd/extra/*.tmpl.custom
    Apache 2.2: /hsphere/local/config/httpd2/extra/*.tmpl.custom

  3. To immediately apply changes, restart Apache:

    /hsphere/shared/scripts/apache-restart

 

PHP 4

PHP 4 config files are located:

  • For H-Sphere before 3.1:
    /hsphere/local/config/httpd/php4/php.ini
  • For H-Sphere v. 3.1:
    /hsphere/local/config/httpd/php4/php.ini.tmpl.custom (when PHP4 uses fastcgi, for all Apache versions)
    /hsphere/local/config/httpd/php4/php.ini.tmpl.custom (when libphp5 is used, for Apache 1.x)
    /hsphere/local/config/httpd2/php4/php.ini.tmpl.custom (when libphp5 is used, for Apache 2.x)

To customize PHP 4 config files:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=php option:

      hspackages ctemplates=php [OPTIONS]

      Custom templates will be placed into the following location:
      /hsphere/local/config/httpd/php4/php.ini.tmpl.custom
      /hsphere/local/config/httpd2/php4/php.ini.tmpl.custom

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the above mentioned tmpl.custom files according to your needs.
  3. To immediately apply changes, copy:

    cp -p /hsphere/local/config/httpd/php4/php.ini.tmpl.custom /hsphere/local/config/httpd/php4/php.ini
    cp -p /hsphere/local/config/httpd2/php4/php.ini.tmpl.custom /hsphere/local/config/httpd2/php4/php.ini

  4. Restart Apache service

 

PHP 5

PHP 5 config files are located:

  • For H-Sphere before 3.1:
    /hsphere/local/config/httpd/php5/php.ini
  • For H-Sphere v. 3.1:
    /hsphere/local/config/httpd/php5/php.ini.tmpl.custom (when PHP4 uses fastcgi, for all Apache versions)
    /hsphere/local/config/httpd/php5/php.ini.tmpl.custom (when libphp5 is used, for Apache 1.x)
    /hsphere/local/config/httpd2/php5/php.ini.tmpl.custom (when libphp5 is used, for Apache 2.x)

To customize PHP 5 config files:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=php option:

      hspackages ctemplates=php [OPTIONS]

      Custom templates will be placed into the following location:
      /hsphere/local/config/httpd/php5/php.ini.tmpl.custom
      /hsphere/local/config/httpd2/php5/php.ini.tmpl.custom

    Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the above mentioned tmpl.custom files according to your needs.
  3. To immediately apply changes, copy:

    cp -p /hsphere/local/config/httpd/php5/php.ini.tmpl.custom /hsphere/local/config/httpd/php5/php.ini
    cp -p /hsphere/local/config/httpd2/php5/php.ini.tmpl.custom /hsphere/local/config/httpd2/php5/php.ini

  4. Restart Apache service

 

FTP

FTP config file templates are included into the hsphere-update package and installed in the following locations:

/hsphere/pkg/scripts/templates/proftpd/shared.proftpd.conf.tmpl.default
/hsphere/pkg/scripts/templates/proftpd/local.proftpd.conf.tmpl.default

To customize these templates, perform:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=ftpd option:

      hspackages ctemplates=ftpd [OPTIONS]

      Custom templates will be placed into the following locations:
      /hsphere/local/config/ftpd/proftpd.conf.tmpl.custom
      /hsphere/shared/config/ftpd/proftpd.conf.tmpl.custom

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the .custom files according to your needs:
    /hsphere/local/config/ftpd/proftpd.conf.tmpl.custom
    /hsphere/shared/config/ftpd/proftpd.conf.tmpl.custom
  3. To immediately apply changes, run:

    /hsphere/shared/config/ftpd/configure-proftpd.sh

  4. Restart FTP service

Note: After H-Sphere 3.1 update previously customized templates will be ignored! You need to re-customize them according to the above described procedure.

 

MySQL

MySQL config file templates are included into the hsphere-update package and installed in the following locations:

Linux: /hsphere/pkg/scripts/templates/FreeBSD/my.cnf_tmpl.default
FreeBSD: /hsphere/pkg/scripts/templates/Linux/my.cnf_tmpl.default

To customize these templates, perform:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=mysql option:

      hspackages ctemplates=mysql [OPTIONS]

      Custom templates will be placed into the following location:
      /hsphere/local/config/mysql/my.cnf_tmpl.custom
      More on customizing config templates by H-Sphere updater.

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the /hsphere/local/config/mysql/my.cnf_tmpl.custom file according to your needs.
  3. To immediately apply changes, run the conf file generating script which is as a rule executed in the package postinstall section:

    /hsphere/local/config/mysql/scripts/config_mysql

 

PostgreSQL

PostgreSQL config file templates are included into the hsphere-update package and installed in the following locations:

Linux: /hsphere/pkg/scripts/templates/FreeBSD/postgresql.conf_tmpl.default
FreeBSD: /hsphere/pkg/scripts/templates/Linux/postgresql.conf_tmpl.default

To customize these templates, perform:

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=pgsql option:

      hspackages ctemplates=pgsql [OPTIONS]

      Custom templates will be placed into the following location:
      /hsphere/local/config/pgsql/postgresql.conf_tmpl.custom

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the /hsphere/local/config/pgsql/postgresql.conf_tmpl.custom file according to your needs.

    Important: By default, PostgreSQL listens on localhost (parameter virtual_host=127.0.0.1 in config file). Change this parameter if required.

  3. To immediately apply changes, run the conf file generating script which is as a rule executed in the package postinstall section:

    /hsphere/local/config/pgsql/scripts/config_pgsql

 

DNS

/etc/named.conf, /etc/resolv.conf (since hsphere-bind-9.3.3rc1-1)

/etc/named.conf

Default template is located at /hsphere/pkg/scripts/templates/named/named.conf.tmpl.default

  1. Create custom config template if required. Otherwise, skip this step.
    1. Download H-Sphere updater for your version, e.g.:

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

    2. Run H-Sphere update script for your version, e.g.:

      sh ./U30.0P6

    3. Execute the hspackages wrapper with the ctemplates=named option:

      hspackages ctemplates=named [OPTIONS]

      Custom template will be placed into the following location:
      /etc/named.conf.tmpl.custom

      Important: Please carefully read the about hspackages ctemplates and especially the note about its options!

  2. Edit the /etc/named.conf.tmpl.custom file according to your needs.
  3. To immediately apply changes, run the conf file generating script which is as a rule executed in the postinstall section of the package:

    /hsphere/local/config/bind/scripts/config_bind

Important: Starting with hsphere-bind-9.3.1-2, the directive include ~named/local/custom.conf is added into /etc/named.conf.

/etc/resolv.conf

(since hsphere-bind-9.3.3rc1-1)

To leave /etc/resolv.conf unchanged during the update (e.g., when MyDNS is used), perform:

touch /etc/resolv.conf.custom

If the latter file exists, then you can customize your /etc/resolv.conf file without the risk of its being overwritten.

 

Customizing Other Files Included into H-Sphere Packages

WARNING:
It is not recommended that you customize the files included into H-Sphere packages by yourself. Any alterations made to them are at your own risk!

Besides customization of some major service configuration files (for Web, mail, DNS, databases, etc.), we have implemented for your convenience a possibility to customize other files included into H-Sphere packages. For this, we have created a configuration file /hsphere/local/config/customs/customs.conf and a special template /hsphere/local/config/customs/customs.conf.tmpl that will help you to save customized H-Sphere packages files during future updates.

To customize a file included into H-Sphere Package and save the changes:

  1. Make necessary changes to the file you want to customize.
  2. Copy a template of custom files to a configuration file:

    cp -p /hsphere/local/config/customs/customs.conf.tmpl /hsphere/local/config/customs/customs.conf

  3. Go to the customs.conf file
  4. Add the full path to the customized file(-s) under the mask of the relevant package, e.g.:

    [hsphere-imap-h2.5]
    /etc/rc.d/init.d/courier-imapd
    /etc/rc.d/init.d/courier-imapd-ssl
    /hsphere/local/config/mail/imap/etc/imapd
    /hsphere/local/config/mail/imap/etc/imapd-ssl

Please note that during the package updates all custom files will be saved in the /hsphere/local/config/customs/$package_mask/ directory. The default files of H-Sphere packages, in their turn, will be stored at /hsphere/local/config/customs/default/$package_mask/. The above mentioned locations store the latest versions of both custom and default files, no matter custom or default file is being used.


Related Docs:   H-Sphere Updater



© Copyright 2017. Parallels Holdings. All rights reserved.