cgi
Trouble-
shooting

Perl Script Troubleshooting:
500 Internal Server Error

We recommend the following books if you want to get into the inner workings of our Perl scripts:

• Perl for Dummies
• Unix for Dummies
• Perl Core Language : Little Black Book
• Elements of Perl
• Beginning Perl

The Ever-Dreaded 500 Internal Server Error

If you have ever installed a CGI script, you probably want to pull out your hair when you see this message:

BEFORE YOU DO ANYTHING ELSE:

Insert the following code at the beginning of your script, just after the "shebang" line:

use CGI::Carp "fatalsToBrowser";

Doing this alone will save you HOURS of frustration. It redirects Perl's error output to the browser instead of (or as well as) the error log. This will allow you to determine if the problem is a syntax error or something more pervasive.

Most Common Causes

1. Script has not been given "Execute Permission"

2. Incorrect "shebang" line

3. Script did not return a valid response header

4. File uploaded as binary rather than ASCII text

5. Extraneous characters in script file

6. Perl encountered a syntax or other logical error while compiling

1. Script has not been given "Execute Permission"

This should be the knee-jerk reflex of anyone installing a CGI script - check the file permission. In order for the server to run the program, the file must have an execute permission at the world level (755).

If your server is running a CGI wrapper which allows CGI's to be run under the username of the website owner, then the script can be set to execute at the owner level. More often than not, however, a Perl CGI script must have read/execute at the world level (commonly chmod 755).

In addition, any libraries that the script uses must also have execute permissions.

2. Incorrect "shebang" line

All Perl scripts must start with an identifier (sometimes called the shebang line because it starts with pound-exclamation point) which tells the server where to find the Perl interpreter so that it can run the program. Normally, it looks like this:

#!/usr/local/bin/perl

or this:

#!/usr/bin/perl

If this line is not the first line of the script, the program will bomb. Also, if it is not correct for your server, the program will crash as well. Find out from your ISP what the correct version is and adjust your Perl scripts accordingly.

3. Script did not return a valid response header

Every CGI must return something to the browser, whether it is a complete web page or just a short text string. If your script does not at least return the following, it will crash with a 500 error.

print "Content-type: text/html\n\n" ;
print "Done."

4. File uploaded as binary rather than ASCII text

Perl scripts must be uploaded to your server as an ASCII text file. If you inadvertently save the file to your server in binary format, the script may crash.

5. Extraneous characters in the script file

Try opening the script in a different text editor and re-saving it to your hard drive before FTPing it. Some editors add extraneous characters that will cause the script to crash. Whatever you do, NEVER use Word, WordPerfect, or any other 'word processing' program. You should only use a basic text editor like TextWrangler, WordPad, Pico, BBEdit, or the like to work with any kind of program script. I suggest using a developers editor like Komodo, CodeWarrior, or MacPerl, so that you can debug the script before you upload it.

If you still can't trace the bug, disable all the options by entering 'no' in the customization section. Also, if the script says to 'comment' a line, place a pound sign (#) in front of the line. This will cause the perl interpreter to ignore the line. Insert the following code in various places in the script.

print "Content-Type: text/html\n\n";
print "Break.";
exit;

Once you get the script working, move the break code to a later spot in the script and run it again. This way you can isolate the code that is causing the problem. Logistic errors are the worst kind. Syntax is easy.

6. Syntax Errors

Insert the following code at the beginning of your script, just after the "shebang" line:

use CGI::Carp "fatalsToBrowser";

This will return Perl's specific error reporting to the browser.

Often, "customizable" scripts require you to reconfigure certain variables and paths to make them work for your specific server. The explanation of variables in general is beyond the scope of this tutorial; however, here are a few rules of thumb for customizing Perl scripts:

Incorrect Variable Assignment
Variables in Perl must start with a $, @ or % ($ is a scalar and is most common. ex: $customer_name ). Sometimes the symbol is inadvertantly left off a variable name. (i.e. customer_name instead of $customer_name).

Statement Not Terminated
Every statement in a Perl script must end with a semicolon (;) except conditionals and subroutines that are enclosed in brackets. Check all of your lines to make sure this is the case.

Quotes Missing
References to strings (1 or more characters that do not have a numerical value) must have quotes (") or apostropes (') on each end. (i.e. $customer_name = 'John Brown; instead of $customer_name = 'John Brown';)

Not Escaping Metacharacters
Certain characters require escape characters when they are included in a quoted string. In Perl this is the backslash "\". Commonly found in customized sections are the quotation mark (seen as \") and the apostrophe (seen as \'). So if you see the following heiroglyphics,

$return_link = "<a href=\"www.myserver.com\">Link to this site</a>";

you will know what's going on.

Other Problems:

"Document Contained No Data" pop up window in browser
This appears when the script does not return any information to the browser. It often happens when the script tries to access a nonexistent file and then return information from that file. Check that the filepaths are correct.

Viewing Environment Variables
Environment.cgi is a handy little utility that allows you to see all of the Environment variables that are active on your particular server. Some useful values are listed below:

DOCUMENT_ROOT - file path to the user's public web directory

SCRIPT_NAME - relative file path to the CGI script called

SCRIPT_FILENAME - absolute file path to the CGI script called

HTTP_HOST - domain of the host website

Create your own environment.cgi using the perl code below:

#!/usr/bin/perl
# CAUTION: REMOVE THIS SCRIPT AFTER USE!
# IT REVEALS SPECIFIC SERVER INFORMATION WHICH
# CAN BE USED IN A SERVER ATTACK

print "Content-Type: text/html\n\n";
print qq~<html><head><title>Environment Variables </title></head><body><center>
<table border="2" cellpadding="10" cellspacing="10">
<th align="left"><h3>environment variable</h3>
<th align="left"><h3>contents</h3><tr>~;
foreach $var(sort keys(%ENV)){ print "<td> $var </td> $ENV{$var}</tr>" }
print "<tr><td>Where we are:</td>".`pwd`."</tr>\n";
print "<tr><td>Sendmail:</td></tr>\n".`whereis sendmail`;
print"</table></center></body></html>";