Troubleshooting CGI Programs

CGI programs launched from a web server run under a fundamentally different environment than they do when invoked from the command line. While you should always verify that your CGI program runs properly from the command line,[] this isn't enough to guarantee that your program will work when called from the web server.

[15] See the CGI.pm documentation for tips on command-line debugging.

You should get the CGI developing FAQ and a good tutorial on CGI developing to help you in this. Some of these references are listed at the end of this chapter. Here's a brief list of the frequent problems that arise in CGI developing. Almost all of them trigger those annoyingly unhelpful Server Error messages that you will soon come to know and hate.

• If, when sending HTML to a browser, you forget the blank line between the HTTP header (that is, the Content-Type line) and the body, your program won't work. Remember to output a proper Content-Type line (and possibly other HTTP headers) plus a totally blank line before you do anything else.
• The server needs to be able to read and execute the script, so you need to make sure that whatever user your script runs as (e.g., IUSR_MYSERVER under IIS) has read and execute rights to the script.
• The directory where the script resides must have read and execute rights for the script user.
• The script must be installed in the proper directory for your server configuration. For example, on some systems, the directory may be c:\inetpub\scripts.[]

  [16] This directory is the default for IIS, Microsoft's Internet Information Server.

• You need to have your script's filename end in a particular suffix, like cgi or plx, so that your web server knows that it needs to invoke the Perl interpreter on your script. Make sure that your script directory is not writable by FTP clients. We suggest using a suffix of plx, and associating plx with your Perl interpreter.
• Your server configuration requires CGI execution specially enabled for the directory you put your CGI script in. Make sure both GET and POST are allowed.
• Normally, the web server doesn't execute your script using your account. Make sure the files and directories accessed by the script are open to whatever user the script will run as; this might be the IUSR_INTERNET or anoynmous account, or whatever account you use on your system. You may need to pre-create such files and directories and give them appropriate permissions. Always be alert to the risks when you grant such access to files.
• Always run your script under Perl's -w flag to get warnings. These warnings go to the web server error log, which contains any errors and warnings generated by your script. Learn the path to that logfile from your webmaster and check it for problems. See also the standard CGI::Carp module for how to handle errors better.
• Make sure that the versions and paths to Perl and any libraries you use (like CGI.pm) are what you're expecting them to be over on the machine the web server is running on.
• Enable autoflush on the STDOUT filehandle at the top of your script by setting the $| variable to a true value, like one. If you've used the FileHandle module or any of the IO modules (like IO::File, IO::Socket, and so on), then you can use the more mnemonically named autoflush() method on the filehandle instead:

  use FileHandle; STDOUT->autoflush(1);
  

• Check the return value of every system call your program makes, and take appropriate action if the call fails.