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:

  1. Navigate to WHM's Theme Manager interface ( WHM >> Home >> Themes >> Theme Manager ).
  2. Click Manage Themes under Login .
  3. Click Clone next to the theme that you wish to duplicate.
  4. 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 cpanel-logo.svg
whm-logo_white.svg The WHM subheader for non-white backgrounds. 55 208 whm-logo_white.svg
images/webmail-logo.svg The Webmail subheader. 50 306 webmail-logo.svg
  • 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 cpanel-logo-tiny.svg
images/cpanel-logo-tiny-white.svg The cPanel logo at the bottom of login pages, for non-white backgrounds. 25 25 cpanel-logo-tiny-white.svg
images/icon-password.svg The icon that appears in the password text box. 20 20 icon-password.svg
images/icon-username.svg The icon that appears in the username text box. 20 20 icon-username.svg
images/locale-map.svg The image that displays for the list of available locales. 220 455 locale-map.svg
images/login-error-close.svg The icon that allows users to close any messages that the system receives. 12 12 images/cpanel-logo.svg
images/notice-error.svg The image that appears on the page whenever an error is encountered. 28 28 notice-error.svg
images/notice-info.svg The image that appears whenever the system needs to display additional information. 28 28 notice-info.svg
images/notice-success.svg The image that appears whenever the user successfully logs in or resets their password. 28 28 notice-success.svg
images/security-policy-error.svg The image that appears whenever an error occurs on a security policy page. 21 21 security-policy-error.svg
images/security-policy-success.svg The image that appears in order to indicate success on a security policy page. 21 21 security-policy-success.svg
images/warning.svg The image that appears whenever the system raises a warning. 28 28 warning.png
  • 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 whm.png

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 and resetpass.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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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:
  • cpaneld — The cPanel interface.
  • whostmgrd — The WHM interface.
  • webmaild — The Webmail interface.
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:
  • 1 — The user logged out recently.
  • 0 — The user has not logged out recently.
page_to_show string The sub-template that the login application calls after it loads the main.tmpl template:
  • access_denied — Access the templates/access_denied.tmpl template.
  • fourohfour — Access the templates/fourohfour.tmpl template.
  • login — Access the templates/login.tmpl template.
  • passthrough — Access the templates/passthrough.tmpl template.
  • referrer_denied — Access the templates/referrer_denied.tmpl template.
  • token_denied — Access the templates/token_denied.tmpl template.
reset_pass Boolean Whether to display the Reset Password link:
  • 1 — Display.
  • 0 — Do not display.

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.
  • The function returns this list of locale information in an array of hashes.
  • This function does not accept arguments.
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.
  • This function matches against the filename that you request, regardless of the application name. For example, if you use this function to search for the logo.png file, the function would also search for the logo_whostmgr.png file.
  • You must pass values through the MagicRevision() function after you pass them through this function. For example, the following code passes the filename logo.png to the get_theme_url() function, and then passes the file through the MagicRevision() function:

      • <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.
  • URLs that you pass through the MagicRevision() function contain the file's modification time in the URL path.
  • The cpsrvd daemon recognizes URL paths that contain a file modification time, and serves files as the browser cached them if no new changes have occurred.

Default template example

Click to view...

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

Click to view...

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

Click to view...

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:
  • resetpass_confirmation — Access the templates/resetpass_confirmation template.
  • resetpass_no_user — Access the templates/resetpass_no_user.tmpl template.
  • resetpass_success — Access the templates/success.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.
  • The function returns this list of locale information in an array of hashes.
  • This function does not accept arguments.
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.
  • This function matches against the filename that you request, regardless of the application name. For example, if you use this function to search for the logo.png file, the function would also search for the logo_whostmgr.png file.
  • You must pass values through the MagicRevision() function after you pass them through this function. For example, the following code passes the filename logo.png to the get_theme_url() function, and then passes the file through the MagicRevision() function:

      • <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.
  • URLs that you pass through the MagicRevision() function contain the file's modification time in the URL path.
  • The cpsrvd daemon recognizes URL paths that contain a file modification time, and serves files as the browser cached them if no new changes have occurred.

Default template example

Click to view...

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 or resetpass-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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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

Click to view...

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).

©2024 WebPros International, LLC All rights reserved.Privacy PolicyTrademarks