This is meant to be a little tutorial that tries to explain what a CGI-script is and how to install one on a server. It's targeted towards novice homepage builders, with no previous experience of CGI-scripts. No UNIX experience is required and it's assumed that you only access the server through FTP and not with telnet.
What is a CGI-script
Just so you know what you're actually dealing with, a brief introduction of what a CGI-script actually is, might be a good place to start. First of all, CGI is not a programming language. CGI is short for Common Gateway Interface, and it's a way for programs and scripts on the web-server to communicate with the web-browser (easily explained).
Usually a CGI-script is made with Perl, which is an interpreted scripting language, very common on the UNIX operation system. However, CGI-scripts may be written in any language, C++ for example (but then it should be called a CGI-program, because it is compiled and no longer a script).
In this tutorial we'll deal with CGI-scripts made with Perl (which is the most common language used for CGI-scripts). Such a script is simply just a text file with a filename ending with .pl or .cgi.
The first thing to check when you're thinking about using a CGI-script on your homepage, is to make sure your web host company support CGI-scripts and that you have permission to use them. If you've noticed a directory called cgi-bin when you're uploading your HTML files, then you most certainly are able to use CGI-scripts.
You also need some more basic things like a text-editor to edit the script (notepad is fine) and a FTP program (we use the free WS FTP LE in this example).
Now to the most important thing, one of the things that usually is the source for errors, the configuration of the script.
Open the script in notepad or your favorite text-editor. Note that it must be an ASCII text editor that saves as pure text, without any formatting, and stuff like Word and other word-processors does.
On the first line of the script, you'll see something like this:
This is the path to the perl compiler (or rather interpreter) on the server. This has to be changed, to be set with the server you will use the script on. Besides #!/usr/bin/perl it usually is #!/bin/perl or #!/usr/local/bin/perl. The best way to find out the correct path is to check your web hosts support pages or look at the first line of any previously installed and working scripts (usually there is some kind of test Hello World CGI-script installed by default).
Next step is to carefully read the documentation of the script and see what other things should be configured. Usually variables that need to be configured are located at the top of the script. Read any comments to see what to do. Comments in Perl are lines starting with the #-character (only exception is the first line).
A common thing is that the path to your site must be specified. The path is not the same thing as the URL. While your URL might be www.foobar.com, the path to the site on the server's hard-disk might be something like this:
Note that the above is just an example, it won't work on your server. Depending on the FTP software and server setup, you might be able to see the complete path when you're connecting to the site with FTP. Otherwise, check the web host's support pages.
Now it's time to actually put the script on your server and set the correct permissions to it. This is done with your favorite FTP program.
When uploading CGI-scripts, use must use ASCII mode (not binary). This is because UNIX and Windows use different line-breaks, but let's not get into that here. The picture shows how the transfer mode may be selected in WS FTP.
Usually there is only one place where CGI-scripts can be executed on the server, and that's in the cgi-bin directory. That's where you should upload the script if your web host has instructed otherwise.
After uploading the script you must set the correct permissions of the script itself and any of the other directories and files it works with.
Permissions are set with a UNIX command called chmod, however, you don't need to be a UNIX guru to use it. It might be used directly through your FTP client instead.
Scripts should have a permission of 755 (chmod 755). In WS FTP, right click on the file and choose chmod, and the following window will pop up. The below example is for permission 755.
Files that should be written to, or directories themselves, that the script uses to save things in, should be set to chmod 777. 777 means that all boxes should be checked.
Alright, that's it. Hopefully you will have a working CGI-script up and running now...
If it doesn't work...
As an inexperienced user there are many traps to fall into. The sad part is that when something goes wrong, it's very seldom obvious what it is caused by. However, there are some things that might help you...
Here are some common errors and what might cause them.
403 Permission Denied
Error 403 is a sure thing; it's because you forgot to change the file permissions of the script. Set all .pl and .cgi files to chmod 755 to be sure.
404 File Not Found
You simply entered the wrong URL. The actual file (i.e. the script) was not found. This is the same error you get when you click on broken links.
500 Internal Server Error
This is the worst one, unfortunately it's also the most common. It's an error in the script itself. Go through all the steps in the configuration and installation section again and confirm they're correct, that should help you track down most of the common errors.
Trying to find the source of an error may be a little bit tricky, however, there are some helpful things that might be available to you.
If you have access to the logfiles on your server, find a file called error_log and check at the end in that file. When a script fails to execute, all errors are logged in that file, and they should give you a hint about what's going on.
Most web host's have support pages with frequently asked questions and instructions about CGI-scripts. There might be some things specific to your particular web host, so read through everything you can find. Also, read the documentation for the script very carefully. Otherwise you will find out sooner than you think what RTFM means when you ask the script author about something that the documentation covered. :-)
Ok, that's it. I hope you found this little tutorial useful...
Written by Stefan Pettersson, July 10th 2000.