Beginner's Guide to Installing CGI Scripts

This tutorial is intended for those with little or no experience installing CGI scripts. It only covers installing scripts you can buy or find for free, it does not cover writing or customizing scripts.

What is a CGI script?

CGI is an acronym for Common Gateway Interface. It's not a programming language as many novices believe, it's actually a small, uncompiled software program that provides a way for a web-server to communicate with a browser in ways not possible with HTML alone. Most CGI scripts are written in a programming language called Perl. Although other languages can be used to create CGI scripts, Perl is by far the most common, so this tutorial will focus on Perl scripts.

A Perl script is really just a common text file written in the Perl language, and saved with a .cgi extension (or .pl extension for some scripts). CGI scripts are server side scripts, which means the scripts are executed on the server with only the output of the script shown in the browser. This is the opposite of JavaScript, which is a script contained within an HTML page and executed client side by the viewers computer.

Requirements

Before looking for scripts, first check to see if your web host supports them, and that you have permission to use them. Some don't allow it, especially free hosting companies. If you've seen a folder called cgi-bin or cgibin when you have uploaded your HTML files, then you are most likely allowed to use CGI scripts.
With some hosts though, you may have to request they create a cgi-bin directory for you, it's not always included by default even with hosts that will allow and support them. A few may even want to test and approve any scripts you use before allowing you to use them.
You also need a text editor to edit the script (Notepad, Textpad, etc.). You won't have to edit much, if anything, but you will need a text editor and not a word processor. A word processor adds formatting to the saved file, which will break the script. Whatever you use, you must be able to save the file as plain text.
You'll also need an FTP program. I use WS_FTP, which comes in a free Lite version, or a commercial Pro version. Either will work fine, though the free version is getting hard to find. CGI scripts should be uploaded in ASCII mode.
A little bit of common sense and perseverance helps, as CGI can be frustrating.

Configuration

The first thing you need to know is the path on your server to the Perl interpreter. If you have cgi-bin already in place there's a good chance there may already be a CGI script in it. View the script to see the correct path to Perl. It will be the first line. You can also usually find it in your web host's FAQ pages, set-up message, in yoru site's control panel, or in the support documents provided by your web host.

The most common cause of error among webmasters new to installing CGI scripts is using an incorrect path to the Perl interpreter. The first line will look something like this:

#!/usr/bin/perl ...or...  #!/usr/local/bin/perl

That first line may or may not have to be changed. The path has to be the correct one for your server or it won't work, but in my experience about half the time the script you download will have the correct path.

Check the Perl Script for Instructions

While you've got the script open to check the path to Perl, look at the top of the script for comments regarding any other variables that need to be configured. Often there are none, but occasionally you'll find one or more. Read the comments to see what to do. Comments in Perl are lines that start with the hash mark ( # - also called the pound sign).

# This would be a comment in a Perl script.
# Comments often read across multiple lines.
# Each line that starts with # is a comment,
# except the first line, which is the path to Perl.

One thing that is occasionally required that you might find directions for in the comments is that the path to your site may be required somewhere in the script. The path is usually not the same thing as the web address (URL). My URL is http://www.boogiejack.com, but the path to my site ON THE SERVER is like this:

/mmt/web/users/boogiejack/www

The above example probably won't work on your server, even if you change the domain name portion from mine to yours. The paths are different on almost every server. If you use WS FTP, you'll be able to see the complete path in the window above the server-side files when you connect. Otherwise, check your web host's support, FAQ, or set-up pages.

Installation

Once you've configured the script for your server, it's time to upload it. Again, when uploading CGI scripts you must upload them in ASCII mode. The other option is binary mode, which is used for images and other types of binary files. A CGI script is a text file so it's should be uploaded in ASCII mode.

Technically, CGI scripts can be executed from any directory, but most hosts only allow it from the cgi-bin, so that's where you should upload the script to. After uploading the script you still aren't finished. You must set the correct file permissions for the script and any other directories and files the script uses.

Understanding File Permissions

UNIX servers allow you to set different levels of access to a file for different groups. There are three groups in terms of file access, and three different permission types each group can receive. You don't really have to understand this part to set permissions if you know what permissons the script should have, but it's here for those that really want to know. Feel free to skip down to Setting Permissions if you're in a hurry.

The groups are:

User: The 'user' group consists only of the owner of the file (your hosting account).
Group: The 'group' group (Tricky English, huh? Pay attention!) consists of the other users on the server—you can usually remove their permissions entirely if you think it is necessary.
Other: The 'other' group consists of everyone else—most importantly, the web server falls into the 'other' category.

The permissions are:

Read: The 'read' permission allows a user or program the ability to read the data in a file.
Write: The 'write' permission allows a user or program the ability to write new data into a file, and to remove data from it.
Execute: The 'execute' permission allows a user or program the ability to execute a file, if it is an executable program or script.

Setting Permissions

Permissions are set with a UNIX command called CHMOD. Don't worry, you don't have to know UNIX commands, it can be done quite easily with your FTP client. You should be able to find the permissions you need via the source where you got the script or within the script itself, or in a Read Me or set up file that may have came with it. Many scripts require a permission of 755, so if you can find the correct persmisisons you might try guessing 755.

To set file permissions using WS FTP, left-click the script to highlight it, then right click on the highlighted file and a pop-up menu will open. Choose chmod(UNIX) from the pop-up menu. Below is a screen capture of the Screen for setting file permissions.

Some FTP programs, and older versions of WS_FTP, do not show the actual file permission number on the permissions screen. Here's a handy chart of the most commonly used CHMOD settings.

Permission #	Owner	Group	Other	What it means...
777	r w x	r w x	r w x	Writable Directory
755	r w x	r x	r x	Standard (non-writable) directory/executable file
666	r w	r w	r w	Writable File
644	r w x	r	r	Readable File
Legend: r=read \| w=write \| x=execute

Obviously there are many other combinations, although they are rarely used. It's not to hard to figure out the settings when you run into an oddball script. Each group and permission has an assigned number. To get the correct permission number (chmod setting), just add up the combinations.

Permission assignments:

400	read by owner
040	read by group
004	read by anybody (other)
200	write by owner
020	write by group
002	write by anybody
100	execute by owner
010	execute by group
001	execute by anybody

Here's an exercise for you. You have a script that calls for the following permissions:

Owner: read, write, execute
Group: read, write
Other: read, execute

Before looking at the chart below for the answer, see if you can add up the correct numbers according to the permission assignments and come up with the correct CHMOD setting number.

Here is the answer worked out in living grayscale for you:

	Read	Write	Execute	Totals
Owner	400	200	100	700
Group	040	020	000	060
Other	004	000	001	005
File Permission (chmod) #:				765

You peeked at the answer without trying to work it out for yourself didn't you? Tsk, tsk . . . how are you going to learn that way?

As you can see, if you add up the sub-totals in the right hand column in the table above, you'd get a file permission of 765. The numbers in each column are pulled from the permission assignments as shown above the table.

Troubleshooting

If you're reading this tutorial, you're likely inexperienced at installing CGI, and the bad news is that there are many things that can go wrong. To compound the problem, the thing that is wrong isn't likely to be obvious to you. Here are the three most common errors and possible causes:

403 Permission Denied

Error 403 is as much of a sure thing as you'll find. You get this error when you forget to change the file permissions of the script, or changed them to the wrong setting.

404 File Not Found

The actual file (i.e. the script) was not found. This is the same error you get for broken links. You simply entered the link incorrectly.

500 Internal Server Error

You don't want this one! Don't do it!! It will blow up the entire Internet!!!

This is the most common error—and also the worst one to try to fix. It's an error in the script itself. Read the documentation for the script very carefully and make sure you followed each step correctly. Go back through all the configuration and installation steps and try to find what is incorrectly configured. Of course, this assumes you have a good script to begin with. It could also be a programming error by the script author, although that isn't real common. Most authors will test their scripts thoroughly before releasing them to the public.

If you have access to the logfiles on your server, find one called error_log and check the end of that file, assuming you check it right after you've discovered your script doesn't work. When a script fails to execute, errors are logged in that file and you should find the recent script errors listed there. It may give you a clue as to what is wrong.

There also might be something peculiar to your web host, so read all your host's documentation. If you can't find anything there, you might check with your host's support services. As a last resort, you could contact the script author. Be sure you've gone through all the other means of troubleshooting first before contacting the script author, especially if it's a free script. As a last resort or to save time and frustraion, many vendors who sell or give out free scripts will install them and get them working for you for a small fee, so that's usually an option.

Lastly, make sure your script works before linking to it for public access/use. If you serve up a broken script, it causes the clock on the users computer to skip ahead 4 years. People really don't like aging that fast.

Whew! That was a humdinger, wasn't it? Yeah, you loved it though. :o)

Back | Web Design Tutorials Index

Almost a Newsletter

Changing list hosts. Will post a new subscribe form shortly.

Did you know...

The member's site has about 100 standards compliant HTML and CSS tutorials, 31 handy reference charts, reprintable content, web graphics, exclusive fonts, free software, free ebooks and more? All this for less than 9 cents a day! [ Details ]