Customizing Server Configuration Files By Means Of Templates

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

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. Edit the /hsphere/local/home/cpanel/apache/etc/httpd.conf.tmpl.custom file according to your needs.
2. 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

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

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:

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. Edit the .custom files according to your needs:

   /hsphere/local/config/httpd/lsrv.conf.tmpl.custom
   /hsphere/local/config/httpd/httpd.conf.tmpl.custom

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

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

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

2. To immediately apply changes, restart Apache:

   /hsphere/shared/scripts/apache-restart

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. Edit the .custom files according to your needs:

   /hsphere/local/config/ftpd/proftpd.conf.tmpl.custom
   /hsphere/shared/config/ftpd/proftpd.conf.tmpl.custom

2. To immediately apply changes, run:

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

3. Restart FTP service

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. Edit the /hsphere/local/config/mysql/my.cnf_tmpl.custom file according to your needs.
2. 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. 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.

2. 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. Edit the /etc/named.conf.tmpl.custom file according to your needs.
2. 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

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.