Running & Debugging CGI Programs

---

Thank you for choosing Why? InterNetworking to supply your Web/FTP hosting needs. In this document, we'll explain how to set up CGI programs with your corporate or corporate deluxe account, and how to determine whats wrong if they don't work.

Contents

1. How to Create CGI programs
2. How to use Perl (or other script languages)
3. How to debug your CGI program

1. How to Create CGI programs

A CGI program at Why? InterNetworking is any program or script that can run on the Unix web server. These can be written in C, Perl, a shell script language, or a number of other alternatives.

This document does not describe the process of designing a CGI program. If you require assistance designing and implementing CGI programs in general, please see the NCSA's guide and Yahoo's Resource page. This document describes the specifics of how to get CGI programs to run on Why? InterNetworking's server.

First, do not put your programs in a directory called "cgi-bin." Cgi-bin is an alias for the server-wide CGI repository found in /httpd/cgi-bin. (Similarly /icons/ is an alias for a large number of icons which exist in /httpd/icons/.)

Second, your CGI program must end with the extension ".cgi." If you use some other extension, the server will attempt to return the program as a file rather than running it and returning the output.

Finally, your CGI program must be executable by the Unix operating system. This means that in the file permissions, the "execute bit" must be enabled. To do this while telneted to the web server, type "chmod 755 prog.cgi" where "prog.cgi" is the name of the CGI program. If you wish to use a perl or other CGI program without the hassle of logging in, see below.

2. How to Use Perl (or other script languages)

The web server supports Perl scripts (we use version 5.002 of the perl interpreter), Bash shell scripts, and C shell scripts. If you wish to use one of these programs on the web server, you will need to adjust the program so that the operating system knows where to find the interpreter, and you must set the "execute bit" on the program so that the operating system knows its dealing with a program and not a plain file.

The operating system on the web server determines where the interpreter is located by looking at the first line of the script. The first line of your CGI program should be one of the following:

• Bash-Shell: "#!/bin/bash" (also works for Bourne and Korn shell scripts)
• C-Shell: "#!/bin/csh"
• Perl Script: "#!/usr/bin/perl"

To install a script CGI program without the hassle of logging in with telnet, you will need to set the program's file permissions via your FTP program.

Each digit in the file permissions (The "755") represents a user class: The first digit is your permissions for accessing the file (or the file's owner if the file is not yours). The second digit is your group's permission to access the file (other web users but not the server program). The final digit is everyone else's permission to access the file. To calculate the value of the digit, start with 0 and add 1 if you want the program to be runable (executable), 2 if you want the program to be writable (as opposed to read-only) and 4 if you want the program to be readable.

All CGI programs must end with the extension ".cgi" and must be both readable and executable. They do not need to be in any special directory in order to work, however please be aware that the directories /cgi-bin and /icons are redirected to the public icons and cgi-bin directories, so if you try to put files there, it won't work.

The ways to do set the file permissions vary depending on what type of FTP client you're using:

• WS-FTP (Microsoft Windows)
• Fetch (Apple Macintosh)
• Generic FTP (Any Operating System)

Windows: WS-FTP

To use the CHMOD command with WS-FTP, click on the file listing window with the right-hand mouse button. This will bring up the FTP Menu. Select FTP Commands and then SITE. Finally, type in the command "chmod 755 program.cgi" where program.cgi is whatever program you want to change the permissions on.

Figure 6. CHMOD via WS-FTP

Newer versions of WS-FTP also have a "chmod" command on the menu bar that you access with the right-hand mouse button. This command will work as well.

Apple Macintosh: Fetch

To use the CHMOD command with Fetch, look under the Remote menu and select Send FTP Command down at the bottom. This will bring up a dialog box where you can type in the command. Type in "site chmod 755 program.cgi" where program.cgi is whatever program you want to change the permissions on.

Figure 7. CHMOD via Fetch

Generic (Unix, Windows, Etc.): FTP

There are several ways that may or may not work to use the CHMOD command with a general ftp client. Normally, you can type, "chmod 755 program.cgi" where program.cgi is whatever program you want to change the permissions on. Sometimes you have to type "site chmod 755 program.cgi" or "literal site chmod 755 program.cgi".

ftp> chmod 755 program.cgi
200 CHMOD command successful.
ftp> site chmod 755 program.cgi
200 CHMOD command successful.
ftp> literal site chmod 755 program.cgi
200 CHMOD command successful.
ftp>

3. How to Debug your CGI programs

500 Server Error
The server encountered an internal error or misconfiguration and was unable to complete your request.
Please contact the server administrator, webmaster@crosslink.net and inform them of the time the error occurred , and anything you might have done that may have caused the error.
Error: HTTPd: malformed header from script something.cgi

If you see this error when you try to use your CGI program, then something is wrong. What's wrong with it? Well, the message above is less than helpful in determining why the program failed.

To determine why your CGI program is failing to work, you should run it in debugging mode. To do so, add "/cgi-bin/debug" to the front of your CGI program's URL. This will cause the results to be displayed to you as plain text instead of HTML, and it will display any errors that the program reports.

So, for example, if you're calling a CGI program from an HTML form where the FORM tag looks like this:

<FORM METHOD= "POST" ACTION= "http://www.crosslink.net/cgi-bin/mailform" >

Then adjust the URL so that it looks like this:

<FORM METHOD= "POST" ACTION= "http://www.crosslink.net/cgi-bin/debug/cgi-bin/mailform" >