How to Install and Troubleshoot CGI / PERL Scripts
This tutorial is intended for those with little or no experience installing CGI scripts. It only covers installing ready-made scripts you can find at free script resources, it does not cover customizing scripts for your own purpose, nor does it cover building your own Perl programs from scratch.
What is CGI?
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.
What is a Perl script?
- 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 hosts such as Geocities, Tripod, and the like. 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 like: Note Tab Pro (recommended), 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, in it's ORIGINAL FILE FORMAT TYPE.
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. CGI scripts should be uploaded in ASCII ONLY mode.
A little bit of common sense and perseverance helps, as CGI can be frustrating.
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's a script already in there. View the script to see the correct path to Perl. It will be the first line. You can also usually find it in the FAQ pages, set-up message, or support documents provided by your web host.
The most common cause of errors among webmasters new to installing CGI scripts is having the path to Perl incorrect. The first line will look something like this:
#!/usr/bin/perl ...or... #!/usr/local/bin/perl
This 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 about half the time the script you download will have the right path already there.
Check for more...
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 must be specified somewhere in the script. The path is not the same thing as the web address URL in the browser address bar.
My URL is
but the path to my site ON THE SERVER is like this:
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.
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.
Most hosts only allow CGI-scripts to be executed 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 of people. 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 a program or a script.
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'll have to check with the place you got the script or with any help files or comments within the script to see what permissions are needed. Most scripts require a permission of 755. If the script your using doesn't say, try 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.
WS_FTP Light Edition Menu
showing permissions level of 644
WS_FTP Professional Menu
showing permissions level of 755
Some FTP programs, and older versions of WS FTP (and maybe WS FTP LE) do not show the actual file permission number on the permissions screen. Here's a handy chart of the most commonly used CHMOD settings.
|Legend: r=read w=write x=execute
||What it means...
||r w x
||r w x
||r w x
||r w x
||r w x
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.
400 read by Owner
040 read by Group
004 read by Other (anybody)
200 write by Owner
020 write by Group
002 write by Other (anybody)
100 execute by Owner
010 execute by Group
001 execute by Other (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 with 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 for you:
|File Permission (chmod) #:
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.
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 some 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! Just Kidding.
• This is the most common error, and also the worst one to try to correct.
• It's an error in the script itself or in a file it is trying to access or write.
SYNTAX - Can be a simple as a missing semi-colon at the end of a statement line... or any other syntax error that may have been made during configuration or modifications.
CONFIGURATION - This can occur if the script calls internally for a file it can't find, and also if it tries to write a folder or file that does not have write permission.
README / INSTRUCTIONS - 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.
Error Log Files - The Secret Analysis & Troubleshooting Tool
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.
Hosting Documentation - Support, FAQs & KnowledgeBases
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.
Modifications, Testing & Verification
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. Naw, just kidding ya... good luck in your scripting ventures.
We host all our clients with Bluehost and fully recommend their services.