<-- 

 Set PAGETITLE = Changes Contained within a VirtualHost Directive
 
-->

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

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) above with your custom version(s). A postupcp script will automatically run after every cPanel update.

Custom Templates for New Accounts

• 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

Unlike the templates located in /var/cpanel/templates/, you will not need to copy and rename the template files. Simply edit the contents of the file to match how you would like new accounts, subdomains, and addon domains to be configured.

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

• Apache 1 without SSL — /var/cpanel/templates/apache1/vhost.local
• Apache 1 with SSL — /var/cpanel/templates/apache1/ssl_vhost.local
• Apache 2 without SSL — /var/cpanel/templates/apache2/vhost.local
• Apache 2 with SSL — /var/cpanel/templates/apache2/ssl_vhost.local
• Apache 2.2 without SSL — /var/cpanel/templates/apache2_2/vhost.local
• Apache 2.2 with SSL — /var/cpanel/templates/apache2_2/ssl_vhost.local

Changes Contained within a VirtualHost Directive

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

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

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

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

• Apache 2 without SSL — /usr/local/apache/conf/userdata/std/2/$user/$domain/$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/$user/$includename.conf

• 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

• 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

• • 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:

Changes Contained within a VirtualHost Directive

• 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

• 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

• 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

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

• • /var/cpanel/templates/apache1/vhost.default — to affect Apache 1 virtual hosts that do not use SSL.
  • /var/cpanel/templates/apache2/vhost.default — to affect Apache 2 virtual hosts that do not use SSL.
  • /var/cpanel/templates/apache1/ssl_vhost.default — to affect Apache 1 virtual hosts that use SSL.
  • /var/cpanel/templates/apache2/ssl_vhost.default — to affect Apache 2 virtual hosts that use SSL.

• • vhost.local — use this if you copied vhost.default.
  • ssl_vhost.local — use this if you copied ssl_vhost.default.

• • /var/cpanel/templates/apache1/vhost.default — to affect Apache 1 virtual hosts that do not use SSL.
  • /var/cpanel/templates/apache2/vhost.default — to affect Apache 2 virtual hosts that do not use SSL.
  • /var/cpanel/templates/apache1/ssl_vhost.default — to affect Apache 1 virtual hosts that use SSL.
  • /var/cpanel/templates/apache2/ssl_vhost.default — to affect Apache 2 virtual hosts that use SSL.

• • vhost.local — use this if you copied vhost.default.
  • ssl_vhost.local — use this if you copied ssl_vhost.default.

• 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

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/$profilename.conf
• Apache 2 with SSL -- /usr/local/apache/conf/userdata/ssl/2/$user/$domain/$profilename.conf
• Apache 1 without SSL -- /usr/local/apache/conf/userdata/std/1/$user/$domain/$profilename.conf
• Apache 2 without SSL -- /usr/local/apache/conf/userdata/std/2/$user/$domain/$profilename.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 update include files for a particular user, execute the following command:

• /scripts/ensure_vhost_includes --user=$username

To update include files for all users, 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 wildcard 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:
   • /var/cpanel/templates/apache1/vhost.default -- to affect Apache 1 virtual hosts that do not use SSL.
   • /var/cpanel/templates/apache2/vhost.default -- to affect Apache 2 virtual hosts that do not use SSL.
   • /var/cpanel/templates/apache1/ssl_vhost.default -- to affect Apache 1 virtual hosts that use SSL.
   • /var/cpanel/templates/apache2/ssl_vhost.default -- to affect Apache 2 virtual hosts that use SSL.
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:
   • /var/cpanel/templates/apache1/vhost.default -- to affect Apache 1 virtual hosts that do not use SSL.
   • /var/cpanel/templates/apache2/vhost.default -- to affect Apache 2 virtual hosts that do not use SSL.
   • /var/cpanel/templates/apache1/ssl_vhost.default -- to affect Apache 1 virtual hosts that use SSL.
   • /var/cpanel/templates/apache2/ssl_vhost.default -- to affect Apache 2 virtual hosts that use SSL.
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:
   1. 1. • custom_vhost_template_ap1 for Apache 1
         • custom_vhost_template_ap2 for Apache 2
      • The $key value should be:
   • 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

Custom Templates for New Accounts, Subdomains, and Addon Domains

When a new account, subdomain, or addon domain is created, the templates located in /var/cpanel/templates/ are not used. However, you are still able to define a template for these events. To do so, you will need to edit the files located at:

• 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

Unlike the templates located in /var/cpanel/templates/, you will not need to copy and rename the template files. Simply edit the contents of the file to match how you would like new accounts, subdomains, and addon domains to be configured.

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.