CGI Programs

Thank you for choosing CrossLink 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 what's 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 CrossLink 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 NCSA's guide to The Common Gateway Interface and Yahoo's Common Gateway Interface Directory. This document describes the specifics of how to get CGI programs to run on CrossLink's web servers.

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 your 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.004 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 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 (this includes the web server). To calculate the value of the digit, start with 0 and add 1 if you want the program to be 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

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

CHMOD via Fetch

Generic FTP (any operating system)

There are several ways 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

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">