Perl Troubleshooting Guide

cPanel & WHM uses Perl heavily. We have worked to provide a self-sustaining platform, but to perform some customizations, system administrators will need to intervene manually. This is why we have added a number of utilities to cPanel & WHM, in addition to an extensive logging system designed to explain the issues and lead administrators to the source of complications. We hope to provide information that allows you to streamline troubleshooting issues directly related to Perl that may arise from within cPanel & WHM.

We have developed cPanel & WHM for use with modern versions of Perl. The core parts of our product use Perl 5.6.2 internally. However, many scripts and modules require Perl version 5.8 or later.

What happens when I install Perl?

Before you can install cPanel & WHM, Perl must be present on the server. If Perl is not present during installation, the cPanel & WHM installer will fail with an error message that instructs you to download and install Perl. If Perl is installed, but older than version 5.8.8, our Perl installer will install version 5.8.8 from source in /usr/local.

Similarly, when you install cPanel & WHM in a virtual environment, such as Xen, Perl 5.8.8 is built from source and installed to /usr/local. This is done regardless of the version of Perl installed by the operating system.

cPanel provides some system tools to help you work with Perl modules:

• /scripts/perlmods -l — List installed modules
• /scripts/perlmods -s — Perl::Mod to search for installed modules
• /scripts/perlmods -u — Perl::Mod to uninstall modules
• /scripts/checkperlmodules --force — Force modules to be reinstalled
• /scripts/checkperlmodules --full — Ensure additional Perl modules are also installed
• /scripts/perlinstaller --force — Perl::Mod to force installation of the module specified

The locations of binaries and modules on your server depend upon how Perl was installed:

• When Perl is installed via yum or up2date, you can find the Perl binary at /usr/bin/perl. Modules installed by yum or up2date are installed to /usr/lib/perl5 for 32-bit systems or /usr/lib64/perl5 for 64-bit systems.
• When Perl is installed by the Perl installer, the binary will be at /usr/local/bin/perl, while the modules and libraries will be in /usr/local/lib or /usr/local/lib64, depending on your server’s architecture.

It is therefore possible to install multiple versions of Perl on a cPanel & WHM system. This is especially true in a virtualized environment. To determine your Perl binaries’ version, you can use the -v parameter:

• /usr/bin/perl -v
• /usr/local/bin/perl -v

What special provisions have been made for Perl on a cPanel & WHM system?

cPanel adds an exclude in /etc/yum.conf that prevents system updates from updating your server’s Perl installations. This will help to ensure that none of your modules are broken by an update. This will preserve compatibility with CPAN modules installed via 
/scripts/checkperlmodules and other utilities.

Under certain conditions, having a Perl installation in /usr and /usr/local can cause issues. The problem seems primarily to be with CPAN modules. One method of resolving these issues is to make either /usr/bin/perl or /usr/local/bin/perl a symlink, depending upon which version of Perl you desire to keep. After creating the symlink, you may need to run /scripts/checkperlmodules several times to successfully install your CPAN modules for that version of Perl.

For example, if you wish to retain the /usr/local/bin/perl install, you could use the following commands:

mv /usr/bin/perl /usr/bin/perl.from.os
ln -s /usr/local/bin/perl /usr/bin/perl
/scripts/checkperlmodules

/scripts/checkperlmodules is executed during the cPanel update process, whenever 
/scripts/upcp is run. The /scripts/checkpermodules script contains a number of checks and tests to verify that a particular group of modules is installed. Whenever a check fails, you may need to install the missing dependency manually. In such instances, cPanel & WHM will generate an email and send it to the system administrator.

An example of an error email concerning Curses::UI

cPanel & WHM requires the Curses::UI module. The system will not function correctly until it is installed and functional. The following is the result of an automatic installation attempt:

   Test Run
   ==============
   Can't load '/usr/lib/perl5/site_perl/5.8.8/x86_64-linux/auto/Curses/Curses.so' for module Curses: /usr/lib/perl5/site_perl/5.8.8/x86_64-linux/auto/Curses/Curses.so: undefined symbol: COLORS at /usr/lib/perl5/5.8.8/x86_64-linux/DynaLoader.pm line 230.
   at /usr/lib/perl5/site_perl/5.8.8/Curses/UI/Common.pm line 20
   Compilation failed in require at /usr/lib/perl5/site_perl/5.8.8/Curses/UI/Common.pm line 20.
   BEGIN failed--compilation aborted at /usr/lib/perl5/site_perl/5.8.8/Curses/UI/Common.pm line 20.
   Compilation failed in require at (eval 1) line 3.
   ...propagated at /usr/lib/perl5/5.8.8/base.pm line 85.
   BEGIN failed--compilation aborted at /usr/lib/perl5/site_perl/5.8.8/Curses/UI.pm line 2.
   Compilation failed in require at - line 1.
   BEGIN failed--compilation aborted at - line 1.

Another good example would be a bootstrap error. A bootstrap error occurs when the installed version of Perl does not meet the requirements for a required module or library.

Template::Stash::XS object version 2.19 does not match bootstrap parameter 2.22 at /usr/local/lib/perl5/5.8.8/x86_64-linux/DynaLoader.pm line 247.

What should I do when Perl modules fail to install?

The --force flag

When /scripts/checkperlmodules fails to install a Perl module after repeated attempts, there are a number of other steps and tools that you can use to fix this issue.

You should be able to fix most issues using the following 5 methods. However, if your problems persist, you will need to take further steps to isolate the cause of issues.

Using /scripts/checkperlmodules --force

The first tool we should mention is /scripts/checkperlmodules’ --force flag.

Warning: Please exercise extreme caution when using the --force flag because it causes errors and warnings to be ignored. This can result in broken modules being installed.

Using /scripts/perlinstaller

The second tool we should discuss is the /scripts/perlinstaller. This script accepts a single argument: the name of the module you wish to install. You must enter the module name using the CPAN convention. If you wished to install the Curses::UI modules, you would need to enter the following:

/scripts/perlinstaller Curses::UI

Like /scripts/checkperlmodules, /scripts/perlinstaller can accept the --force parameter. As with /scripts/checkperlmodules, using the --force flag causes errors and warnings to be ignored, and can result in broken modules being installed.

Installing modules manually

The third method for installing a Perl module on a cPanel & WHM server is the manual method. Configuration and build data used by /scripts/checkperlmodules is stored in /home/.cpan. When modules fail to install, they are left in /home/.cpan/build. Changing to one of those directories can allow you to install the module manually. You can read more information about the manual installation of Perl modules at http://theoryx5.uwinnipeg.ca/CPAN/perl/pod/perlmodinstall.html.

Downloading modules manually

The fourth method we should consider is manually downloading and installing the problematic module. This may be the best method when the problem is due to a faulty mirror. Using http://search.cpan.org, you can obtain the URL for the desired module. Once you have obtained the URL, the installation may be as simple as:

Download
Uncompress
make
make install

Using this method, we can install the DBD::mysql module manually:

wget http://search.cpan.org/CPAN/authors/id/C/CA/CAPTTOFU/DBD-mysql-4.018.tar.gz
tar zfvxp DBD-mysql-4.018.tar.gz
cd DBD-mysql-4.018
perl Makefile.PL
make install clean

Installing the module via CPAN

Finally, you may wish to use CPAN itself to perform the installation. This is as simple as calling the CPAN utility with a module name as the argument:

cpan Curses::UI

When you execute this command without an argument, you will enter an interactive shell that you can use to fully manage CPAN module installations.

More About Troubleshooting

Remember, cPanel & WHM attempts to direct STDERR output to /usr/local/cpanel/logs/error_log anytime something happens. However, you will need to use strace (system trace) to catch some output that was not directed to the /usr/local/cpanel/logs/error_log file. We typically use the following strace command while stimulating the system to create the issue at hand, gaining further insight into the complication:

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

CONTROL + C should break you from the trace as soon as you have reproduced the data.

You may also encounter problems with Perl’s @INC array. In this case, you will be provided with the direct @INC error in /usr/local/cpanel/logs/error_log:

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.

As you can see from the error above, the Perl module was not located. Perl even shows you where it searched for the module. From this point forward, you will need to use a symlink, or you may need to resolve an issue with the module itself during build time. You may even need to place a copy of the module in an @INC-mentioned path to fix the situation.

Remember, Perl modules required by various cPanel & WHM binaries (e.g. /usr/local/cpanel/cpsrvd) will not be in the normal system paths. Rather, the binaries search /usr/local/cpanel/perl for these. Very few of the scripts and utilities will manage the modules in that location. Usually, the /usr/local/cpanel/perl directory is populated during a cPanel update (/scripts/upcp). The /scripts/checkperlmodules script does not manage /usr/local/cpanel/perl. You should not copy modules and files from elsewhere on the system into /usr/local/cpanel/perl. If the utilities we provide are not resolving the issue, you will need to open support ticket needs with us, since you have encountered a bug in cPanel & WHM, or its deployment.

Running perl -V as the root user will show you the current @INC paths. This will allow you to see if there is a problem with any configured paths, and where the installation may be looking for the module.

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

Managing /usr/local/cpanel/perl

The following utilities will manage some of the modules in the /usr/local/cpanel/perl directory:

• /usr/local/cpanel/bin/nativedf-install
• /usr/local/cpanel/bin/nativessl-install

Should you ever fail to fix any of these issues, please feel free to ask one of our technical analysts to take a closer look.