How to Create a WHM Plugin

Overview

You can use plugins to add new functionality to WHM. For example, the WatchMySQL plugin allows administrators to monitor user connections to MySQL. Once a plugin is installed, it can be viewed in the Plugins section of your WHM interface.

Basics

WHM plugins are CGI scripts with special comments that control how they are displayed in WHM. WHM plugins must be located in the cgi directory:

• /usr/local/cpanel/whostmgr/docroot/cgi/

Each plugin you add needs to be prefixed with addon_ and end with .cgi. For example:

• addon_NAME.cgi

Remember: WHM plugins are always executed as the root user. It is extremely important that you implement access control.

You can control various aspects of the CGI script by when you include special comments inside of the script file. To control the display name in the WHM interface, you will need to use the #WHMADDON comment. This comment is a colon-separated (:) line, formatted in the following way:

• #WHMADDON:appname:Display Name

For example, if you created an application called cPscanner:

The comment appears within the script as:

• #WHMADDON:cPscanner:cPanel Scanner

The plugin's filename and path must be:

/usr/local/cpanel/whostmgr/docroot/cgi/addon_cPscanner.cgi

How to create a WHM plugin icon

To set an icon, add the filename of your icon at the end of your WHMADDON comment. The resulting comment will appear within the script as:

• #WHMADDON:cPscanner:cPanel Scanner:filename.gif

The plugin's filename and path must be:

• /usr/local/cpanel/whostmgr/docroot/addon_plugins/filename.gif

Finally, change the permissions so that cpsrvd may read it.

For example: -rw-r--r-- 1 root root 77670 Aug 17 2012 filename.gif

Note: The WHM icons should be 25x25 GIF images or JPEG images. The images should have white backgrounds, and cannot be transparent.

Access Control

Because WHM plugins are executed as root, it is extremely important to implement access control with your plugin. Without appropriate access control, an unsafe plugin can damage a system.

The term ACL, in the context of WHM, refers to reseller Access Control Lists (ACLs). ACLs correspond to permissions that are granted to a reseller. In regards to a WHM plugin, ACLs can specify which resellers can see and use the plugin, based on the privileges assigned to that reseller. You can define ACLs on the Edit Privileges screen of WHM's Reseller Center interface. These strings are also stored in /var/cpanel/resellers.

Note: For more information about ACLs, see our list of ACLs.

How to hide the plugin

Root can use the #ACLS comment to control which resellers can see the WHM plugin. If you do not include the #ACLS comment, the plugin appears to all of your resellers. The #ACLS comment should resemble the following:

• #ACLS:username

username in the example above should correspond to the reseller username you wish to allow to view the plugin. You can also include an ACL as a username. For example, a comment that allows resellers who have the ability to add packages to see the plugin would resemble:

• #ACLS:add-pkg

Note: For more information about ACLs, see our list of ACLs.

Important: If you only use this access control, the plugin can still be executed by a user who visits the URL directly.

How to prevent plugin execution

Access control can be used to prevent the execution of a plugin. This is extremely important because WHM plugins are executed as root. Failure to set this access control results in a serious security issue with the plugin.

There is not a language-agnostic way to a WHM ACL at this time.

Perl

If you choose to use Perl to prevent WHM plugin execution, you can use the Whostmgr::ACLS module to parse ACL information. The checkacl() function within the module returns a true or false value, which depends on whether or not the reseller who attempts to access the plugin has the appropriate credentials. For example:

use lib '/usr/local/cpanel/';
use Whostmgr::ACLS ();
Whostmgr::ACLS::init_acls();
if (!Whostmgr::ACLS::checkacl( 'all' ) ) {
        print 'Access Denied.';
        exit;
}

In the example above, the script checks for the all ACL, which indicates that the reseller has root access. In this example, if a reseller without all privileges attempted to access the plugin, he or she would be denied.

PHP

When you use PHP, there is no predefined method for working with ACLs. However, the code below will function just as the example in the Perl section.

function checkacl ($acl) {
	$user = $_ENV['REMOTE_USER'];

	if ($user == "root") {
		return 1;
	}

	$reseller = file_get_contents("/var/cpanel/resellers");
	foreach ( split( "\n", $reseller ) as $line ) {
		if ( preg_match( "/^$user:/", $line) ) {
			$line = preg_replace( "/^$user:/", "", $line);
			foreach ( split(",", $line )  as $perm ) {
				if ( $perm == "all" || $perm == $acl ) {
					return 1;
				}
			}
		}
	}
	return 0;
}

Other languages

There is no pre-written code available that will work with other languages. However, you can determine reseller privileges if you read and parse the data contained within the following file:

• /var/cpanel/resellers

How to Check the Username

The username that is currently authenticated against WHM is available via the REMOTE_USER environment variable. This can be used to implement per-user access control. You can access this information with the function below:

• your_access_control_function( $ENV{REMOTE_USER} )