Development Guides Home >> Guide to WHM Plugins

Guide to WHM Plugins - Plugin Files

Introduction

WHM includes specific requirements for plugin interfaces and other files.

Note:

Files

WHM plugins can include many different types of files. Your installation script should use the following locations to store your plugins' files:

Interface files

Your installation script should store interface files in a subdirectory of the /usr/local/cpanel/whostmgr/docroot/templates/ directory.

  • In cPanel & WHM version 66 and later, WHM plugin interfaces that perform ACL checks must include an additional module. For more information, read our Guide to WHM Plugins - ACL Reference Chart documentation.
  • In cPanel & WHM version 64, we implemented a wrapper system that plugin developers can access in their custom interfaces.

  • cPanel plugin requirements and WHM plugin requirements are not identical. For information about cPanel plugins, read our Guide to cPanel Plugins documentation.
  • For resources that help you match custom interfaces to the WHM interface, read our experimental User Interface Style Guide.

Icons

Your installation script should store icons in the /usr/local/cpanel/whostmgr/docroot/addon_plugins/ directory.

  • When you register your plugin, the AppConfig configuration file automatically adds your plugin's icon to the WHM interface.
  • We strongly recommend that you use 48x48 pixel .png images with a transparent background.
  • Image files must use a supported image file type (.gif, .jpeg, or .png).

CGI scripts

Your installation script should store CGI scripts in the /usr/local/cpanel/whostmgr/docroot/cgi/ directory.

  • For plugins with a single CGI file, use the addon_name.cgi naming convention for CGI scripts, where name represents your plugin's name.
  • For plugins with multiple CGI files, store them in a subdirectory within the /usr/local/cpanel/whostmgr/docroot/cgi directory.

WHMADDON and ACLS comments

CGI scripts can include two special comment lines that provide additional plugin information to WHM.

  • The WHMADDON comment creates an entry for the plugin in WHM's left navigation menu. This comment line must use the following format: #WHMADDON:plugin_name:Display Name:icon.png In this example, plugin_name represents the plugin's name, Display Name represents the plugin's display name, and icon.png represents the plugin's icon file.
  • The ACLS comment determines the Access Control Lists (ACLs) that the plugin requires in order to display in WHM's left navigation menu. This comment line must use the following format: #ACLS:all In this example, all represents a list of ACLs that the plugin requires. For a complete list of ACLs, read our Guide to WHM Plugins - ACL Reference Chart documentation.

Example

#!/usr/local/cpanel/3rdparty/bin/perl
#WHMADDON:example:Example WHM Plugin:example.png
#ACLS:all

use strict;
 package cgi::examplePlugin;
 use warnings;
 use Cpanel::Template                  ();

 # Make the script into a modulino, to facilitate testing.
 run() unless caller();

 sub run {
     print "Content-type: text/html\r\n\r\n";
     Cpanel::Template::process_template(
         'whostmgr',
         {
             'template_file' => 'whm_example_plugin/index.tmpl',
             'print'         => 1,
         }
     );
     exit;
 }

Other files

Your installation script should store other plugin files in a subdirectory of the /usr/local/cpanel/3rdparty/ directory.

When files exist in this directory, WHM users with the correct permissions can access them via a URL. For example, WHM users on the example.com server could access the /usr/local/cpanel/3rdparty/myplugin/index.html file via the following URL:

https://example.com:2087/cpsess##########/myplugin/index.html