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:
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
Step 4: - Obtain the App from github.com.
Obtain the App from github.com and save it to the /root directory and uncompress it.
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.
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
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.
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)
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:
Code:
# 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 - <b>rblcheck</b>
# 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.jpgStep 3: - Create the directory for the plugin.
Create the rblcheck directory under /usr/local/cpanel/whostmgr/docroot/cgi
Code:
mkdir -p /usr/local/cpanel/whostmgr/docroot/cgi/rblcheckObtain the App from github.com and save it to the /root directory and uncompress it.
Code:
curl https://raw.githubusercontent.com/cPanelPeter/rblcheck/master/whmplugin/whmrblcheck.tar.gz > /root/whmrblcheck.tar.gz
tar xvzfp /root/whmrblcheck.tar.gzCopy the rblcheck.jpg file to the /usr/local/cpanel/whostmgr/docroot/addon_plugins directory.
Code:
cp -fv /root/rblcheck.jpg /usr/local/cpanel/whostmgr/docroot/addon_plugins
cp -fv /root/rblcheck.cgi /usr/local/cpanel/whostmgr/docroot/cgi/rblcheckDocumentation on how to register your plugin is here: Guide to WHM Plugins - AppConfig Registration - Software Development Kit - cPanel Documentation
Code:
/usr/local/cpanel/bin/register_appconfig ~/rblcheck.confThe 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.
Code:
#!/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 ([email protected]) {
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)
Code:
#!/bin/sh
# SCRIPT: install.sh
# PURPOSE: Install the infection_scanner plugin into cPanel
# AUTHOR: Peter Elsner <[email protected]>
#
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!"