Page tree
Skip to end of metadata
Go to start of metadata

Overview 

A custom template file modifies how cPanel & WHM builds the Apache configuration's virtualhost entries. 

Warning:

If you misconfigure a custom template, Apache may generate an invalid httpd.conf file. This will result in a server that does not respond to HTTP requests. Be certain that you use caution when you create custom templates and create any directives that rely on specific Apache modules in the appropriate <IfModule> blocks.

Custom templates that apply to all virtual hosts

Note:

You cannot use custom templates for a parked domain.

To create a custom template file for all virtual hosts, perform the following steps:

  1. Copy one or more of the following files:
    • Apache 2.4 virtual host with SSL — /var/cpanel/templates/apache2_4/ssl_vhost.default
    • Apache 2.4 virtual host without SSL — /var/cpanel/templates/apache2_4/vhost.default
    • EasyApache 4 main template — /var/cpanel/templates/apache2_4/ea4_main.default
  2. Rename the copied file to one of the following filenames:
    • vhost.local — Use this filename if you copied the vhost.default file.
    • ssl_vhost.local — Use this filename if you copied the ssl_vhost.default file.
    • ea4_mail.local — Use this filename if you copied the ea4_main.default file. 
  3. Edit the *.local files to make the desired changes to your virtual host configuration.

Warnings:

  • This method affects all of your virtual hosts. cPanel & WHM will use the .local files instead of the original .default files.
  • You will lose all custom configurations when you upgrade to cPanel & WHM version 68. We strongly recommend that you back up any .local template customizations before you upgrade.

Custom templates that apply to an individual virtual host

The /var/cpanel/userdata/ directory

Warning:

We strongly recommend that you use include files to modify the content of an individual virtual host. For more information about how to use include files, read our Modify Apache Virtual Hosts with Include Files documentation.

cPanel & WHM uses the data in the subdirectories of the /var/cpanel/userdata/ directory to build the virtual hosts for your Apache configuration. These files use the YAML format. For more information about the YAML format, read The Official YAML Website

EasyApache 4 loads these files into the vhost template variable. For more information about the Template Toolkit, visit the Template Toolkit website.

Warning:

Do not manually edit these YAML files.

How to create a custom template that will apply to a single virtual host

You can use a custom template to modify the data in the /var/cpanel/userdata/ directory for an individual domain.

To create a custom template that affects how cPanel & WHM builds entries for a single virtual host, perform the following steps:

  1. Copy one or more of the following files:
    • Apache 2.4 virtual host with SSL — /var/cpanel/templates/apache2_4/ssl_vhost.default
    • Apache 2.4 virtual host without SSL — /var/cpanel/templates/apache2_4/vhost.default
    • EasyApache 4 main template — /var/cpanel/templates/apache2_4/ea4_main.default
  2. Rename the copied file to one of the following filenames:
    • vhost.local — Use this filename if you copied the vhost.default file.
    • ssl_vhost.local — Use this filename if you copied the ssl_vhost.default file.
    • ea4_mail.local — Use this filename if you copied the ea4_main.default file. 
  3. Edit the new file with your changes to your virtual host configuration.
  4. Move the new file to any other directory.

    Note:

    You will specify the template file's location when you run the script in step 5.

  5. Use the following script to add the information to the data structure, where username represents the user name and domainname represents the domain's name:

     

    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 custom_vhost_template_ap2 path/to/template