Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include Page
_Version
_Version

Toc no bullet

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

Before you install a module, make certain that it will function correctly with the cPanel-provided Perl environments. For more information, read our Guide to Perl in cPanel & WHM documentation.


Note
titleNote:

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

Custom modules that ship with cPanel & WHM

Include Page
LIB:_CustomModules
LIB:_CustomModules

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:

MethodDescriptionExample command
Install from the WHM interface.

To install a module to the system Perl environment from the WHM interface, use the Module Installers interface (Home >> Software >> Module Installers).

Note
titleNote:

To use this interface, you must have compiler access.


 
Install from the command line with the /scripts/perlinstaller script.

The /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
titleNotes:

When you use 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 cPanel's version of the App::cpanminus application. For more information, read the cpanminus documentation.
  • Run this command without arguments to enter an interactive shell that you can use to fully manage CPAN module installations.



Code Block
languagebash
/scripts/perlinstaller Module::Name


Install from the command line with 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.


Code Block
cpan Module::Name


 

Install modules to the cPanel Perl installation

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

MethodDescriptionExample Command
The /usr/local/cpanel/3rdparty/perl/514/bin/cpan tool.

When you use this tool, 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 option to indicate that you wish to install the module.


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


Confirm that your module installed correctly

To confirm that the modules you installed to the system's Perl binary are functional, run the following command, where Module::Name is the name of the module:

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

To confirm that the modules you installed to the cPanel-included Perl installation are functional, run the following command, where Module::Name is the name of the module:

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

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

Manage installed modules

The /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:

  • -lUse the Perl::Mod module to list all of the installed modules for your system.
  • -sUse the Perl::Mod module to search for an installed module.
  • -uUse 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 strace

Some errors require that you use the strace (system trace) command to view additional output that does not write to the /usr/local/cpanel/logs/error_log file.

To view additional error information, run the following command while the system experiences the problem:

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

Code Block
languagetext
linenumberstrue
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 location 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:

Code Block
languagetext
linenumberstrue
perl -V

 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