Creating a WHM Plugin

You can use plugins to add new functionality to WHM. Once a plugin is installed, it can be viewed in the Plugins section of your WHM interface.

Basics

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

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

Each plugin you add will need 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 including 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 resulting comment would appear within the script as:

• #WHMADDON:cPscanner:cPanel Scanner

The plugin's filename and path would need to be:

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

Access Control

Because WHM plugins are executed as root, it is extremely important to implement access control with your plugin.

The term ACL, in the context of WHM, refers to reseller access control lists. ACLs correspond to permissions granted to a reseller. When used alongside 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.

The ACL Table

To view a list of ACLs and their corresponding privileges click here. click here to hide.

Hiding the Plugin

There are 2 types of access control you can use with a WHM plugin. The first is handled by the #ACLS comment. This controls which resellers can see the plugin in the WHM interface. If you do not include the #ACLS comment, The plugin will appear to all of your resellers. The #ACLS comment should resemble the following:

• #ACLS:aclname

aclname in the example above should correspond to the reseller ACL you wish to allow to view the plugin. For example, if you wanted resellers who have the ability to add packages to see the plugin, you would create the comment like so:

• #ACLS:add-pkg

Refer to the table above for a list of available ACLs.

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

Preventing Plugin Execution

The second type of access control can be used to prevent the execution of a plugin. This is extremely important because WHM plugins are executed as root. Failing to set this access control will result in a serious security issue with the plugin.

There is not a language-agnostic way of setting a WHM ACL at this point.

Perl

If you choose to use Perl when preventing WHM plugin execution, you can use the Whostmgr::ACLS module for parsing ACL information. The checkacl() function within the module returns a true or false value, depending on whether or not the reseller attempting 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, indicating 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 using PHP, there is no predefined method for working with ACLs. However, the code block 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 == $ac ) {
					return 1;
				}
			}
		}
	}
	return 0;
}

Other Languages

There is no pre-written code available for working with other languages. However, you can determine reseller privileges by reading and parsing the data contained within the following file:

• /var/cpanel/resellers

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