Development Guides Home >> Quickstart Development Guide
Tutorial - Create Custom-Branded Login Pages
Introduction
This tutorial creates server-wide custom login pages for the cPanel, WHM, or Webmail interfaces. For more information about cPanel & WHM's login theme, read our Guide to cPanel Interface Customization - The Login Theme documentation.
-
Throughout this document,
themename
represents the name of your custom theme. - You cannot modify login pages for individual cPanel accounts.
- Resellers cannot create their own custom login pages.
Duplicate the existing login theme
To duplicate the existing login theme, perform the following steps:
- Navigate to WHM's Theme Manager interface ( WHM >> Home >> Themes >> Theme Manager ).
- Click Manage Themes under Login .
- Click Clone next to the theme that you wish to duplicate.
- Enter a name for the duplicate theme in the available text box and click Submit .
WHM saves your new theme in the /usr/local/cpanel/base/unprotected/themename/
directory, where themename
represents the name that you entered.
Modify the login page subheader logos
Replace any or all of the subheader images in the /usr/local/cpanel/base/unprotected/themename/images/
directory.
- Subheader images appear at the top of the login pages for cPanel, WHM, and Webmail.
- Make certain that your replacement images use the correct dimensions in order to allow for the appropriate amount of padding within the login subheader containers.
The default cPanel & WHM login theme contains the following subheader logo images:
Image location | Description | Height | Width | Image |
---|---|---|---|---|
images/cpanel-logo.svg |
The cPanel subheader. | 50 |
233 |
|
whm-logo_white.svg |
The WHM subheader for non-white backgrounds. | 55 |
208 |
|
images/webmail-logo.svg |
The Webmail subheader. | 50 |
306 |
- These images appear in the default login theme for the most recent version of cPanel & WHM. If you use an older version of cPanel & WHM, check the images in your default login theme to ensure that you use the correct image dimensions.
- For more information about login theme images, read our Guide to cPanel Interface Customization - Login Images documentation.
Modify other login page images
Replace any or all of the other login theme images in the /usr/local/cpanel/base/unprotected/themename/images/
directory.
The default cPanel & WHM login theme contains the following additional images:
Image location | Description | Height | Width | Image |
---|---|---|---|---|
images/cpanel-logo-tiny.svg |
The cPanel logo at the bottom of the login pages. | 25 |
25 |
|
images/cpanel-logo-tiny-white.svg |
The cPanel logo at the bottom of login pages, for non-white backgrounds. | 25 |
25 |
|
images/icon-password.svg |
The icon that appears in the password text box. | 20 |
20 |
|
images/icon-username.svg |
The icon that appears in the username text box. | 20 |
20 |
|
images/locale-map.svg |
The image that displays for the list of available locales. | 220 |
455 |
|
images/login-error-close.svg |
The icon that allows users to close any messages that the system receives. | 12 |
12 |
|
images/notice-error.svg |
The image that appears on the page whenever an error is encountered. | 28 |
28 |
|
images/notice-info.svg |
The image that appears whenever the system needs to display additional information. | 28 |
28 |
|
images/notice-success.svg |
The image that appears whenever the user successfully logs in or resets their password. | 28 |
28 |
|
images/security-policy-error.svg |
The image that appears whenever an error occurs on a security policy page. | 21 |
21 |
|
images/security-policy-success.svg |
The image that appears in order to indicate success on a security policy page. | 21 |
21 |
|
images/warning.svg |
The image that appears whenever the system raises a warning. | 28 |
28 |
- These images appear in the default login theme for the most recent version of cPanel & WHM. If you use an older version of cPanel & WHM, check the images in your default login theme to ensure that you use the correct image dimensions.
- For more information about login theme images, read our Guide to cPanel Interface Customization - Login Images documentation.
The following files are not a part of the default cPanel & WHM login theme and require further customization of the reference file:
Image location | Description | Height | Width | Image |
---|---|---|---|---|
images/whm.svg |
The WHM subheader for use with lighter page backgrounds. | 55 |
208 |
Modify the login page templates
Make the desired changes to your custom theme's other login page templates. Login themes include the main templates that all users view when they log in, error page templates, and templates for the Reset Password feature.
- These template files control what users see when they log in, encounter login errors, or reset their passwords.
-
Advanced users can modify the
main.tmpl
andresetpass.tmpl
files to change how the system processes user input.
For more information about login page templates, read our Guide to cPanel Interface Customization - Login Templates documentation.
The default cPanel & WHM login theme contains the following template files:
errorwrapper.tmpl
The system accesses this wrapper template whenever the user encounters an error.
Location
templates/_error_wrapper.tmpl
Template variables
This template does not use template variables.
Default template example
access_denied.tmpl
The system accesses this template whenever the server responds with an Access Denied error. This error occurs whenever a user attempts to log in with an invalid username or password.
Location
templates/access_denied.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
disabled.tmpl
The system accesses this template whenever the visitor attempts to access a disabled account.
Location
templates/disabled.tmpl
Template variables
This template inherits the template variables from its parent template.
Default template example
error502.tmpl
The system accesses this template whenever the server responds with a 502 (server) error.
Location
templates/error502.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
error503.tmpl
The system accesses this template whenever the server responds with a HTTP status 503. The system displays HTTP status 503 when the requested service is unavailable.
Location
templates/error503.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
page_message |
string | The optional message provides more details about why the service is unavailable. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
externalauthheader.tmpl
The system accesses this template in order to add the header for the External Authentication login section.
Location
templates/external_auth_header.tmpl
Template variables
This template inherits the template variables from its parent template.
Default template example
external_auth.tmpl
The system accesses this template in order to add the External Authentication login section.
Location
templates/external_auth.tmpl
Template variables
This template inherits the template variables from its parent template.
Default template example
fourohfour.tmpl
The system accesses this template whenever the server responds with a HTTP 404 (page not found) error.
Location
templates/fourohfour.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
generic_error.tmpl
The system accesses this template whenever the server responds with a generic error.
Location
templates/generic_error.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
invitation_failure.tmpl
The system accesses this template whenever it cannot properly process a new user invitation.
Location
templates/invitation_failure.tmpl
Template variables
This template inherits the template variables from its parent template.
Default template example
invitationsetpassword.tmpl
The system accesses this template whenever an invited user needs to set a new password.
Location
templates/invitation_set_password.tmpl
Template variables
This template inherits the template variables from its parent template.
Default template example
invitation_success.tmpl
The system accesses this template whenever an invited user successfully accepts the invitation and sets their new password.
Location
templates/invitation_success.tmpl
Template variables
This template inherits the template variables from its parent template.
Default template example
login.tmpl
This template determines the appearance of the first login page that users see when they attempt to log in to cPanel, WHM, or Webmail.
Location
templates/login.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
msg_code |
string | The key that corresponds to the login_messages value. This message displays on the loading page, after the user authenticates. |
Default template example
main.tmpl
This template contains the conditions to perform the following actions:
- Correctly set the title of the login page in the web browser.
- Set the page's favicon.
- Load the login theme CSS files.
- Include the login page's copyright notice.
Advanced users can update this template to modify the way in which the system processes user input.
Location
main.tmpl
Template variables
This template does not use template variables.
Advanced use
The login
application loads the main.tmpl
template to determine how the system processes user input.
Application parameters
The login
application uses the following parameters, which are only available in templates that use the main.tmpl
parent template:
Variable | Type | Description |
---|---|---|
app_name |
string | The cPanel & WHM service that the user attempted to log in to:
|
http_status_code |
string | The HTTP status code that the server used to respond to the request. |
login_messages |
hash | A hash of messages that the browser can display dynamically via Javascript. |
logout |
Boolean | Whether the user logged out recently:
|
page_to_show |
string | The sub-template that the login application calls after it loads the main.tmpl template:
|
reset_pass |
Boolean | Whether to display the Reset Password link:
|
Global objects
The Template::Toolkit
module does not allow scoping. For more information, read our Guide to Template Toolkit in cPanel & WHM documentation.
When you modify the way in which this template processes input, you can also use the following global objects:
Global object | Type | Description |
---|---|---|
display_locales() |
function | This function retrieves a list of the locales that are available on the server.
|
get_theme_url() |
function | This function searches the /usr/local/cpanel/base/unprotected/ directory and its subdirectories for a specified file and returns its location. Use this function to ensure that the system displays the correct image for the server's current login theme.
<img src="[% MagicRevision( get_theme_url('logo.png') ) %]" alt="logo"> |
locale |
Cpanel::Locale hash object instance |
This global object contains the current user's locale. For more information, read our How cPanel & WHM Determines a Browser's Locale and Guide to Locales documentation. |
MagicRevision() |
function | This function provides a caching system. Use this function to improve load times for users and decrease system I/O.
|
Default template example
passthrough.tmpl
This template generates the page that displays when a user authenticates successfully after a Token Denied error.
Location
templates/passthrough.tmpl
Template variables
Variable | Type | Description |
---|---|---|
cp_security_token |
string | The security token to use in the URL. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
redirect_uri |
string | The URL to which the system will redirect the user |
Default template example
referrer_denied.tmpl
The system accesses this template whenever the server returns a Referrer Denied error. The system returns this error if the server rejects the user's reference link.
Location
templates/referrer_denied.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
resetpass.tmpl
This template generates the page that instructs users to reset their passwords.
Advanced users can update this template to modify the way in which the system processes user input.
Location
resetpass.tmpl
Template variables
This template does not use template variables.
Advanced use
The resetpass
application loads the resetpass.tmpl
template to determine how the system processes user input when users reset their passwords.
The resetpass
application uses the resetpass-email.tmpl
and resetpass-email-html.tmpl
templates when it sends a confirmation email to the user.
Application parameters
The resetpass
application uses the following parameters, which are only available in templates that use the resetpass.tmpl
parent template:
Parameter | Type | Description |
---|---|---|
notice_class |
string | The HTML class for the notice_text notice. |
notice_text |
string | The notice to display, if one exists. |
page_to_show |
string | The sub-template that the resetpass application calls after it loads the resetpass.tmpl template:
|
Global objects
The Template::Toolkit
module does not allow scoping. For more information, read our Guide to Template Toolkit in cPanel & WHM documentation.
When you modify the way in which this template processes input, you can also use the following global objects:
Global object | Type | Description |
---|---|---|
display_locales() |
function | This function retrieves a list of the locales that are available on the server.
|
get_theme_url() |
function | This function searches the /usr/local/cpanel/base/unprotected/ directory and its subdirectories for a specified file and returns its location. Use this function to ensure that the system displays the correct image for the server's current login theme.
<img src="[% MagicRevision( get_theme_url('logo.png') ) %]" alt="logo"> |
locale |
Cpanel::Locale hash object instance |
This global object contains the current user's locale. For more information, read our How cPanel & WHM Determines a Browser's Locale and Guide to Locales documentation. |
MagicRevision() |
function | This function provides a caching system. Use this function to improve load times for users and decrease system I/O.
|
Default template example
resetpass_confirmation.tmpl
This template generates the page that displays when a user clicks Reset Password and has entered a username in the Username text box.
-
When the system accesses this template, it also sends a confirmation code to the user via email. This email message uses either the
resetpass-email.tmpl
orresetpass-email-html.tmpl
template, based on whether the user's email client can display HTML. - The user must enter the confirmation code that they receive in order to reset the password.
Location
templates/resetpass_confirmation.tmpl
Template variables
This template does not use template variables.
Default template example
resetpass_failure.tmpl
This template generates the page that displays when the system cannot reset the user's password. The system displays an error message.
Location
templates/resetpass_failure.tmpl
Template variables
This template does not use template variables.
Default template example
resetpassnouser.tmpl
This template generates the page that displays when a user clicks Reset Password without a username in the Username text box.
Location
templates/resetpass_no_user.tmpl
Template variables
This template does not use template variables.
Default template example
resetpass_puzzle.tmpl
This template generates the page that displays when a user requests a password reset and must enter a Two-Factor Authentication code.
Location
templates/resetpass_puzzle.tmpl
Template variables
This template does not use template variables.
Default template example
resetpasssetpassword.tmpl
This template generates the confirmation page that displays when a user requests a password reset.
Location
templates/resetpass_set_password.tmpl
Template variables
This template does not use template variables.
Default template example
resetpass_success.tmpl
This template generates the confirmation page that displays when a user resets a password successfully.
Location
templates/resetpass_success.tmpl
Template variables
This template does not use template variables.
Default template example
resetpass_suspended.tmpl
This template generates the page that displays when a user attempts to reset the password on a suspended account.
Location
templates/resetpass_suspended.tmpl
Template variables
This template does not use template variables.
Default template example
securitypolicy_footer.html.tmpl
This template generates the Security Policy page's footer. Users set the security questions for their accounts through this page.
Location
templates/securitypolicy_footer.html.tmpl
Template variables
This template does not use template variables.
Default template example
securitypolicy_header.html.tmpl
This template generates the Security Policy page's header. Users set the security questions for their accounts through this page.
Location
templates/securitypolicy_header.html.tmpl
Template variables
This template does not use template variables.
Default template example
token_denied.tmpl
The system accesses this template whenever the server responds with a Token Denied error.
Location
templates/token_denied.tmpl
Template variables
Variable | Type | Description |
---|---|---|
dest_uri |
string | The URL to load after a user authenticates. This URL does not contain the security token. |
error_msg |
string | The error message to display. |
form_ref |
hash | A hash of the form variables to pass with the request. The system sends this hash to the location that the redirect_uri variable specifies. |
parameterized_form |
hash | A hash of form variables that the user provided as a URL query string. |
theme |
string | The theme to load. |
user |
string | The username to authenticate. |
Default template example
Modify theme CSS files
Make the desired changes to the style_v2.css
and style_v2_optimized.css
files.
Subheader logo customizations may require changes to the subheader logo style attributes. Modify these attributes under the login-sub-header
div
tag in thestyle_v2.css
file.
Update your server's locales
If you added new text to your theme's login templates, add those new phrases to your server's locales.
- To do this, use WHM's Edit a Locale interface ( WHM >> Home >> Locale >> Edit a Locale ).
- For more information about cPanel & WHM's localization system, read our Guide to Locales documentation.
Use your new custom login theme.
To cause all of your server's accounts to use the new custom login theme, select the theme's name from the Default login theme menu in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings).