CGI Troubleshooting

Incorrectly Set Permissions

The mother of all errors, knowing what the file permissions need to be is critical for your PERL applications to function. You will need to refer to your program's documentation to learn what permissions need to be set for which files.

Do NOT set permissions on any file that resides within your cgi-bin directory to 777 (rwxrwxrwx) -- use 755 (rwxr-xr-x) instead -- even if the program's documentation calls for the 777 permission.

Some Important Notes About Permissions and
Typical Permission Settings:

Executed via the web by anyone: chmod 755 (rwxr-xr-x)

Executed only through the command line: 700 (rwx------)

Library files: 644 (r-wr-wr-w)

World writable: 777 (rwxrwxrwx) -- this is not necessary on our servers and will only work on files that are placed outside of the cgi-bin directory.

We run suEXEC seamlessly through the Apache webserver. This affects how file permissions are set. This automatically makes the 777 (rwxrwxrwx) permission return an error when applied to file permissions. Perl scripts will never work if the permissions on the file are 777.

Files that would otherwise require world write access (writable files) do not have to have this permission (777 or rwxrwxrwx). Since the Perl script which will open and write to the file is executed under the owner's userid, and the file is also owned by the same user, then the file only needs to be writable by the owner, not the world.

Finally, there are some freeware or perhaps even commercial Perl scripts which may require you to set a directory to rwxrwxrwx (chmod 777). Again, this is not necessary. Setting the directory permissions to 755 should always be sufficient. If you do set any directories to rwxrwxrwx, then any Perl scripts located inside of this directory will not execute!

If your program does require that you change the permissions of the program's directory to 777 (rwxrwxrwx), make sure that you put the program AWAY from your other cgi programs. Make a new directory, put it outside of the CGI-BIN, whatever, but do not change the permissions of your CGI-BIN to 777. This will cause all of the other scripts in to FAIL.
You should NEVER change the permissions on your cgi-bin directory.
If you have already changed the permissions of your CGI-BIN, you need to change it back to 775 (rwxrwxr-x) or 755 (rwxr-xr-x).

While troubleshooting your scripts, you may be tempted to change everything to 777 (rwxrwxrwx), but if you do, remember that this setting offers absolutely NO security. Once your program is complete, remember to change your permissions to whatever is the most secure setting while allowing the program to still function.

NOTE: HTML documents are not viewable from within the cgi-bin directory structure. If your program is writing to an HTML file, that file must reside within the www directory structure, but outside of the cgi-bin directory.

Incorrect Path to Perl

This is a very common problem, and is easily fixed. The first line of your program needs to be the correct path to where Perl is installed on your server. On all servers, the following path is correct:
If you need a special version of Perl, you can see what's installed by telnetting to your domain and typing: whereis Perl. If you need to see where Perl5 is, type: whereis Perl5, etc.

Uploaded in BINARY Format

This is another common problem -- the fix is just to re-upload the file in ASCII format. You'll need to consult your FTP program's documentation to figure out how to switch modes.

BINARY mode is used for non-text items, such as executables (*.exe), zip files (*.zip), image files (*.jpg, *.gif) and the like. ASCII mode needs to be used for text only documents, which includes *.txt, *.cgi, *.pl *.css, *.html, etc.

Incorrect Program or Library Paths

If you need to use the server path to programs, make sure that it is in the following format:
The first slash is necessary. A trailing slash may or may not be required, depending on the program. If you are not sure of the exact server path to your file, go into your site via telnet, navigate to your file and type: pwd. You will be given the correct, full path to your file.

Unescaped @ or "

There are several special characters that Perl uses to perform specific functions, such as @ $ " . Internal Server Errors will definitely occur if you have an unescaped @ or " in your variable definition. (An unescaped $ within a variable definition or subroutine usually will not cause Internal Server Error, but may make your program behave contrary to the way you want it to).

As Perl reads through the script, it will look for these characters and try to execute a command based on it. As you may already know, the @ is used to define arrays, the $ is used to define variables, and the " is used to enclose variable definitions. For this reason, if you want to use any of these symbols within your variable definitions, you have to "escape" them.

Escaping is simply adding a backslash before the special character like this:


he said \"I really need to escape that quotation mark\"

so your final variable definition will look like:


$a_useless_message="So he said that \"I really need to escape that
quotation mark\"";

Not escaping these special characters will cause an error in your program when you try to run it.

Alternatively, you can change the " " surrounding your variable definition to ? ?, which means that your variable definition will be taken literally instead of attempting to process a function.


$test = "this will produce @n error";
$test = ?this will not produce @n error?;
$test = "this will not produce \@n error";

Incorrectly Closed Subroutine, Line or Library

All subroutines begin with a { and end with a }.

Most lines must end with a ;.

Though there are times when you really don't need the final ;, if you're not 100% sure when you don't need it, it's best to use it. It won't do any wrong being there, but it sure will cause problems if it is not there when it's supposed to be.

The last line of a library (a file that does not actually perform any function, but lists variables or contains only subroutines) must be 1;.
This is because each file in the program must return a true value. Placing this 1; on the last line does this.

Incorrect Operating System

Our servers are running Linux over Apache. Programs designed to run on other operating systems can either function properly, not function properly, or not work at all, producing Internal Server Errors.
Please make sure that the program you are attempting to run is intended for a Unix-based server.

© Copyright 2004-2009 DataBoy