How to Manage Perl Modules in DirectAdmin

Perl is one of the older scripting languages that still powers a number of legacy web applications and CGI scripts. If you are running a website or script that depends on Perl, managing Perl modules correctly is essential. DirectAdmin provides a dedicated section for viewing and installing Perl modules so that your CGI scripts can access the dependencies they need without requiring SSH access for most tasks.

What Are Perl Modules?

Perl modules are reusable libraries of code that extend the capabilities of the Perl programming language. Just as PHP uses Composer packages or Python uses pip packages, Perl uses modules distributed through CPAN (the Comprehensive Perl Archive Network). When a Perl script requires functionality that isn't built into the language itself — such as sending email, connecting to a database, or parsing XML — it imports a module using the use or require keyword.

Common examples of Perl modules you might encounter include CGI, DBI (for database connections), LWP::UserAgent (for HTTP requests), MIME::Lite (for email), and XML::Parser.

When Do You Need to Manage Perl Modules?

You will need to check or install Perl modules in two main situations:

• You are installing a third-party Perl or CGI script that lists module dependencies in its documentation or README file.
• Your existing Perl script is throwing a "Can't locate module" error, which means a required module is not installed on the server.

Most modern hosting setups come with a base set of common Perl modules pre-installed. You should check what is already available before attempting to install anything new.

Viewing Installed Perl Modules in DirectAdmin

To see which Perl modules are currently installed on your hosting server, log in to DirectAdmin and navigate to the System Info & Files section. Click on Perl Modules. You will see a list of all available modules along with their version numbers.

Use the search box at the top of the list to quickly find a specific module by name. If the module you need appears in this list, it is already installed and your script should be able to use it right away.

Installing New Perl Modules

If a module you need is not in the installed list, you can request installation through DirectAdmin. In the Perl Modules section, look for an option to install or request a new module. Enter the exact CPAN module name and submit the request. On shared hosting, module installations are typically applied server-wide by the hosting administrator.

For modules that need to be installed immediately and you have SSH access, you can use the CPAN shell:

1. Log in to your server via SSH.
2. Run perl -MCPAN -e shell to enter the CPAN shell.
3. Type install Module::Name (replace with your module name) and press Enter.
4. CPAN will automatically download and install the module and its dependencies.

Fixing "Can't locate Module" Errors

The most common Perl error you will encounter on hosting is something like: Can't locate Some/Module.pm in @INC. This error means the module is not installed or is not in the Perl include path. Here is how to resolve it:

1. Check the DirectAdmin Perl Modules list to see if the module is installed.
2. If it is not listed, note the exact module name from the error message.
3. Contact your hosting provider to install the module, or install it via CPAN if you have SSH access.
4. For modules that you cannot install server-wide, you can install them locally in your home directory using local::lib.

Installing Modules via CPAN over SSH

For more control over Perl module installation, you can use CPAN directly via SSH. First, ensure your hosting account has SSH access enabled (you can enable this in DirectAdmin under SSH Management). Then connect with your SSH client and use the following commands:

• cpan Module::Name — installs a module directly from the command line
• cpanm Module::Name — uses the faster cpanminus tool if available
• perl -e "use Module::Name" — tests if a module is loadable

If you need to install modules without root access, use local::lib to set up a local installation directory in your home folder. This allows you to manage Perl dependencies independently without needing server administrator access.

How Perl CGI Scripts Work on a Web Server

Understanding the CGI execution model helps you configure and debug your scripts more effectively. When a visitor requests a URL pointing to a Perl CGI script, here is exactly what happens:

1. The web server (Apache) receives the HTTP request and identifies the file as executable based on its directory location (typically cgi-bin/) or its file extension (.cgi).
2. Apache forks a new process and executes the Perl interpreter, passing environment variables such as REQUEST_METHOD, QUERY_STRING, HTTP_HOST, and REMOTE_ADDR to the script.
3. The Perl script must begin by printing HTTP headers. The absolute minimum is Content-Type: text/html followed by a blank line before any HTML output.
4. The script outputs its response (HTML, plain text, JSON, or any content type), then terminates.
5. Apache collects the output and sends it back to the browser as the HTTP response body.

This per-request process model means CGI scripts start and stop for every single page view, which is less efficient than persistent runtimes like PHP-FPM or Node.js. For low-traffic legacy scripts, this is acceptable; for high-traffic sites, the overhead becomes significant.

Setting File Permissions Correctly for Perl Scripts

Incorrect file permissions are the single most common cause of Perl CGI failures. The web server process needs execute permission to run your script, but cannot have write permission for security reasons.

The Correct Permission: 755

Set all .cgi and .pl files to permission 755. This breaks down as:

• Owner (7 = rwx): Read, write, and execute — you can edit and run the script.
• Group (5 = r-x): Read and execute only — the server process can run it but not modify it.
• Others (5 = r-x): Read and execute only — same as group.

You can set this in DirectAdmin's File Manager by right-clicking the file and choosing Change Permissions, or via SSH with chmod 755 myscript.cgi.

The Shebang Line

The very first line of every Perl script must be a shebang line telling the operating system which interpreter to use. The standard format for Linux hosting is:

#!/usr/bin/perl

If the Perl binary is at a different path on your server, the script will fail with a "No such file or directory" error. To verify the correct path, run which perl over SSH. If you receive output like /usr/local/bin/perl, update your shebang line accordingly.

Line Endings Must Be Unix (LF)

If you edit Perl scripts on a Windows computer, your editor may save them with Windows line endings (CRLF, \r\n). Linux servers expect Unix line endings (LF, \n). A CRLF shebang line causes the Perl interpreter to fail silently, producing a 500 error with a message about a bad interpreter. Fix this by saving files in your editor with Unix line endings, or run dos2unix myscript.cgi on the server via SSH after uploading.

Debugging Perl CGI 500 Internal Server Errors

When your Perl CGI script returns a 500 error, the browser gives you no useful information. Here are the most effective debugging approaches:

Check the Apache Error Log

The actual error message from Perl is written to the server's error log, not displayed in the browser. In DirectAdmin, navigate to Advanced Features > Site Summary / Statistics / Logs and download the error log. Look for lines containing the script filename — the error message will tell you exactly what went wrong.

Use CGI::Carp to Display Errors in the Browser

Add this line near the top of your script, after the shebang line:

use CGI::Carp qw(fatalsToBrowser);

This sends Perl fatal errors directly to the browser output, making debugging far easier. Remove this line before the script goes live, as displaying error details to visitors is a security risk.

Syntax Check Without Running

Via SSH, you can check a script for syntax errors without executing it:

perl -c myscript.cgi

If the syntax is valid, you will see myscript.cgi syntax OK. If there is a syntax error, Perl will print the line number and description of the problem.

Modern Alternatives to Perl CGI

Perl CGI was the dominant web programming technology in the late 1990s, but modern alternatives offer significantly better developer experience, performance, and ecosystem support. Here is a comparison to help you choose:

PHP — The Default Choice for Shared Hosting

PHP runs natively on virtually all shared hosting plans without any additional configuration. It powers WordPress, Drupal, Laravel, and countless other frameworks. If you are migrating a Perl CGI script to a modern language, PHP is often the easiest path because shared hosting already supports it. PHP-FPM (the process model used by modern PHP) is also far more efficient than CGI, as worker processes persist between requests.

Python — Flexibility and Data Processing Power

Python with Django or Flask is an excellent choice for web applications that need complex logic, database interactions, or data processing. Python is also the leading language for automation scripts, making it a natural replacement for system-level Perl scripts. Running Python web applications on shared hosting requires CGI or WSGI support; for production use, a VPS is recommended.

Node.js — JavaScript on the Server

Node.js lets you use JavaScript for both front-end and back-end development. It excels at real-time features, API servers, and event-driven applications. Node.js requires a persistent process, so it is not suitable for shared hosting in a CGI model — it runs best on a VPS where you have full control over the server environment.

When Perl Still Makes Sense

There are legitimate reasons to keep using Perl:

• You have a working legacy application that would be expensive to rewrite without clear business benefit.
• Your team has deep Perl expertise and the codebase is well-maintained.
• You need powerful text processing with regular expressions — Perl's regex engine is still among the most feature-rich available.
• System administration scripts on Linux servers where Perl is pre-installed and no additional runtime needs to be set up.