Internal Perl Modules

Overview

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

• cPanel & WHM version 11.34 and earlier servers contain 2 Perl environments.
• cPanel & WHM version 11.36 servers contain 3 Perl environments. More Perl environments may be added in future releases.

Perl Instances

The system's Perl binary

The system's Perl is located in the /usr/bin/perl directory. By default, this instance of Perl is a standard environment that runs Perl 5.8.8 on RHEL/CentOS 3, 4, and 5; and Perl 5.10 on RHEL/CentOS 6.

This particular instance of Perl is used by CGI scripts and operating system maintenance scripts.

cPanel & WHM version 11.34 and earlier

For cPanel & WHM systems that run version 11.34 or earlier, the system's Perl binary is also used by cPanel 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.

cPanel & WHM adds modules to this environment and excludes this instance in YUM updates.

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

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

cPanel & WHM version 11.36 and newer

As of cPanel & WHM version 11.36, cPanel no longer updates Perl modules or installs new Perl modules to the /usr/lib or the /usr/local/lib directories. If you have scripts that need to work with cPanel code, we recommend that you make the following changes to the top of your Perl scripts. This modification allows the scripts to work with all cPanel installs:

#!/bin/sh                                                                                                                                                                                               
 eval 'if [ -x /usr/local/cpanel/3rdparty/bin/perl ]; then exec /usr/local/cpanel/3rdparty/bin/perl -x -- $0 ${1+"$@"}; else exec /usr/bin/perl -x $0 ${1+"$@"}; fi;'
   if 0;
#!/usr/bin/perl

Custom modules will not be installed to /usr/local/cpanel. Instead, the custom module will be installed to the system's Perl at /usr/bin/perl.

Note: The Home >> Software >> Module Installers feature is deprecated as of version 11.36.

cPanel's Perl binary application

cPanel & WHM consists largely of Perl applications compiled with Perl 5.6.2. A compiled Perl application in Linux is somewhat unusual and can cause some issues with extensibility.

This particular instance of Perl is used by cPanel itself and any custom modules that are loaded from inside a cPanel binary or integrated with cPanel and WHM.

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

We plan to compile a future version of cPanel & WHM with a more recent version of Perl (5.14 or later). Any third-party module built for earlier versions of cPanel & WHM which contains compiled code (For example: XS) will not load in the future. For more information about this change, read the Planned Changes section of this document.

cPanel-included Perl installation

As of cPanel & WHM version 11.36, we distribute a 3rd version of Perl located at /usr/local/cpanel/3rdparty/perl/514/bin/perl.

In addition, we have changed the Perl scripts that we distribute with cPanel & WHM to use this version of perl. These scripts include the cPanel system maintenance scripts (in /usr/local/cpanel/scripts) and in CGI scripts in cPanel & WHM.

This change allows you to manage your system's Perl binary independently of cPanel & WHM. Ultimately, you can no longer expect all of the same modules to be installed into @INC for the system's Perl binary located at /usr/bin/perl in cPanel & WHM 11.36.

This also means that systems that have been provisioned after this change can manage the system's Perl binary via an RPM.

For more information, read Prepare Your Perl Scripts For 11.36.

How to Install Modules Into cPanel's Perl Binary

Because 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 you use use the buildperl utility, you must 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

How to install a Perl module

The tools provided by cPanel & WHM to install CPAN modules, such as scripts/perlinstaller, have always installed the modules to the /usr/lib directory or to the /usr/local/cpanel directory. These paths are the search paths that the system perl binary uses at /usr/bin/perl, and they will not change.

To install a module:

1. Download the module from cpan.
2. Extract the source.
3. Access the source directory via the command line.
4. Run 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 finishes without an error.
• Only issue the make install command if the make test command finishes without an error.

How to install other modules

To install other Perl modules, use the command /usr/local/cpanel/3rdparty/perl/514/bin/cpan -i followed by the name of the module to be installed.

For example:

/usr/local/cpanel/3rdparty/perl/514/bin/cpan -i Module::Name

#!/usr/bin/perl

To use the instance of Perl shipped with cPanel, you must add #!/usr/local/cpanel/3rdparty/bin/perl at the beginning of your scripts.

The shebang line, #!/usr/local/cpanel/3rdparty/bin/perl , is a symlink to the latest Perl Shipped by cPanel. The default search order is:

/usr/local/cpanel
/usr/local/cpanel/3rdparty/perl/514/lib/perl5/cpanel_lib
/usr/local/cpanel/3rdparty/perl/514/lib/perl5/5.14.3
/opt/cpanel/perl5/514/site_lib

To insert your path at the top of this list, you must add the following block into your code.

BEGIN { unshift @INC, '/path/to/my/lib'; }

How to Modify Applications and Scripts to Use cPanel-Provided Perl

Applications and scripts need to be modified to use cPanel-provided Perl. If an application needs to support both newer and older versions of cPanel & WHM, you must change the first line of the script to the following to ensure multi-version compatibility:

#!/bin/sh
eval 'if [ -x /usr/bin/local/cpanel/3rdparty/bin/perl ]; then exec /usr/local/cpanel/3party/bin/local -x --$0
${1+”$@”}; else exex /usr/bin/perl -x $0 ${1+”$@”}; fi;'
if 0;
#!/usr/bin/perl/

How to Modifiy Perl Magic User Loader

cPanel no longer modifies /usr/bin/perl. Instead, the Perl Module Magic User Loader is located at /usr/bin/perlml . To continue to use the Perl Magic User Loader, the system administrator must change all of the CGI scripts from #!/usr/bin/perl to #! /usr/bin/perlml .

WHM's Install a Perl Module screen includes a deprecation message for the Perl Module Magic User Loader. Users can still disable the Magic Loader, but they will not be able to re-enable it.

Included PERL Modules

To get more detailed information on the modules Perl shipped by cPanel, run the following command:

/usr/local/cpanel/3rdparty/bin/perl -V

For more information on the included Perl modules, read metacpan.org.

How to test your installation

At this point, your module should be installed. To test whether the module is installed and available to cPanel Perl binary, run the following via the command line:

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

If the utility responds with the version of the module that you installed, then the installation was successful.

If you encounter errors, the problem may be one or more of the following:

• The module was written for a different version of the operating system, or for another operating system entirely.
• The module depends on other modules that are not present.
• The test may not be written correctly.
• The module may contain errors.

You can find more information about Perl modules in the CPAN archive.

Planned Changes

We plan to compile future cPanel binaries against a more modern version of Perl. As a result, any third-party module built for earlier versions of cPanel & WHM which contain compiled code (For example: XS) will no longer function. You will need to prepare your application for this change.

To assist with this change, we will provide free development licenses that allow you to run an automated test system for your application. This automated test 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 that you run an automated test within the /usr/local/cpanel/scripts/postupcp script as a hook that validates your application's functionality externally. We also strongly recommend that this hook notify you of any failures so that you can address them yourself or file a support ticket with our technical support staff.