Easy Apache 3 & PHP
Adding Custom Directives to httpd.conf
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.
<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
/usr/local/cpanel/bin/apache_conf_distiller --update --mainafter making such a change to update the templates and datastores. Regenerating the httpd.conf file with/scripts/rebuildhttpdconfwill allow you to quickly verify that the change was properly stored. - 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:
- Individual VirtualHost
/usr/local/apache/conf/userdata/(ssl|std)/(1|2)
/<user>/<domain>/<something>.conf - All VirtualHost containers
/usr/local/apache/conf/userdata/<something>.conf - All VirtualHost containers for SSL or standard VirtualHosts
/usr/local/apache/conf/userdata/[ssl or std]/<something>.conf - 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 - 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 - 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
- Individual VirtualHost
- 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:/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_include_directiveswith the proper arguments.
Add --help if you wish for additional information.
To update the include files for a single user, run/scripts/ensure_vhost_includes --user=<username>.
To update include files for all users, run/scripts/ensure_vhost_includes --all-users.
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
/usr/local/cpanel/bin/apache_conf_distiller --update. Many additional checks are performed on the VirtualHost datastores, so it is possible changes made in this way will be silently ignored or rejected. Rebuild the httpd.conf file with/scripts/rebuildhttpdconfto verify that your changes were saved.
- 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.- For Apache 1 the new line would read:
custom_vhost_template_ap1: /path/to/template
- For Apache 2 the new line would read:
custom_vhost_template_ap2: /path/to/template
- For Apache 1 the new line would read:
- 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.