1. cPanel & WHM Documentation
  2. EasyApache4
  3. Apache
  4. Custom Templates
apache ea4

Custom Templates

Last modified: December 1, 2022

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.

  • If you create a custom template, you must manually edit it to include any necessary patches or changes after an Apache update. EasyApache will not override the server’s .local files or make changes to them. We recommend that you create a new custom template with your desired customizations after you perform the Apache update.

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_main.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.
    Warning:

    • This method affects all of your virtual hosts. cPanel & WHM will use the .local files instead of the original .default files.

    • Custom templates with local overrides cause the system to permanently disable the Force HTTPS Redirects option in cPanel’s Domains interface (cPanel » Home » Domains » Domains).

    • 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 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_main.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: 
    1
2
3

    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

Additional Documentation