Distributing Your Addons

If you wish for your addon scripts to be able to be installed through WebHost Manager, you will need to be able to distribute them to your customers. To do this, you will need to set up a cPanel Sync Server. Click here to learn how to create a cPanel Sync System to provide your addons for customers to install.

If you choose not to set up a cPanel Sync Server, each addon script will need to be installed manually on each cPanel server.

Creating a vendor name

If you have one or more cPAddons you wish to make available for installation via cPanel you should set your self up as a "Vendor". Once you have a vendor setup — for example, "TMBG_Inc" — you can create as many addons as you like under the TMBG_Inc::Category::Name name space using the directions in Creating a New cPAddon Script. The first step is to pick a short descriptive Vendor name that identifies the individual or organization behind him or her. It must be all numbers, letters, and underscores.

To create a Vendor name, use a custom name when creating your addon script. For example: package Vendor::Category::Name; or John::CMS::Johns_Content_System. For more information on creating an addon script, see Basic Sample Module.

Distributing your software

Administrators will be able to add you as a vendor to use in WHM by entering your "cPAddon Vendor Info URL" at WHM > cPanel > Install cPAddons > Add/Remove Vendors > Vendor's Information URL, and clicking Update Vendors.

Tip: Advertise your cPanel cPAddon Vendor URL on your Downloads page so that cPanel Administrators can easily install your products.

Click here to learn how to create a cPanel Sync Server to provide your addons for customers to install.

The URL you give out to use in WHM as your "cPAddon Vendor Info URL" should be the URL of this script:

#!/usr/bin/perl


use strict;
use warnings;


use CGI qw(header param);


print header('text/plain');


my $data = param('cphost') ? 'your.cpsync.host.here'
         : param('cphuri') ? '/cpaddons/path/on/cphost/here'
         : param('palmd5') ? 'MD5_Sum_of_your_/cPAddonsMd5/Vendor.pm_here'
         :                   'Your_Vendor_Name_Here'; # must be ^\w+$
print $data;

You will need to change the 4 pieces of data to reflect your hostname, path of the addon, md5 sum of your addon package, and your vendor name.

In that example above, the URL of the base cPAddons directory would be: http://your.cpsync.host.here/cpaddons/path/on/cphost/here/

The URL will need to point to a server using cPanel Sync, where all files for your vendorship and cPAddons will be located.

Those files would be:

• cPAddonsAvailable/Vendor.pm

package cPAddonsAvailable::Vendor;
our %list = (
    'Vendor::Category::Name' => {
        'VERSION' => '0.0.1',    # $Vendor::Category::Name::VERSION
        'version' =>
          '1.0-beta',    # script's version, same as $meta_info->{'version'}
    },

    # repeat for each cPAddon you want to distribute
);
1;

• cPAddonsMD5/Vendor.pm (update the md5 sum of this file in "cPAddon Vendor Info Url" when you edit it).

package cPAddonsMD5::Vendor;
our %cpaddons = (
    'Vendor::Support::Mars_Rover' => {
        'md5' => '024994ae44c700902ced23c777cf25d2',    # md5 of .pm file
        'desc' => 'This script is a Perl/MySQL based Mars Rover Support system',
    },

    # repeat for each cPAddon you want to distribute
);
1;

• Vendor/*/* — These are the actual cPAddons you create:
  • Vendor/Category/Foo/*
  • Vendor/Category/Foo.pm

Installing addons manually

If you choose not to use a cPanel Sync Server for your cPAddons, they will need to be installed manually on each server on which the cPAddon will be used.

To install your cPAddon on the server:

Add your cPAddon files to /usr/local/cpanel/cpaddons/Vendor/Category/ This includes your cPAddon.pm and your cPAddon directory.

Add your available and md5 modules to:

• /usr/local/cpanel/cpaddons/cPAddonsAvailable/Vendor.pm
• /usr/local/cpanel/cpaddons/cPAddonsMD5/Vendor.pm

Note: More information about creating your Vendor.pm files is available in our Distributing Your Addons documentation.

Your cPAddons will only show up if the Vendor is in the %vend hash inside /usr/local/cpanel/cpaddons/cPAddonsConf.pm.

The key should be your vendor name. The value should be an empty hashref.

our %vend = (
  ...
  'Vendor' => {},
  ...
);

Note: If you choose this method, you will need to install your cPAddon in an existing Vendor namespace. If you install your cPAddon into the cPanel namespace, your addon will show as not trusted.

Licensing your addons

If your addon requires a commercial license, you have 3 options:

1. Handle the license requirements and entry from the installed addon only (100% independent of the cPAddon system).
2. Use the $meta_infoLicensing addons key "vendor_license" to install regardless of whether a valid license was entered (ie, your addon script will just detect an invalid license and handle as you wish).
3. Use the $meta_info key "vendor_license" to install only if the license entered was valid as determined by your license server on the fly.

The first step is to create an install_field key called vendor_license as well as a simple check for the license in install_field_hook.

After that:

To simply allow them to enter a ^\w+$ license key and put it in [% vendor_license %]:

'vendor_license' => {},

To allow them to enter a license key of any format you wish and put it in [% vendor_license %]:

'vendor_license' => {
    'bad_string_error' => 'Needs to be 32 digits', 
    #optional description of problem with the 
    #input as determined by the code ref below
    'string_is_ok' => sub {
        my($lisc_string) = @_; # 32 digits
        return 1 if length $lisc_string == 32 && $lisc_string =~ m/^\d+$/; # ^\d{32}$
        return 0;
    },
},

To allow them to enter anything they want and have a script verify it is valid or else not install/upgrade it:

'vendor_license' => {
    'use_url_as_error' => 1, 
    #optional, turns on or off using the result of the 
    #url in the same way as 'bad_string_error' above # it 
    #would be best to just return short text string
    'verify_url'      => 'http://foo.bar.baz/lisc.pl', # ?user=cpanel_user
lisc=liscense_string_from_input_here
     'url_says_its_ok' => sub {
        my ($url_result) = @_; # it is empty if url failed
        return 1 if $url_result =~ m/Vendor says Valid/;
        return 0;
    },
},

Creating your cPanel Sync Server

If you wish to distribute your addons through a cPanel Sync Server, you will need to configure the server on which your addons reside to be a cPanel Sync Server.

You can find Utilites and information for creating cpanelsync aware directories at http://search.cpan.org/perldoc?cPanel::SyncUtil.

Please read the documentation (and see the fully working sample scripts in the distribution) at that URL to learn more about using this utility to create a cPanel Sync Server.

There is a script called cpanelsync_build_cpaddons_dir in the distribution's /scripts directory that you can use to build your cpanelsync/ directory for your cPAddons. You will need to copy it to your server to a location that is not publicly accessible and execute it on your server as root. Then, follow its prompts to see what data you need to supply it so that it can build what you need.

For example: ./cpanelsync_build_cpaddons_dir -d /home/user/public_html/cpaddons/path/on/cphost/here -u user -a bz2 -v myvendor

This will make /home/user/public_html/cpaddons/path/on/cphost/here a cPanel Sync directory with all files owned by user and from the vendor 'myvendor'. The -a bz2 is required for all addons.

For more information on the script:

• Execute ./cpanelsync_build_cpaddons_dir
• Do not use any options.