How to create a Plugin (WHM & cPanel)

What you will learn from this walkthrough There are 2 types of plugins, One for the WHM interface and one for the cPanel interface. The following is a step by step guide to show you how easy it is to create a plugin within WHM. (cPanel interface follows below) After completing the steps below, you should be able to create a basic WHM plugin. Step 1: - Your WHM Plugin/App You'll have to have an idea for a Plugin already. This walkthrough will use a basic one I created called rblcheck. This is still in beta and will likely not receive many updates since it was specifically designed for this walkthrough. It will check your servers main IP address and any additional IP addresses (ipaliases) to see if any of them are on a Realtime Blackhole List (RBL). Things that must be done: 1) create your App/Plugin ( for the purposes of this walk-through, I've created: rblcheck/whmplugin at master " cPanelPeter/rblcheck " GitHub ) 2) Create a JPG (icon) file (25x25 px) 3) Install the following Perl modules from cpan.org. Net::IP, Geo::IP:PurePerl, IO::Uncompress::Gunzip, Archive::Tar, File::Copy (some of these may already be installed). (The install script after step 6 will check all these for you and install them if needed). Step 2: - Create the AppConfig Configuration File. The documentation for this is here: Guide to AppConfig - The AppConfig Configuration File - Software Development Kit - cPanel Documentation Since we are using the rblcheck.cgi program as an example, you'll want to follow these steps: In the /root directory, create a file called "rblcheck.conf" with the following contents:


# The name of the plugin
name=rblcheck

# Service that will run the plugin/app
service=whostmgr

# User to run the plugin as (root)
user=root

# URL where the plugin program will be stored/called from (relative to /usr/local/cpanel/docroot/)
url=/cgi/rblcheck

# Required ACL's
acls=email

# Display name within the WHM (Plugins section)
displayname=RBL Check - rblcheck

# URL to show in WHM (again, relative to where the plugin/app is installed)
entryurl=rblcheck/rblcheck.cgi

# Icon that will show up in WHM => Plugins section
icon=rblcheck.jpg

Note: There are additional options that can be added to this configuration file. Only the above is required. Step 3: - Create the directory for the plugin. Create the rblcheck directory under /usr/local/cpanel/whostmgr/docroot/cgi


mkdir -p /usr/local/cpanel/whostmgr/docroot/cgi/rblcheck

Step 4: - Obtain the App from github.com. Obtain the App from github.com and save it to the /root directory and uncompress it.


curl https://raw.githubusercontent.com/cPanelPeter/rblcheck/master/whmplugin/whmrblcheck.tar.gz > /root/whmrblcheck.tar.gz
tar xvzfp /root/whmrblcheck.tar.gz

Step 5: - Copy the rblcheck.jpg (Icon) image file, and the rblcheck.cgi file to their respective locations. Copy the rblcheck.jpg file to the /usr/local/cpanel/whostmgr/docroot/addon_plugins directory.


cp -fv /root/rblcheck.jpg /usr/local/cpanel/whostmgr/docroot/addon_plugins
cp -fv /root/rblcheck.cgi /usr/local/cpanel/whostmgr/docroot/cgi/rblcheck

Step 6: - Register your plugin. Documentation on how to register your plugin is here: Guide to WHM Plugins - AppConfig Registration - Software Development Kit - cPanel Documentation


/usr/local/cpanel/bin/register_appconfig ~/rblcheck.conf

Note: The steps above all have to be done via an install script, which will be distributed with your plugin. Additionally, the rblcheck.cgi program requires a Perl module to be installed (Net::IP). The install script can be written in anything you like (bash, Perl, PHP, Python, etc.). Example Install Script (WHM) Below is a basic install script (written in Perl) that will accomplish the install of the WHM RBL Check for you.


#!/usr/bin/perl
system("clear");
print "Installing the RBLCheck WHM Plugin...\n";
# Check for and install if missing any required Perl modules from CPAN.
&module_sanity_check;
use IO::Uncompress::Gunzip qw(gunzip $GunzipError);
# Create the directory for the plugin
print "Creating /usr/local/cpanel/whostmgr/docroot/cgi/rblcheck directory... ";
mkdir "/usr/local/cpanel/whostmgr/docroot/cgi/rblcheck";
print " - Done\n";
# Obtain the plugin from Github
print "Downloading whmrblcheck.tar.gz... ";
my $download = qx[ curl --silent https://raw.githubusercontent.com/cPanelPeter/rblcheck/master/whmplugin/whmrblcheck.tar.gz > "/root/whmrblcheck.tar.gz" ];
print " - Done\n";
# Uncompress whmrblcheck.tar.gz
print "Extracting whmrblcheck.tar.gz... ";
my $tar = Archive::Tar->new;
$tar->read("/root/whmrblcheck.tar.gz");
$tar->extract();
print " - Done\n";
# Copy the rblcheck.jpg (Icon) image file to /usr/local/cpanel/whostmgr/docroot/addon_plugins
print "Copying rblcheck.jpg to /usr/local/cpanel/whostmgr/docroot/addon_plugins... ";
copy("/root/rblcheck.jpg","/usr/local/cpanel/whostmgr/docroot/addon_plugins") or die "Copy failed: $!";
print " - Done\n";
# Copy the rblcheck.cgi file to /usr/local/cpanel/whostmgr/docroot/cgi/rblcheck
print "Copying rblcheck.cgi to /usr/local/cpanel/whostmgr/docroot/cgi/rblcheck... ";
copy("/root/rblcheck.cgi","/usr/local/cpanel/whostmgr/docroot/cgi/rblcheck") or die "Copy failed: $!";
print " - Done\n";
# Set execute permissions on the rblcheck.cgi script
print "Setting permissions on /usr/local/cpanel/whostmgr/docroot/cgi/rblcheck/rblcheck.cgi to 0755...";
chmod 0755, "/usr/local/cpanel/whostmgr/docroot/cgi/rblcheck/rblcheck.cgi";
print " - Done\n";
# Download the GeoLiteCity.dat file to /usr/local/share/GeoIP and gunzip it.
print "Creating directory /usr/local/share/GeoIP... ";
mkdir "/usr/local/share/GeoIP";
print " - Done\n";
print "Downloading GeoLiteCity.dat.gz... ";
my $download = qx[ curl --silent http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz > "/usr/local/share/GeoIP/GeoLiteCity.dat.gz" ];
print " - Done\n";
print "Uncompressing GeoLiteCity.dat.gz...";
my $input="/usr/local/share/GeoIP/GeoLiteCity.dat.gz";
my $output="/usr/local/share/GeoIP/GeoLiteCity.dat";
gunzip $input => $output or die "gunzip failed: $GunzipError\n";
print " - Done\n";
# Register the plugin
print "Registering plugin...";
system( "/usr/local/cpanel/bin/register_appconfig /root/rblcheck.conf" );
print "\nRBL Check WHM Plugin installed!\n";
exit;
# sub routines
sub module_sanity_check {
    @modules_to_install = qw( Net::IP Geo::IP::PurePerl IO::Uncompress::Gunzip File::Copy Archive::Tar );
    foreach $module(@modules_to_install) {
        chomp($module);
        print "Checking if $module is installed - ";
        eval("use $module;");
        if ($@) {
            print "No - Installing now... ";
            my $install = qx[ /usr/local/cpanel/bin/cpanm --force $module 2>&1 ];
            print "Done!\n";
        }
        else {
            print "Yes\n";
        }
    }
    return;
}

How To Create A cPanel Plugin Step 1: Your cPanel Plugin/App For this walkthrough, I created a very simple (quick & dirty) infection scanner. It simply uses the Unix/Linux "grep" command to search for specific strings that I've found over the years while investigating websites that were compromised. Please note that this is not a perfect malware/infection scanner and should not be heavily relied upon. It was created specifically for this walk-through. It can currently be found on github at: cPanelPeter/infection_scanner " GitHub Step 2: Create the install.json file. To create the install.json file, we go to WHM => Development => cPanel Plugin File Generator. Documentation on how to use this can be found here: cPanel Plugin File Generator - Documentation - cPanel Documentation You'll need a Unique Identifier (letters, numbers, hyphens and underscores). For the purposes of this tutorial, I used "Infection_Scanner" For the Name I used "Infection Scanner", the Group I selected "Security", for the Priority I chose "99" and for the URI, I entered: "infection_scanner/infection_scanner.live.pl". You'll also need an icon that is 48px by 48px and must be in PNG format. Browse for your icon file and add it to the page. Finally click the Add Item button and for the name (top-right) enter "infection_scanner". This will create a compressed tar.gz file in /var/cpanel/cpanel_plugin_generator directory, called infection_scanner.tar.gz. The UI will also give you a chance to download the file. The contents of the infection_scanner.tar.gz file will be an infection_scanner/ directory and within that directory will be an install.json file, a meta.json file (which only contains a timestamp and cpversion information), and your icon. The meta.json file is not required and if you wish, you can remove it from the archive, but it also does not hurt to leave it in place. The contents of the install.json file will look something like this: [{"icon":"infection_scanner.png","featuremanager":true,"name":"Infection Scanner","uri":"infection_scanner/infection_scanner.live.pl","group_id":"security","order":"99","type":"link","id":"infection_scanner"}] The compressed infection_scanner.tar.gz file should then be included with your backend code (your plugin/app) in another tar file (used for distribution). Step 3: Create an install.sh script Write an install.sh script (or use your preferred language) that will extract the tar files and move the contents into their respective locations. Your backend code should go into /usr/local/cpanel/base/frontend/paper_lantern/infection_scanner Step 4: Install the plugin Run /usr/local/cpanel/scripts/install_plugin infection_scanner.tar.gz This will install your plugin using the install.json file which will place your icon in the correct spot and rebuild the sprites. Example install script (cPanel)


#!/bin/sh
# SCRIPT: install.sh
# PURPOSE: Install the infection_scanner plugin into cPanel
# AUTHOR: Peter Elsner 
#
clear
echo "Installing infection_scanner"
# Create the directory for the plugin
mkdir -p /usr/local/cpanel/base/frontend/paper_lantern/infection_scanner
# Get the plugin files from Github
curl -s https://raw.githubusercontent.com/cPanelPeter/infection_scanner/master/is_files.tar.gz > /root/is_files.tar.gz
# Uncompress the archive
tar xzf is_files.tar.gz
# Move files to /usr/local/cpanel/base/frontend/paper_lantern/infection_scanner directory
mv /root/infection_scanner.live.pl /usr/local/cpanel/base/frontend/paper_lantern/infection_scanner
mv /root/infection_scanner.tar.gz /usr/local/cpanel/base/frontend/paper_lantern/infection_scanner
# Install the plugin (which also places the png image in the proper location)
/usr/local/cpanel/scripts/install_plugin /usr/local/cpanel/base/frontend/paper_lantern/infection_scanner/infection_scanner.tar.gz
# Move dlinfections script to /etc/cron.weekly (and run it once)
mv /root/dlinfections /etc/cron.weekly
chmod 0755 /etc/cron.weekly/dlinfections
/usr/local/bin/perl /etc/cron.weekly/dlinfections
echo "Installation is complete!"

speckados

April 30, 2016 18:56

Thanks for your tuto. It's possible made a plugin only with PHP? It's possible a simple tutorial how this for "PHP Users" ... thanks

cPanelPeter cPanel Staff

May 02, 2016 19:18

Hello, The programming language you decide to use for your app is irrelevant. Write your PHP code for your App/Plugin and use that instead. It can be written in any language you wish.

chiencongvn

November 03, 2016 07:51

Thanks for your tutorial ! it is a comprehensive guide for beginners like me

danielpmc

December 13, 2016 16:44

Hello cPanelPeter, This is exactly what i have been looking for. cPanelBenny suggested that a feature request i had recently submitted would be a good idea for a cPanel plugin. This is very well written for a first time plugin coder such as me. Thank you very much for the tutorial and your time, danielpmc

December 13, 2016 17:51

Hi Daniel, I'm glad you like it. Hope it gets your plugin off the ground.

April 30, 2017 19:14

I've updated both plugins infection scanner - for cPanel UI and RBL Check for WHM UI to work with version 64. The only change really is to add the following to the rblcheck.conf file:


# Target (frame).  In 64 and later, this defaults to _blank. Use mainFrame to open within WHM
target=mainFrame

This allows the RBL Check to stay within the main WHM frame instead of opening in a new window.

June 15, 2017 20:04

Hello, I just updated the RBL Check plugin again for version 66. A few minor changes had to be done to the code to accommodate the no frames in WHM. However the instructions of how to create a plugin and register it are still valid and remain the same.

Lucas

June 16, 2017 23:55

I've updated both plugins infection scanner - for cPanel UI and RBL Check for WHM UI to work with version 64. The only change really is to add the following to the rblcheck.conf file:
# Target (frame). In 64 and later, this defaults to _blank. Use mainFrame to open within WHM target=mainFrame
This allows the RBL Check to stay within the main WHM frame instead of opening in a new window.

Is it now target=_self as per the documentation here? Guide to WHM Plugins - AppConfig Configuration File - Software Development Kit - cPanel Documentation

cPanelMichael

June 19, 2017 16:17

Is it now target=_self as per the documentation here? Thank you.

How to create a Plugin (WHM & cPanel)

Comments

Didn't find what you were looking for?