Problem
Your objective is to get cPanel services (webmail, cPanel, and WHM) to be accessible via HTTPS for domains that have a dedicated IP address and a valid certificate. The goal is for these selected domains to work via a URL like so…
https://webmail.domain.tld/
…instead of a URL with a port number appended like this one…
https://webmail.domain.tld:2096/
…which has the undesired effect of using the server-wide certificate instead of the one installed for this domain.
Note that there is some proxy magic built into cPanel that is designed to solve this problem, but it does not provide the level of granularity that is often needed. Specifically, it does not allow you to apply this functionality to just those domains with valid certificates.
This document will describe how to override cPanel’s settings on a per-domain basis so that users will be taken to an HTTPS URL bearing a valid certificate for the domain. All domains that have not been explicitly targeted will remain unaffected.
Technical details
Certificates installed for users’ domains are handled by apache and are installed in…
WHM >> Install a Certificate and Setup the Domain
However, cPanel services are handled by the daemon “cpsrvd”, not apache. Instead of using the certificates installed via the above utility, cpsrvd uses a server-wide certificate that is installed in…
WHM >> Manage Service SSL Certificates >> cPanel/WHM/Webmail Service
You might think that you could simply use the following URLs to access these services:
https://cpanel.domain.tld/
https://webmail.domain.tld/
https://whm.domain.tld/
However, the above URLs do not automatically work because no mechanism exists for globally connecting SSL sites to cPanel services. Instead, these services must be accessed via their respective port numbers that cpsrvd listens on like so:
https://domain.tld:2083/ or https://hostname:2083/
https://domain.tld:2096/ or https://hostname:2096/
https://domain.tld:2087/ or https://hostname:2087/
(actually, any domain that resolves to the server will work so long as the correct port is appended to the URL)
Unfortunately, when accessing sites with the domain name and port number, you will likely encounter certificate warnings because the server-wide certificate is not usually valid for a user’s domain. cPanel offers two less than ideal ways to resolve this:
Unsatisfactory way #1
Configure cPanel to forward all cPanel services to the URL that is on the server-wide certificate (this is the default behavior). Assuming that the server-wide certificate is valid for the hostname, users will be redirected to URLs that look like the following:
https://hostname:2083/ (cpanel)
https://hostname:2096/ (webmail)
https://hostname:2087/ (whm)
This prevents certificate warnings if the server-wide certificate is valid, but it causes the URL that appears in the address bar to change to something unexpected.
Unsatisfactory way #2
Purchase a server-wide certificate that is good for multiple domains and add each required “subdomain.domain.tld” to the server-wide certificate. Then, configure cPanel to redirect to the “origin domain name” so that the final URLs look like this:
https://cpanel.domain.tld:2083/
https://webmail.domain.tld:2096/
https://whm.domain.tld:2087/
Note that in this case the certificate will be valid, but the port number will still be appended. This is also problematic because it puts the burden of maintenance and cost on the administrator instead of the end user.
Solution
A workaround can be implemented using a combination of custom redirects and mod_proxy.
Note that cPanel already provides this mechanism, which works consistently for non-secure URLs. As described at the beginning of this document, this mechanism is inconsistent when using secure URLs.
The “cPanel way” is to enable “proxy subdomains” in WHM >> Tweak Settings, which will connect port-less URLs to their corresponding cPanel services like so (the URL on the left is retained in the browser’s address bar):
http://cpanel.domain.tld/ =PROXY=> http://127.0.0.1:2082/
http://webmail.domain.tld/ =PROXY=> http://127.0.0.1:2095/
http://whm.domain.tld/ =PROXY=> http://127.0.0.1:2086/
https://cpanel.domain.tld/ =PROXY=> http://127.0.0.1:2083/
https://webmail.domain.tld/ =PROXY=> http://127.0.0.1:2096/
https://whm.domain.tld/ =PROXY=> http://127.0.0.1:2087/
As previously explained, this feature does not work reliably for HTTPS URLs. The solution to this problem has two parts. The first part is to use mod_proxy to provide the necessary connection between apache and cpsrvd. The second part is to override cPanel’s default behavior of redirecting to https://service.domain.tld:port/ and instead redirect to the regular HTTPS URL https://service.domain.tld/.
Prerequisites
Mod_proxy
If not installed, you can enable mod_proxy via EasyApache
Dedicated IP address
Each domain for which you implement this workaround must have a dedicated IP address. This is not just an arbitrary policy but a technical limitation based on how SSL sites work. You can get it to work on the shared IP address, but in this case it will only work for one domain!
Certificate
There are three different types of certificates that you can install, arranged in order of preference:
Multiple-domain certificate
A certificate that is valid for multiple domains is ideal so that it will be valid for both the main domain and the subdomains. This prevents you from having to dedicate an IP address for the main domain and another one for all its subdomains.
Wildcard subdomain certificate
A wildcard subdomain certificate would validate each of the cPanel service subdomains, but would not cover the main domain. cPanel does not technically support wildcard certificates, but these instructions show how you can get them to work:
Single-domain certificate
A certificate that is valid for only one of the subdomains can be installed to get this working for just that subdomain and its corresponding service.
Steps
Step 1: Configure apache to respond to the cPanel service subdomains
This step is necessary to be able to implement custom redirection on a per-domain basis, as described in later steps.
First, you should enable “Proxy subdomain override” in WHM >> Tweak Settings. Otherwise you will receive an error when attempting to create the subdomains in the cPanel interface.
Next, you will need to ensure that each subdomain does not already have a corresponding DNS record. Simply delete any of the following records if they currently exist in the domain’s DNS zone:
cpanel 14400 IN A IP_ADDRESS
webdisk 14400 IN A IP_ADDRESS
webmail 14400 IN A IP_ADDRESS
whm 14400 IN A IP_ADDRESS
Lastly, you will need to use the cPanel interface to add the cPanel service subdomains. The best way to accomplish this would be to park these subdomains to the main domain using cPanel >> Parked Domains. However, cPanel disallows adding these as parked domains this even if “Proxy subdomain override” is enabled in Tweak Settings. You will instead have to add them using the cPanel >> Subdomains utility.
Step 2: Ensure that a certificate is installed for the domain
For a certificate to work for the both the main domain and all of its subdomains, it must be a multiple-domain certificate (see the section Prerequisites->Certificates above for more information about the types of certificates that you might install).
Note that, since only one certificate can be installed per IP address, all URLs that resolve to a particular IP address will be presented with whichever certificate is installed for that IP address irrespective of the host name requested by the website visitor. This is because apache is ignorant of the host name that the visitor seeks until after a secure connection has been established. Before accepting the certificate, the only things apache knows about are the IP address and port number being requested.
Step 3: Override cPanel’s default redirection
cPanel’s default redirects are controlled by CGI scripts. The corresponding lines appear near the top of httpd.conf and look like the following:
ScriptAliasMatch ^/?cpanel/?$ /usr/local/cpanel/cgi-sys/redirect.cgi
ScriptAliasMatch ^/?webmail/?$ /usr/local/cpanel/cgi-sys/wredirect.cgi
ScriptAliasMatch ^/?whm/?$ /usr/local/cpanel/cgi-sys/whmredirect.cgi
The configuration changes described below use mod_rewrite’s “RewriteRule” directive to redirect website visitors to the port-less HTTPS URL before the above ScriptAliasMatch directives come into play. This ensures that apache can present the correct certificate to the visitor.
The first step is to create an include file which contains the apache directives that will override cPanel’s default redirection:
vi /usr/local/apache/conf/includes/redirect_to_ssl_subdomain.conf
The contents of this file should be as follows:
RewriteEngine on
# Redirect /service to service.domain.tld
RewriteRule ^/cpanel$ https://cpanel.%{HTTP_HOST}/ [R=301,L]
RewriteRule ^/webmail$ https://webmail.%{HTTP_HOST}/ [R=301,L]
RewriteRule ^/whm$ https://whm.%{HTTP_HOST}/ [R=301,L]
# Redirect non-ssl service subdomains to ssl url
RewriteCond %{HTTP_HOST} ^cpanel.*
RewriteRule ^.*$ https://%{HTTP_HOST}/ [R=301,L]
RewriteCond %{HTTP_HOST} ^webmail.*
RewriteRule ^.*$ https://%{HTTP_HOST}/ [R=301,L]
RewriteCond %{HTTP_HOST} ^whm.*
RewriteRule ^.*$ https://%{HTTP_HOST}/ [R=301,L]
Next, include this file into the VirtualHosts of the corresponding user. Create the following directory and file, replacing $user with the actual username:
mkdir -p /usr/local/apache/conf/userdata/std/2/$user/
vi /usr/local/apache/conf/userdata/std/2/$user/redirection.conf
The contents of this file should be as follows:
Include /usr/local/apache/conf/includes/redirect_to_ssl_subdomain.conf
Note that this technique of modifying a site’s VirtualHost directive is described in fuller detail in cPanel’s online documentation
Step 4: Connect the HTTPS site to the cPanel service
This step enables a reverse proxy to connect the HTTPS site served by apache to the cPanel service served by cpsrvd.
First, create the following include file containing the necessary directives:
vi /usr/local/apache/conf/includes/proxy_cpanel_services.conf
The contents of this file should be as follows:
RewriteEngine on
<IfModule core.c>
SSLProxyEngine On
</IfModule>
RewriteCond %{HTTP_HOST} ^cpanel\.
RewriteRule ^/(.*) https://127.0.0.1:2083/$1 [P]
RewriteCond %{HTTP_HOST} ^webmail\.
RewriteRule ^/(.*) https://127.0.0.1:2096/$1 [P]
RewriteCond %{HTTP_HOST} ^whm\.
RewriteRule ^/(.*) https://127.0.0.1:2087/$1 [P]
RewriteCond %{HTTP_HOST} ^webdisk\.
RewriteRule ^/(.*) https://127.0.0.1:2078/$1 [P]
Then, create the following directory and file to include the proxy directives into the SSL VirtualHost:
mkdir -p /usr/local/apache/conf/userdata/ssl/2/dar
vi /usr/local/apache/conf/userdata/ssl/2/dar/proxy.conf
The contents of this file should be as follows:
Include /usr/local/apache/conf/includes/proxy_cpanel_services.conf
Step 5: Rebuild apache configuration
Run the following command to rebuild httpd.conf. This causes the custom VirtualHost overrides that were created in the previous step to be included at the right places with httpd.conf:
/scripts/rebuildhttpdconf
Step 6: Restart apache
For your changes to be applied, it is necessary to restart apache, which can be done with the following command:
/scripts/restartsrv_httpd
Your users will now be able to access all cPanel services via the corresponding subdomain and have each of them verified by the domain’s certificate. Also, the non-SSL URLs will redirect to the SSL URLs like so (this is something that the default cPanel configuration does not do)…
http://webmail.domain.tld/ => https://webmail.domain.tld/
http://cpanel.domain.tld/ => https://cpanel.domain.tld/
http://whm.domain.tld/ => https://whm.domain.tld/
…and the http://domain.tld/service shortcuts will likewise redirect to the SSL URL like so:
http://domain.tld/webmail => https://webmail.domain.tld/
http://domain.tld/cpanel => https://cpanel.domain.tld/
http://domain.tld/whm => https://whm.domain.tld/
Important Note
The redirects configured in these instructions are permanent 301 redirects. This will cause the final destination to be cached by your browser. If you make any changes to the redirection while testing, be very sure to delete your browser’s cache every time. Otherwise, the redirection that you observe happening may be due to your browser’s cache instead of from the apache configuration.
Global Settings
For those domains that are not on dedicated IPs and do not have their own SSL certificate, I recommend configuring cPanel to redirect their services to the server-wide certificate that is configured in WHM >> Manage Service SSL Certificates. This is accomplished by setting the following configuration options in Tweak Settings:
Proxy subdomains – On
Proxy subdomain creation – On
Require SSL – On
Always redirect to SSL – On
SSL redirect destination – SSL Certificate Name