Custom Apache Include for Single Virtual Host


Well-Known Member
Mar 29, 2005
I"m a bit confused about the proper location for custom apache includes for single virtual hosts.

The first part of Changes Contained within a VirtualHost Directive says

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 2 without SSL — /usr/local/apache/conf/userdata/std/2/$user/$domain/$includename.conf
But under the heading "Custom templates that will apply to a single virtual host when rebuilding an existing Apache configuration" it says ...

4. Move the *.local file to another directory.

Note: Any separate directory will do, as you will specify the location of the file.

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
Can someone please help me understand this?


Well-Known Member
Dec 1, 2010
cPanel Access Level
Root Administrator
Those are two entirely unique concepts that you've listed.

  1. Includes
  2. Templates

Which one you want to use depends on what type of change(s) you want to enact.

If you only want to add simple static directives to a user's <VirtualHost>, then you want to use the "Include" method on that page. That involves simply slapping down a file at:

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
and then following the remainder steps for verifying/ensuring the includes are recognized and included to httpd.conf

On the other hand, the "Custom Templates" option is for:
  • If you want to modify the directives that cPanel & WHM already puts in place for a <VirtualHost>
  • If the directives that you're adding would benefit from the cPanel template system variables to auto-populate certain information about the user account.

However, unless you absolutely need the benefits of the custom template method, I would otherwise strongly recommend the include method. Why? With the template method you're taking a static snapshot of the vhost template cPanel has deployed and then modifying it. When we make changes to that template design in the future, any places you've copy/paste/modified the template would then be based off of the old/stale template and wouldn't have any updates we made. This could cause those particular <VirtualHost>s to be unable to use new features or, potentially, break entirely. You'd have to then re-copy a fresh version of the updated template and re-implement the customizations again. "Includes" are much less invasive and much less likely to cause such problems down the road.