Changes Contained within a VirtualHost Directive

This section regards custom changes to httpd.conf inside a VirtualHost directive.

Using Include Files

VirtualHost containers can also accept include files. However, at this point, there is no graphical interface for creating and managing these includes. This means that, if you would like to use an include inside a VirtualHost container, you will have to add and manage it manually.

It is important to note that the include directory structure is not created for you. You will need to create and use the following file structures:

For an individual VirtualHost container:

• Apache 1 with SSL — /usr/local/apache/conf/userdata/ssl/1/$user/$domain/$includename.conf
• Apache 2 with SSL — /usr/local/apache/conf/userdata/ssl/2/$user/$domain/$includename.conf
• Apache 1 without SSL — /usr/local/apache/conf/userdata/std/1/$user/$domain/$includename.conf
• Apache 2 without SSL — /usr/local/apache/conf/userdata/std/2/$user/$domain/$includename.conf

For all VirtualHost containers:

• /usr/local/apache/conf/userdata/$includename.conf

For all SSL VirtualHost containers:

• /usr/local/apache/conf/userdata/ssl/$includename.conf

For all standard VirtualHost containers:

• /usr/local/apache/conf/userdata/std/$includename.conf

For all VirtualHost containers for SSL Apache version 1:

• /usr/local/apache/conf/userdata/ssl/1/$includename.conf

For all VirtualHost containers for SSL Apache version 2:

• /usr/local/apache/conf/userdata/ssl/2/$includename.conf

For all VirtualHost containers with SSL or standard VirtualHosts with version-specific settings:

• Apache 1 with SSL — /usr/local/apache/conf/userdata/ssl/1/$includename.conf
• Apache 2 with SSL — /usr/local/apache/conf/userdata/ssl/2/$includename.conf
• Apache 1 without SSL — /usr/local/apache/conf/userdata/std/1/$includename.conf
• Apache 2 without SSL — /usr/local/apache/conf/userdata/std/2/$includename.conf

For all of a user’s containers for SSL or standard VirtualHosts with version-specific settings:

• Apache 1 with SSL — /usr/local/apache/conf/userdata/ssl/1/$user/$includename.conf
• Apache 2 with SSL — /usr/local/apache/conf/userdata/ssl/2/$user/$includename.conf
• Apache 1 without SSL — /usr/local/apache/conf/userdata/std/1/$user/$includename.conf
• Apache 2 without SSL — /usr/local/apache/conf/userdata/std/2/$user/$includename.conf

For individual VirtualHost containers for SSL or standard VirtualHosts with version-specific settings:

• Apache 1 with SSL — /usr/local/apache/conf/userdata/ssl/1/$user/$domain/$includename.conf
• Apache 2 with SSL — /usr/local/apache/conf/userdata/ssl/2/$user/$domain/$includename.conf
• Apache 1 without SSL — /usr/local/apache/conf/userdata/std/1/$user/$domain/$includename.conf
• Apache 2 without SSL — /usr/local/apache/conf/userdata/std/2/$user/$domain/$includename.conf

Includes are located as the last directive in a VirtualHost container. This allows you to override default values using the include files. Include files that begin with cp_ are reserved for cPanel settings. These settings will most likely be overwritten automatically. Thus, altering these files is probably futile.

After adding new include files, you will need to check for compatibility. To verify that the include files are valid with Apache, run the following command in a terminal session:

• /scripts/verify_vhost_includes

For additional information, use the following command:

• /scripts/verify_vhost_includes --help

To ensure that cPanel-created include files (whose filenames begin with cp_) are in sync with a particular user's settings (or "userdata"), execute the following command:

• /scripts/ensure_vhost_includes --user=$username

To ensure that cPanel-created include files (whose filenames begin with cp_) are in sync with all users' settings (or "userdata"), execute the following command:

• /scripts/ensure_vhost_includes --all-users

Remember: You cannot use an asterisk (*) in the middle of an include path. If you need to work around this problem for wild card subdomains, the leading * should be changed to wildcard_safe. For example *.example.com, a standard Apache 2 domain, would be placed in /usr/locall/apache/conf/userdata/std/2/wildcard_safe.mydomain.com.

Apache Config Distiller

With regard to VirtualHost data, the Apache config distiller does not update the templates in any way. The distiller, in this case, simply updates the datastores within /var/cpanel/userdata. This means that direct edits made to a VirtualHost within httpd.conf can be preserved.

To ensure that your direct edits have been preserved, you can use the following script:

• /usr/local/cpanel/bin/apache_conf_distiller --update

Because many checks are performed on VirtualHost datastores, it is possible that changes made directly to httpd.conf will be ignored or rejected. To see whether your changes will be saved, rebuild the httpd.conf file by using the following script:

• /scripts/rebuildhttpdconf

Custom Templates

Warning: Custom templates offer complete control over how virtual hosts are written. However, if they are misconfigured, Apache may be prevented from generating a syntactically valid httpd.conf file. This will result in a server that doesn’t respond to HTTP requests. Use caution when creating custom templates and remember to place directives that rely on the certain Apache modules within appropriate <IfModule> blocks.

Custom templates that will apply to all virtual hosts when rebuilding an existing Apache configuration

To create custom template files that affect all virtual hosts:

1. Create a copy of one or more of the following files:
   • Apache 1 without SSL — /var/cpanel/templates/apache1/vhost.default
   • Apache 2 without SSL — /var/cpanel/templates/apache2/vhost.default
   • Apache 1 with SSL — /var/cpanel/templates/apache1/ssl_vhost.default
   • Apache 2 with SSL — /var/cpanel/templates/apache2/ssl_vhost.default
2. Rename the copied file to one of the following:
   • vhost.local — use this if you copied vhost.default.
   • ssl_vhost.local — use this if you copied ssl_vhost.default.
3. Edit the *.local files to make the changes you would like to your virtual host configuration.

Important: This method affects all of your virtual hosts as the .local file(s) will be used in place of the .default file(s).

Custom templates that will apply to a single virtual host when rebuilding an existing Apache configuration

To create a custom template that affects only a single virtual host:

1. Create a copy of one or more of the following files:
   • Apache 1 without SSL — /var/cpanel/templates/apache1/vhost.default
   • Apache 2 without SSL — /var/cpanel/templates/apache2/vhost.default
   • Apache 1 with SSL — /var/cpanel/templates/apache1/ssl_vhost.default
   • Apache 2 with SSL — /var/cpanel/templates/apache2/ssl_vhost.default
2. Rename the copied file to one of the following:
   • vhost.local — use this if you copied vhost.default.
   • ssl_vhost.local — use this if you copied ssl_vhost.default.
3. Edit the *.local files to make the changes you would like to your virtual host configuration.
4. Move the *.local file to another directory.
   • Note: Any separate directory will do, as you will specify the location of the file.
5. Use the following script to add the necessary information to the data structure:
   • perl -MYAML::Syck -e 'my $hr = YAML::Syck::LoadFile($ARGV[0]);$hr->{$ARGV[1]} = $ARGV[2];YAML::Syck::DumpFile($ARGV[0],$hr);' /var/cpanel/userdata/$username/$domainname $key $path/to/template
   • The $key value should be:
     • custom_vhost_template_ap1 for Apache 1
     • custom_vhost_template_ap2 for Apache 2

Custom Templates for New Accounts

When a new account is created, the templates located in /var/cpanel/templates/ are not used. Instead, the system uses the following files:

• Apache 1 without SSL — /usr/local/cpanel/etc/httptemplates/apache1/default
• Apache 1 with SSL — /usr/local/cpanel/etc/httptemplates/apache1/ssldefault
• Apache 2 without SSL — /usr/local/cpanel/etc/httptemplates/apache2/default
• Apache 2 with SSL — /usr/local/cpanel/etc/httptemplates/apache2/ssldefault
• Apache 2.2 without SSL — /usr/local/cpanel/etc/httptemplates/apache2_2/default
• Apache 2.2 with SSL — /usr/local/cpanel/etc/httptemplates/apache2_2/ssldefault

Warning: The system will not look for a custom template (.local file) within these directories. To create a custom template, you may rewrite the contents of a file, using the same filename. However, each of these files will be overwritten any time you update cPanel (run /scripts/upcp).

To maintain custom templates for new accounts:

1. Create your custom version of the above file(s).
2. Store these file(s) in a safe directory, where they will not be overwritten.
3. Create a postupcp script that replaces the default file(s) with your custom version(s). A postupcp script will automatically run after every cPanel update.

Custom Templates for Subdomains and Addon Domains

To create custom template files that affect your subdomains and addon domains:

1. Create a copy of one or more of the following files:
   • Apache 1 without SSL — /var/cpanel/templates/apache1/vhost.default
   • Apache 2 without SSL — /var/cpanel/templates/apache2/vhost.default
   • Apache 1 with SSL — /var/cpanel/templates/apache1/ssl_vhost.default
   • Apache 2 with SSL — /var/cpanel/templates/apache2/ssl_vhost.default
2. Rename the copied file to one of the following:
   • vhost.local — use this if you copied vhost.default.
   • ssl_vhost.local — use this if you copied ssl_vhost.default.
3. Edit the *.local files to make the changes you would like to your virtual host configuration.

Important: This method affects all of your virtual hosts as the .local file(s) will be used in place of the .default file(s).

Custom Templates for Parked Domains

Parked domains are simply aliased to your server. There are no custom templates for you to edit as they are not needed.

More info about files in /var/cpanel/userdata/

Files located within subdirectories of the /var/cpanel/userdata/ directory are written in YAML format (for more information, see http://yaml.org/).

In addition, these files are loaded into a template variable called 'vhost.' For more information, see http://template-toolkit.org/.

For example, inside of a YAML file, you may see a line that looks like this:

foo: hello world

That is a YAML-format entry of a single key/value pair of a hash. This means that there is a corresponding key called "foo" with a value of "hello world," that you are able to use in your template.

Foo "[% vhost.foo %]" would render as Foo "hello world"

Manually editing a YAML file (such as the userdata file) can break the YAML format. Use a tool, such as the command in step 5 above, to edit it for you.