Child pages
  • Tutorial - Create a WHM Plugin
Skip to end of metadata
Go to start of metadata

Introduction


WHM plugins add custom system administrator-level functionality to cPanel & WHM servers.

Important:

Use this tutorial with cPanel & WHM version 66 and later only.

Create a WHM plugin


Create your plugin's backend code.

Use your preferred programming language to write your plugin's backend code.

Important:

If your plugin's functionality requires specific permissions, you must add appropriate Access Control List (ACL) checks.

 


 

Create your plugin's interfaces.

To allow WHM users to access your plugin within the WHM interface, provide one or more interfaces.

 


 

Add an installation script.

You can include an installation script with your WHM plugins.We do not require a specific programming language or other specific details for this script. However, we strongly recommend that you create one, and that it performs at least the following actions:

  • Check for the appropriate installation directories and create any that do not already exist.
  • Register the plugin with the AppConfig system.
  • Copy the plugin files, templates, and icons into the correct locations.

Important:

AppConfig registration does not automatically search for or run installation scripts. Whenever system administrators install plugins, they must decompress the files and run the installation script manually.

For more information or to view an example BASH installation script, read our Guide to WHM Plugins - Installation Scripts documentation.

 


 

Add an optional uninstallation script.

When you provide an uninstallation script, make certain that it removes the plugin's icon, files, and directories, and then unregisters the plugin with AppConfig.

  • Do not delete the plugin's AppConfig configuration file before you unregister the plugin.

  • For more information and an example uninstallation script, read our Guide to WHM Plugins - Uninstall Plugins documentation.

 


 

Add an icon.

Your installation script should store your plugin's icon in the /usr/local/cpanel/whostmgr/docroot/addon_plugins/ directory.

  • We strongly recommend that you use 48x48 .png images with a transparent background.
  • Image files must use a supported image file type (.gif.jpeg, or .png).

 


 

Add other assets.

Add any other files or assets to your plugin files. Many WHM plugins include the following additional files:

  • A LICENSE file provides license information for a plugin.
  • A README file can provide installation instructions, copyright and license information, and links to documentation and other external resources.

 


 

Register your plugin with AppConfig.

To use WHM plugins, you must register them with the AppConfig system. AppConfig registration adds plugin icons to the WHM interface automatically. It also configures the plugin's ACL requirements, upgrade script information, and other plugin variables.

 


 

Test your plugin.

Run your plugin's installation script and ensure that your plugin functions correctly.

For help to troubleshoot common WHM plugin development issues, read our Guide to Testing Custom Code documentation.