Perl Scripts Installation, FTP, File Permissions

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?

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 viewer’s 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 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.

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

http://www.one-serve.com

but the path to my site ON THE SERVER is like this:

/home/oneserve/public_html/

     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.

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.

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'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 Client, Light Edition Menu, Permissions

WS_FTP Professional Menu
showing permissions level of 755

WS_FTP Client, Professional Menu, Permissions

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

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

	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.

Practice Pad:

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 some common errors and possible causes:

Page Errors

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