Debugging Perl CGI Scripts

By: Jeff Boes

This month, we're going to dig deeply into my bag of tricks and learn how to debug a Perl CGI script. All the tips and techniques here are straightforward; most of them are things you probably know from your first course in programming-that is, if you had one! And that just may be your problem: if you are a self-taught Perl programmer, you may not have received any formal education in debugging.

So, let's set the stage. You've just written your magnum Perlus, a 1000-line masterpiece CGI script that takes orders, processes credit cards, tracks inventory, and calculates satellite orbits. You upload it to the server, and fire up your browser to put it through its paces. And you get something like what appears below:

Um, oops. Now what?

An excellent resource for beginning (and even experienced) CGI programmers is The Idiot's Guide to Solving Perl CGI Problems. And don't be offended by the name: we're all idiots, at times. Let's try a few of their suggestions, and some others as we go, to see what's wrong.

Our first step: verify that the script is available for execution.

• Make sure you uploaded it to the proper directory. Many servers restrict CGI programs to a particular subdirectory of your "home" directory, or of your "public_html" directory , such as cgi-bin or cgi-local. Sometimes the scripts have to be in a central CGI repository, like /usr/local/etc/httpd/cgi-bin.
• Verify that the script's filename is appropriate for your server's set up. Some servers require Perl CGI scripts to have the extension .cgi; some require .pl; others have no such requirement.
• Check that the script is executable: on Unix-based servers, the script's file permissions must be set to allow execution. This can be done from a telnet prompt with a command like this:

       $ chmod 0755 myscript.cgi
       

  or you may be able to use your FTP client software to change the permissions after you upload the script.
• Verify that the server on which you have installed your script has everything you need to do the job.

#!/usr/bin/perl -w
use diagnostics;
print 'Content-type: text/html

Hello, world.';

You may want to take this a bit further though, and for that I can recommend nothing better than perldiver. It's a very useful script that you upload and run to get a comprehensive report on the server: where Perl is, which modules are installed, and a wealth of other information. (You should probably remove this script once you are finished checking your site, as it provides a lot of information that an unscrupulous user might use to break in.)

So, you've taken these steps, and you still can't figure out what's wrong? The next logical step is to verify that the script compiles cleanly. You should as a matter of course start ALL your perl scripts this way:

#!/usr/bin/perl -w
use diagnostics;

There's a third line that you may wish to add to your code.

use strict;

So, now you've added these lines, and perhaps run the code from the command line (if available) using

$ perl -c myscript.cgi

But what if you don't have access to a Perl interpreter at your command prompt? (This is becoming less and less likely, as Perl is available for almost any commonly used platform, and differences between native versions are likely to be slight or esoteric. But perhaps you are developing on a Windows system, and haven't taken the plunge to put Perl on your Microsoft slavebox yet. Or perhaps you are quick-fixing a script using a borrowed computer, and you don't want to inflict a huge Perl installation for a few minutes work.

This is where we get into the meat of what I do for a living: debugging Perl scripts with nothing more than an FTP client and a browser. First, we have to make some alterations to your script:

use CGI qw(:standard);
use CGI::Carp qw(fatalsToBrowser);
BEGIN {
  print CGI::header();
  open (STDERR, '>myscript.log');
}

The second line imports another package called "CGI::Carp", which is an error handling package that replaces and extends the more frequently seen Carp. We grab the CGI family's Carp because we want nicely-formatted error messages, but even more we want the error-trapping facilities provided by the internal routine fatalsToBrowser. This routine will intercept control of our script in the event of a fatal error, and display that error (instead of the "500") in the browser. Think of it as a "fail-safe".

The third line signals a BEGIN block. This is a syntactic element of Perl programs that lets you insert code blocks anywhere in your program (say, in include files, or modules). These blocks only get executed once, as they are parsed (so, they are compile-time code). In what I've shown, the code will redirect any further output via STDERR to a log file. This is quite handy in the CGI environment, because many times your CGI program's errors are either suppressed, or written to a centralized site error log that is very large and may not be readable by you.

There's another thing slipped into the BEGIN block which is intended to save you grief. That's the print CGI::header statement. This forces a compliant HTTP header back to the browser before anything else can slip in there and spoil your day. If you aren't aware of it, CGI scripts must return a proper header at the top of their "output document" so the browser knows what to do with the output. The most common header looks like

Content-type: text/html

Of course, if your script produces a header other than Content-type (say, a cookie, or a redirection), that header will be ignored, pushed down into the document by our BEGIN block header. Again, we'll remove the BEGIN's header at some point when we're convinced the bugs are all dead.

Now, with these lines in place, you have a very good start towards catching and even preventing those frustrating "500"s.