Custom Templates
Last modified: December 1, 2022
Overview
A custom template file modifies how cPanel & WHM builds the Apache configuration’s virtualhost entries.
-
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
To create a custom template file for all virtual hosts, perform the following steps:
- 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
- Apache 2.4 virtual host with SSL —
- Rename the copied file to one of the following filenames:
vhost.local
— Use this filename if you copied thevhost.default
file.ssl_vhost.local
— Use this filename if you copied thessl_vhost.default
file.ea4_main.local
— Use this filename if you copied theea4_main.default
file.
- 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
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.
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:
- 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
- Apache 2.4 virtual host with SSL —
- Rename the copied file to one of the following filenames:
vhost.local
— Use this filename if you copied thevhost.default
file.ssl_vhost.local
— Use this filename if you copied thessl_vhost.default
file.ea4_main.local
— Use this filename if you copied theea4_main.default
file.
- Edit the new file with your changes to your virtual host configuration.
- 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.
- Use the following script to add the information to the data structure, where
username
represents the user name anddomainname
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