Many users are initially daunted by the new system used for generating and managing Apache's core configuration file, httpd.conf. As mentioned in The Apache Configuration System direct edits of httpd.conf will no longer be preserved unless they are properly integrated with the new Apache configuration system. This section lists the various methods available for customizing the httpd.conf file. For most users, the apache config distiller tool or the use of include files are recommended.
httpd.conf changes not contained in a <VirtualHost>
* Includes - When EasyApache 3 is rebuilt using a different version of Apache, changes checked in using the apache config distiller will be replaced with default values to ensure compatibility with the new version of Apache. If you would like your changes to persist through such a rebuild, several include files can be used instead of editing the main httpd.conf. The WebHost Manager features an editor for these include files at Main >> Service Configuration >> Apache Setup >> Include Editor. Open the editor interface and select the appropriate location in httpd.conf and the desired Apache version. When you have finished editing the include file, click Update and your changes will be tested for syntactical validity.
NOTE: Virtually any Apache directives can be added using this method. Please make certain that any changes you make in this fashion will remain valid regardless of other configuration changes made in the WebHost Manager. For instance, if you are adding directives that pertain to mod_suphp, enclose them in an appropriate <IfModule> block.
- Code: Select all
<IfModule mod_suphp.c>
suPHP_ConfigPath /usr/local/lib/
</IfModule>
* Apache config distiller - Most changes to the non-VirtualHost sections of httpd.conf can be easily preserved using the apache config distiller tool. Simply run
- Code: Select all
/usr/local/cpanel/bin/apache_conf_distiller --update --main
- Code: Select all
/scripts/rebuildhttpdconf
* Custom Templates - The final method for preserving changes to the non-VirtualHost sections of httpd.conf is to create a custom template for Apache. This would be placed at /var/cpanel/templates/apache(1 or 2)/main.local and should be based on the template at /var/cpanel/templates/apache(1 or 2)/main.default. The templates located here are processed using the Template Toolkit and have access to the information contained in the configuration datastores used by the new configuration system. The same warning about ensuring your edits will remain valid when settings are changed in the WebHost Manager applies to this method. Additionally, if you create a main.local template the apache config distiller will no longer preserve changes to the non-VirtualHost sections in httpd.conf. The apache config distiller updates the main.default template only.
httpd.conf changes contained in a <VirtualHost>
* Includes - Like the main portion of httpd.conf, the VirtualHost containers also provide the ability to add customizations using Include files. At this time there is no graphical interface for creating and managing VirtualHost includes, so they must be manipulated manually. The include directory structure is not created automatically, but uses the following file structure:
o Individual VirtualHost
/usr/local/apache/conf/userdata/(ssl|std)/(1|2)
/<user>/<domain>/<something>.conf
o All VirtualHost containers
/usr/local/apache/conf/userdata/<something>.conf
o All VirtualHost containers for SSL or standard VirtualHosts
/usr/local/apache/conf/userdata/[ssl or std]/<something>.conf
o All VirtualHost containers for SSL or standard VirtualHosts with version specific settings
/usr/local/apache/conf/userdata/[ssl or std]/[1 or 2]/<something>.conf
o All of a users VirtualHost containers for SSL or standard VirtualHosts with version specific settings
/usr/local/apache/conf/userdata/[ssl or std]/[1 or 2]/ /<something>.conf
o Individual VirtualHost container for SSL or standard VirtualHosts with version specific settings
/usr/local/apache/conf/userdata/[ssl or std]/[1 or 2]/<user>/<domain>/<something> .conf
* Includes are located as the final directive in the VirtualHost container. As a result, default values in the VirtualHost can usually be overridden via the include files. Include files beginning with "cp_" are reserved for cPanel settings and can and will likely be automatically rewritten. After adding any new include files, they need checked for compatibility and httpd.conf needs made aware of it.
To verify that include files are valid with the running apache run:
- Code: Select all
/scripts/verify_vhost_includes
Add --help if you wish for additional information.
After that is complete you can ensure that cpanel includes are setup as per the userdata and have the VirtualHost Include directives updated by running /scripts/ensure_vhost_includes with the proper arguments:
- Code: Select all
/scripts/ensure_vhost_includes
Ensure all vhost includes are setup as per userdata.
/scripts/ensure_vhost_includes --help (this screen)
/scripts/ensure_vhost_includes --all-users | --user=USERNAME1 [--user=USERNAME2 --user=...] | --domain=DOMAIN1 [--domain=DOMAIN2 --domain=...]
'--verbose' have output reporting what it is doing
'--skip-file-check' will skip the check that makes sure the
setting in the userdata reflects what is on the filesystem
'--no-restart' will skip restarting Apache after httpd.conf is updated
'--debug' implies, --verbose and makes the verbose information include more achaic information about what its doing
NOTE: Due to a bug in Apache it is not possible to have any * characters in the middle of an include path. To work around this problem with wildcard subdomains, the leading * should be changed to wildcard_safe. For example, include files for *.mydomain.com would be placed in /usr/local/apache/conf/userdata/std/2/username/wildcard_safe.mydomain.com/
* Apache config distiller - The role of the apache config distiller in relation to VirtualHosts is often misunderstood. For the non-VirtualHost sections of httpd.conf, the apache config distiller creates the appropriate template to match the directives present and updates the datastore used to populate the template with values. For VirtualHosts, the apache config distiller DOES NOT update the templates in any way. It only updates the VirtualHost datastores in /var/cpanel/userdata/. This means that many items that are already listed in a VirtualHost can be changed with a direct edit to httpd.conf and the changes will be preserved by the apache config distiller to an extent. To invoke the apache config distiller for this purpose, run
- Code: Select all
/usr/local/cpanel/bin/apache_conf_distiller --update
- Code: Select all
/scripts/rebuildhttpdconf
* Custom Templates - Custom template files are also possible with VirtualHosts. The standard template files used for VirtualHosts are located at /var/cpanel/templates/apache(1 or 2)/vhost.default and /var/cpanel/templates/apache(1 or 2)/ssl_vhost.default. Templates named vhost.local or ssl_vhost.local can be created based on the default versions and they will be used in preference to the default templates. Changes made in this way will apply to all SSL or non-SSL VirtualHosts.
* It is also possible to create a custom template that only a single VirtualHost will use. To do so, create the template following the example of the vhost.default or ssh_vhost.default files (naming and location of the custom template are not important.) Next, open the VirtualHost datastore at /var/cpanel/userdata/<username>/<domain>.
Add a new line with the location of the custom template, and save.
o For Apache 1 the new line would read:
+ custom_vhost_template_ap1: /path/to/template
o For Apache 2 the new line would read:
+ custom_vhost_template_ap2: /path/to/template
* Custom templates offer complete control over how the VirtualHosts are written, and as a result make it very easy to "break" Apache by preventing the creation of a syntactically valid httpd.conf file. Use them with extreme care and always place directives that depends on the presence of a certain Apache module within appropriate <IfModule> blocks.
For more information please refer official cPanel site.
http://www.cpanel.net/support/docs/ea/ea3/customdirectives.html
