The Community Forums

Interact with an entire community of cPanel & WHM users!
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

How to create a Plugin (WHM & cPanel)

Discussion in 'cPanel Developers' started by cPanelPeter, Dec 24, 2015.

  1. cPanelPeter

    cPanelPeter Technical Analyst III
    Staff Member

    Joined:
    Sep 23, 2013
    Messages:
    569
    Likes Received:
    15
    Trophy Points:
    18
    cPanel Access Level:
    Root Administrator
    Twitter:
    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:

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

    Code:
    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.

    Code:
    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.

    Code:
    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

    Code:
    /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.

    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 ($@) {
                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 <peter.elsner@cpanel.net>
    #
    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!"
    
     
  2. speckados

    speckados Well-Known Member

    Joined:
    May 21, 2003
    Messages:
    291
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    Acequias :: Granada :: España
    cPanel Access Level:
    DataCenter Provider
    Twitter:
    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
     
  3. cPanelPeter

    cPanelPeter Technical Analyst III
    Staff Member

    Joined:
    Sep 23, 2013
    Messages:
    569
    Likes Received:
    15
    Trophy Points:
    18
    cPanel Access Level:
    Root Administrator
    Twitter:
    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.
     
  4. chiencongvn

    chiencongvn Registered

    Joined:
    Nov 3, 2016
    Messages:
    1
    Likes Received:
    1
    Trophy Points:
    1
    Location:
    Viet Nam
    cPanel Access Level:
    Website Owner
    Thanks for your tutorial ! it is a comprehensive guide for beginners like me
     
    cPanelMichael likes this.
Loading...

Share This Page