Perl Module Installation

Last modified: July 13, 2022

Overview

Perl modules allow you to extend cPanel & WHM’s functionality. For example, you can use Perl modules to add functions to cPanel & WHM.

Warning:

Before you install a module, make certain that it functions in a cPanel-provided Perl environment. For more information, read our Guide to Perl in cPanel & WHM documentation.

Note:

In the examples throughout this document, Module::Name is the name of the custom Perl module that you wish to install.

Install modules to the system Perl binary

To install a Perl module to the system’s Perl environment (/usr/bin/perl), use one of the following methods:

Install from the WHM interface

To install a module to the system Perl environment, use WHM’s Install a Perl Module interface (WHM » Home » Software » Install a Perl Module).

Note:

To use this interface, you must have compiler access. For more information, read our Compiler Access documentation.

Install from the command line via script

The /usr/local/cpanel/scripts/perlinstaller script requires that you include, as an argument, the name of the module that you wish to install. Make certain that you use the CPAN convention for the module name.

Note:

When you run this script without arguments, you will enter an interactive shell that lets you fully manage CPAN module installations.
When you run this script, you can include the --force flag. This flag causes the system to ignore errors and warnings, and can result in the installation of broken modules.
The CPAN utility on your server is the cPanel & WHM version of the App::cpanminus application. For more information, read the cpanminus documentation.

Example

/usr/local/cpanel/scripts/perlinstaller Module::Name

Install via the cpan command

The cpan command calls the CPAN utility. You must include, as an argument, the name of the module that you wish to install. Make certain that you use the CPAN convention for the module name.

Example

cpan Module::Name

Install modules to the cPanel & WHM Perl installation

To install a Perl module to the cPanel-included Perl installation (/usr/local/cpanel/3rdparty/bin/perl), use the following method:

The cpanm script

When you the /usr/local/cpanel/bin/cpanm script, you must include, as an argument, the name of the module that you wish to install.

Make certain that you use the CPAN convention for the module name.
Include the -i argument to indicate that you wish to install the module.
You can use this script to install a Perl module with minimal interaction.

Example

/usr/local/cpanel/bin/cpanm -i Module::Name

Confirm that your module installed correctly

Perl binary

To confirm that the modules installed to the system’s Perl binary function, run the following command. In this example, Module::Name is the name of the module:

/usr/bin/perl -MModule::Name -e 'print $Module::Name::VERSION . "\n"'

The system will return the installed module’s version number.

cPanel-included Perl installation

To confirm that the modules installed to the cPanel-included Perl installation function, run the following command. In this example, Module::Name is the name of the module:

/usr/local/cpanel/3rdparty/bin/perl -MModule::Name -e 'print $Module::Name::VERSION . "\n"'

The system will return the installed module’s version number.

Manage installed modules

The /usr/local/cpanel/scripts/perlmods script allows you to use the Perl::Mod module in order to manage the modules on your system. Use the following flags to troubleshoot module installations:

-l — Use the Perl::Mod module to list all of the installed modules for your system.
-s — Use the Perl::Mod module to search for an installed module.
-u — Use the Perl::Mod module to uninstall modules.

Troubleshoot module problems

Error logs

Error logs provide additional insight into problems on your server. cPanel & WHM writes STDERR (standard error) output to the /usr/local/cpanel/logs/error_log file whenever it encounters an error.

Use the strace command

Some errors require the strace (system trace) command to view additional output that does not write to the /usr/local/cpanel/logs/error_log file. To view this output, run the following command during the system error:

strace -s 4096 -fvt -o /root/strace.issue.at.hand -p `cat /var/run/cpsrvd.pid`

@INC errors

When you encounter @INC array errors, you will see a message that resembles the following example in the /usr/local/cpanel/logs/error_log file:

1
2


Can't locate DB_File.pm in @INC (@INC contains: /usr/local/cpanel /usr/local/lib/perl5/5.8.8/x86_64-linux /usr/local/lib/perl5/5.8.8 /usr/local/lib/perl5/site_perl/5.8.8/x86_64-linux
/usr/local/lib/perl5/site_perl/5.8.8 /usr/local/lib/perl5/site_perl .) at /scripts/spamassassin_dbm_cleaner line 14.

In this example, the system could not locate the Perl module. The error message also lists the locations in which the system searched for the module.

If you encounter this error, perform the following actions to resolve the problem:

Place a copy of the module in one of the locations that the error message lists.
Create a symlink from one of the listed locations to the location of the module.
Resolve an issue in the module itself during build time.

To view the current @INC array paths, run the perl -V command as the root user. The system will return output that resembles the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Built under linux
Compiled at Jan 28 2011 08:49:59
@INC:
  /usr/lib/perl5/site_perl/5.8.8/i386-linux-thread-multi
  /usr/lib/perl5/site_perl/5.8.8
  /usr/lib/perl5/site_perl
  /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi
  /usr/lib/perl5/vendor_perl/5.8.8
  /usr/lib/perl5/vendor_perl
  /usr/lib/perl5/5.8.8/i386-linux-thread-multi
  /usr/lib/perl5/5.8.8