CGI Frequently Asked Questions (FAQ)

This page has been accessed times.

This file contains the answers to questions I get asked most often. If there's something you'd like to see covered, let me know.

If you find this info helpful, kindly drop me a line and let me know; I really enjoy getting feedback (both good and not so good)!

Max H. Parke
Lodi, New York
<mhp@lightlink.com>

Note:Throughout this file, username refers to your Lightlink UNIX login user name.

1. What is CGI?

CGI is an acronym for Common Gateway Interface, which lets you write programs at the Web server.

2. What's a CGI-BIN directory?

In UNIX you generally group all your executables in a directory, commonly named `bin'. For CGI's, this directory by convention is named cgi-bin. 
(Example URL: http://www.lightlink.com/cgi-bin/imagemap...)

Lightlink has a system-wide cgi-bin directory where common cgi's such as the imagemap and Web page traffic counter programs reside; you don't need to do anything other than point to these in your HTML files to use them.

In my own work I don't like to use cgi-bin directories since I usually have several unrelated projects and would rather have the cgi's in separate directories. Using cgi-bin also causes certain conflicts with the Web server software.

The other way to identify CGI's is to have a filename suffix of `.cgi' on your CGI scripts. (Example: /home/www/username/foo/foobar.cgi)

3. What's a .htaccess file?

There must be a .htaccess file in each directory from which you want to run CGI's. This file must contain, at a minimum, the following line: 
Options ExecCGI FollowSymLinks

(Note: the FollowSymLinks is needed in your home Web directory to allow index.html to work properly).

The .htaccess file must be readable by the Web server (Example: chmod 604 /home/www/username/foo/.htaccess)

4. How do UNIX file permissions work with CGI?

All files in your Web directories must be readable by the Web server. For text files (html, .htaccess, GIF's, JPEG's, etc), you can use permission `604'. Since CGI's are executable, you must have execute permission as well. Binaries (e.g., compiled C programs) can use 701; scripts (e.g., PERL or Bourne shell) must be readable as well, so 705 is needed. (Example: chmod 705 /home/www/username/foo/foorbar.cgi)

The directories themselves must be readable, too. (Example: chmod 701 /home/www/username/foo)

5. What about adding authentication?

There used to be a tutorial at wintermute.ncsa.uiuc.edu; however, this seems to be broken. Following are the setups taken from my security demo.

.htaccess:

Options ExecCGI

AuthType Basic
AuthName SAMPLE PROTECTED DOCUMENT
AuthUserFile /home/www/username/xxxdemo/.htpasswd
AuthGroupFile /home/www/username/xxxdemo/.htgroup
<Limit GET>
require valid-user
</Limit>

.htpasswd:

sample:5aa4g6lgnXyEs

.htgroup:

mhpgroup: mhp
Notes: the .htgroup file is not really used or needed in this example; also the files must be readable (see Q4 above). To create and maintain the .htpasswd file, you must use the htpasswd program, which is installed at Lightlink.

Click here for more information.

6. Most common errors running CGI

1) The CGI files are not readable and executable by the Web server (see Q4 above)
2) The .htaccess file is not present, or is not readable (see Q3 & Q4 above)
3) The CGI must produce a two-line MIME header; the second line must be blank. For example: 
Content-type: text/html
4) The CGI must be identified as such to the Web server; either by placing it in a `cgi-bin' directory, or having as the last four characters of its file name `.cgi' (the preferred way).

7. How does IMAGEMAP work?

I've written a tutorial on this; this FAQ contains some additional info based on common questions I receive.

First, you start with a URL such as the following in your HTML file: 

<A HREF="http://www.lightlink.com/cgi-bin/imagemap/username/fish/fishmap.txt"> <IMG SRC="xxx.gif" ISMAP>
                                                  ^
                                                  |
                                                  |
The URL gets "split" into two parts as shown. The first part causes the imagemap program to be run; the second part identifies the file name of the image mapping text file which you must create. The Web server automatically prepends /home/www/ to this, for a resulting filename of (in this example): 
/home/www/username/fish/fishmap.txt
(Note that in Lightlink, /home/www/username/ is actually an alias to /home/ftp/pub/username/www)

Finally, the imagemap program at the Web server reads the fishmap.txt file, and decides what to do based on where the mouse click occurred. An excerpt from fishmap.txt: 

default /username/fish/none.html

# Top fish eye
circle /username/fish/ow.html 313,28 313,44
Again, the Web server adds /home/www to the beginning of the file name corresponding to the mouse click. If the user clicked on the fisheye, the resulting 
/home/www/username/fish/ow.html
would be displayed.

Note: The imagemap.conf file that appears in the tutorial's distribution is an old file that's not used.

8. Most common error messages running CGI

9. What are Server Side Includes?

Also known as SSI and Server Parsed HTML, Server Side Includes allow you to place additional commands in your HTML files which are interpreted by the lightlink Web server software before being sent to the client's browser. For example, you can use SSI to display a randomly chosen image on your page, among other goodies.

SSI is enabled by using a filename suffix of .shtml instead of the usual .html suffix on ordinary html files. Also, you must add the Includes directive to your .htaccess file, for example:

Options Indexes FollowSymLinks Includes ExecCGI
AddType text/html .shtml
AddHandler server-parsed .shtml
XBitHack full

This example .htaccess file will instruct the Web server to parse all documents which have a file name suffix of ``.shtml''.

Since using SSI increases server overhead, you should use it sparingly.

If you want your index.html file to be parsed automatically, so that your home page can take advantage of SSI features, use the following trick which came to us courtesy of one of our users. I haven't used this myself, but I have heard from more than one customer who has had success with it. Rather than trying to name your home page index.shtml, this trick works by changing the default for the entire directory to be parsed html.

You need to modify the .htaccess file in the directory containing the index.html file to be parsed as follows: 


Options Indexes FollowSymLinks Includes ExecCGI
AddType text/html .html
AddHandler server-parsed .html
XBitHack full
Every .html file in that directory will be parsed.

You'll also need to change the permission to that of an executable file: 


chmod 705 index.html

Warning

Since every html file in the directory will now be parsed, increasing the load on the Web server, you will want to make sure that only files that contain SSI appear in this directory. "Ordinary" html files should be placed in a separate directory!
© Copyright 1995-1996, Max H. Parke <mhp@lightlink.com>