Apache Configuration System

Internal WHM & cPanel Changes
Now that the Apache configuration data is abstracted and stored separately from the actual configuration file, the cPanel and WHM need only to read and update the data stores when modifying Apache related items. Once the data stores have been updated, that information can be used to generate a new updated configuration file. Until the complete EasyApache configuration system is rolled out, modifications are made directly to the Apache configuration file and at the same time the data stores are updated. This will change in the future, allowing the data stores to be updated and processed using the template, yielding the same results.

Data Storage
The configuration system utilizes YAML format for data storage. YAML is a markup language designed to be human readable.

The primary configuration file for Apache is located at /var/cpanel/conf/apache/main. All directives and sections outside of VirtualHost sections are contained in this file. The data in this file is organized by sections, starting with “main”. The individual VirtualHost sections are separated based upon the user into directories named for each user in /var/cpanel/userdata. Inside the user’s directory are one file for domain mapping and an individual file for each VirtualHost section. Each file is named according to its ServerName setting. VirtualHost sections for SSL configuration are denoted by the “_SSL” extension to their filename. The user “nobody” is a special case where data is only stored and not currently used. That may change in the future.

Template Files
As mentioned earlier, the final Apache configuration template is generated from the default Apache configuration installed during an Apache build. There are some default values and required directives that are included in the resulting template file from items in the Cpanel::AdvConfig::apache::directives module. The resulting template file is stored in the directory /var/cpanel/template. Within the template directory is a versioned directory containing the actual template file. Currently there are only two versions, apache1 and apache2. Apache 2 and 2.2 configuration syntax is the same. This simplification may change in the future to separate these versions. The template file generated by the distiller is named “main.default”. This template file does not include the format for VirtualHost sections. They are handled in separate files and are not generated automatically. The template files for VirtualHost sections have been built by cPanel to ensure compatibility with cPanel’s numerous configuration options. The default templates are located in version specific directories inside /usr/local/cpanel/src/templates.

The template processing tool uses template files in the following order:

Main Configuration:



SSL VirtualHosts:


Virtual-Host templates can be overridden by including the following key in the userdata, the value of which should be the full path to the custom VirtualHost template:


Path: /usr/local/cpanel/bin/userdata_update
This utility is used to initialize, update, and possibly reset the userdata files. Userdata files contain the mappings of domains to their role and each VirtualHost’s minimal data. The utility draws upon information contained in the cPanel user files (/var/cpanel/users) and the existing Apache configuration file.

The userdata_update utility’s functionality can be altered by the following command line options:

* –reset
Ignore existing data, resetting all information to default values in accordance with cPanel configuration settings.

* –unpark-addons
A special flag rarely needed that analyzes the domain mapping for add-on domains and rectifies the situation where add-on domains are also listed as parked domains.

* –help
Displays the command line options

Path: /usr/local/cpanel/bin/apache_conf_distiller
Its functionality is covered in the proceeding text. Essentially this utility is used to distill the Apache configuration file into a template and update the userdata and Apache configuration data files. Flags worth knowing about:

* –help
Describes various command line options. Changes to the distiller’s operation will be documented here first.

* –verbose
Displays progress and action messages. Messages seen with the verbose flag do not necessarily indicate problems or failures, but are merely informational. If you’re having problems with the distiller, then running it with the verbose flag may more clearly indicate the root cause.

* –update
The update flag tells the distiller to update userdata and Apache configuration data as well as any associated templates.

* –reset
This causes the distiller to ignore existing datastore values and start from scratch. By default, the distiller merges existing datastores with newly distilled data.

* –pedantic
This causes the distiller to flag any directives it doesn’t know of as an error. By default, it will silently add unknown directives to the template and datastores.

* –main
This causes the distiller to ignore all VirtualHosts for the purpose of updating the main Apache configuration files and template. VirtualHost datastores will not be updated during the distiller run.

* –apache-conf=<path>
This flag allows you to distill a httpd.conf file that is not in the standard location. For instance, if you fix one of the httpd.conf.timestamp files to work, you can distill it into the data stores and template with this flag.

Path: /usr/local/cpanel/bin/ build_apache_conf This utility is synomous with the following scripts: (includes /scripts/rebuildhttpdconf and /scripts/buildhttpdconf). This tool activates the template processing system and generates a new Apache configuration.

Path: /usr/local/cpanel/bin/userdata_update This sets up an include file /usr/local/apache/conf/php.conf with the specified PHP configuration. Further documentation can be found by passing the “–help” command line option.


Path: /scripts/ensure_vhost_includes This sets up a series of directories under /usr/local/apache/conf/userdata with configuration files for various things like Tomcat. If for some reason this directory is missing or corrupted, running this script should correct the problem.
The “–help” command line option documents other options.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s