Installing Internal Perl Modules

Introduction

A cPanel & WHM server has more than one Perl environment. This can lead to some confusion when attempting to build a plugin. You should know that:

• cPanel & WHM servers contain 2 Perl environments in versions 11.32 and lower.
• cPanel & WHM 11.34 will contain 3 Perl environments. We may add more Perl environments later.

Perl Instances

The system's Perl binary

You can find the system's Perl at /usr/bin/perl. The system's Perl is the version distributed by your operating system or compiled by cPanel for your operating system to use. By default, this instance of Perl is a standard environment running Perl 5.8.8 on RHEL/CentOS 3, 4, and 5; and Perl 5.10 on RHEL/CentOS 6. cPanel & WHM adds a few modules to this environment and will exclude this instance in YUM updates.

This particular instance of Perl is used by CGI scripts, system maintenance scripts (in /usr/local/cpanel/scripts), and in CGI scripts in cPanel & WHM. These CGI scripts in cPanel & WHM include WHM plugins that use the #!/usr/bin/cpenv perl shebang.

You can manage modules for this Perl instance with cpan command or using the Software Module Installers feature in WHM.

Note: To use the Software Module Installers feature, you must have compiler access.

cPanel's Perl binary

cPanel & WHM is largely a compiled Perl application. It is compiled with Perl 5.6.2. A compiled Perl application is somewhat unusual for Linux and can cause some issues with extensibility.

We plan to compile cPanel & WHM version 11.36 against a more recent version of Perl (5.14 or later). Any module that contains compiled code built against our current version will not load in cPanel & WHM 11.36. For more information, please see the Future Changes section of this document.

cPanel & WHM is distributed in a form that may not grant access to Perl modules required to develop your plugin; however, you can install new modules to cPanel's Perl binary.

Installing modules for cPanel's Perl Binary

As cPanel's Perl binary is a compiled version of Perl 5.6.2, the modules you wish to install must be compatible with Perl version 5.6.2.

Perl modules are handled by /usr/local/cpanel/build-tools/buildperl. This binary is a compiled Perl script that implements many of the switches required for Perl modules to be compiled against it. When using buildperl utility, you will need to specify a variety of MakeMaker options:

SITEPREFIX=/usr/local/cpanel/perl
PERL_LIB=/usr/local/cpanel/perl
PERL_ARCHLIB=/usr/local/cpanel/perl/x86_64-linux
SITELIBEXP=/usr/local/cpanel/perl
SITEARCHEXP=/usr/local/cpanel/perl/x86_64-linux
INSTALLPRIVLIB=/var/cpanel/lib/perl5
INSTALLSITELIB= /var/cpanel/lib/perl5
INSTALLARCHLIB= /var/cpanel/lib/perl5
PERL_SRC=/usr/local/cpanel/perl
INSTALLMAN3DIR=/usr/local/cpanel/3rdparty/man

Installing the Perl module

In some cases, the order of these options is important.

To install a module, download it from cpan, extract the source, access the source directory and execute the following commands:

/usr/local/cpanel/build-tools/buildperl MakeFile.PL SITEPREFIX=/usr/local/cpanel/perl PERL_LIB=/usr/local/cpanel/perl PERL_ARCHLIB=/usr/local/cpanel/perl/x86_64-linux  INSTALLPRIVLIB= /var/cpanel/lib/perl5 INSTALLSITELIB= /var/cpanel/lib/perl5 SITELIBEXP=/usr/local/cpanel/perl SITEARCHEXP=/usr/local/cpanel/perl/x86_64-linux INSTALLARCHLIB= /var/cpanel/lib/perl5 PERL_SRC=/usr/local/cpanel/perl INSTALLMAN3DIR=/usr/local/cpanel/3rdparty/man
make
make test
make install

Important:

• Only issue the make test command if the make command was successful.
• Only issue the make install command if the make test command was successful.

Testing your installation

At this point, your module should be installed. In order to test whether or not the module is installed and available to cPanel Perl binary, you can use the following command:

/usr/local/cpanel/build-tools/buildperl -e'use <MODULENAME>; print "$<MODULENAME>::VERSION\n";'

If the version of the module you installed is returned by the utility, the installation was successful.

Future Changes

We intend to change how we distribute Perl in future builds. This section contains some additional details about coming changes. You should read the following notes and consider the information before developing your plugin.

Custom modules will not be installed to /usr/local/cpanel. If you plan on developing plugins, please check back frequently for more specifications as they become available.

cPanel & WHM 11.34

We intend to change Perl scripts that we distribute with cPanel & WHM version 11.34 with a 3rd version of Perl at /usr/local/cpanel/3rdparty/perl/514/bin/perl. This will allow your system's Perl binary to be managed independently of cPanel & WHM. Ultimately, you cannot longer expect all of the same modules to be installed into @INC for the system's Perl binary at /usr/bin/perl/ in cPanel & WHM 11.34. This also means that systems provisioned after this change can manage the system's Perl binary via an RPM.

cPanel & WHM 11.36 and 11.38

We plan to begin compiling cPanel binaries against a modern version of Perl in version 11.36 or 11.38. As a result, all 3rd party modules with compiled code will no longer function. You will need to ready your application for this change. We will provide free development licenses that allow you to run an automated test system for your application. This system should run on our EDGE tier. This will allow you to see if a change to our product breaks your plugin before the change goes into a production tier.

We suggest running an automated test as a hook in /usr/local/cpanel/scripts/postupcp that validates your applications functionality externally. We also strongly recommend that this hook notify you of any failures so that you may address them yourself or file a support ticket with our technical support staff.