CGI Script Installation 101 - Learn to install perl cgi scripts.

This web page shows how to setup CGI (Common Gateway Interface) using free perl scripts. It does not teach users to write perl scripts.

Introduction
General
Step x Step
Example
Closing Tips
Glossary

CGI
Config
Host
PERL
SSI
Unzip

CHMOD
FTP
Path
shtml
Text Editor

Introduction: [Top]

This page contains basic 'step x step' directions for working on a cgi script. Followed by an actual project - downloading, expanding and installing a script.
To use a CGI script, you will need CGI access on the host / server. In many cases, the script will required support for SSI (Server Side Includes).

Note: Most ISP's (Internet Service Providers) do not allow CGI access at a 'fair' price - if at all. Therefore, you may want to use a small commercial web hosting company where prices are usually $5 to $10/month.

General: [Top]

Instructions for installing and configuring the perl/CGI script can be found in the script itself. However, the instructions often assume that you understand uploading procedures and setting permissions (chmod).
A typical host requires a special cgi-bin directory (folder) that the hosting company installs on the server. If a cgi-bin directory has not been set up for your account, then you probably are not allowed to run your own CGI.
To chmod (change mode) for a file means to set permission. The most common chmod value is 755 (to allow execution of a script). Most FTP software allows the user to change the file permissions. Another option is to use telnet to set permissions. However, many hosting companies don't allow telnet (or SSH) because of security concerns.
A common requirement is that the path to your site must be specified. The absolute path is not the same thing as the URL (browser address). While your URL might be www.yourdomain.com, the path to the site on the server's hard-disk might be something like this: /home/username/www/
Your hosting company will supply the required path info - for perl, for sendmail, for date and for your home (or www) directory i.e. your host provider will supply the correct path's for the server / host computer.
Path to the sendmail program is required for scripts that send email notices (such as message boards). Buyer beware - some hosting companies do not allow you to use sendmail. Others may not allow you to use flat file message board scripts. Still others will not allow chat scripts. Therefore, you should first determine what type of scripts are allowed at your host.
The path to 'perl' is the very first line in the .cgi or .pl config file. Usually it looks something like this #!/usr/bin/perl or #!/usr/local/bin/perl. This is the first thing you should edit/check when you open the config file in your text editor.
Scripts that require SSI (Server Side Includes) in the HTML page(s) will normally require a .shtml extension instead of a .html extension e.g. index.shtml instead of index.html for the default page

Step x Step: [Top]

Download the perl script to your hard drive and unzip it. BTW: All scripts are pure ASCII / text files.
Note: A good source for perl/CGI scripts is the [ Cgi-Resources Index ]
Check for a 'readme' file and/or read the instructions in the beginning of the 'config' file.
Open the config file in a text editor (such as Notepad or Wordpad). After you make the changes, one of the most common mistakes is not saving the script files as a text file. Note: some text editors add a .txt extension by default so you may end up with a file name such as config.pl.txt. Be sure to rename and remove the .txt extension. BTW: upper / lower case does make a difference to some host / servers so it's good practice to use all lower case letters for file names.
Check the first line of the config script to make sure you have the correct path to perl (this is critical but it's amazing how many people forget to do this :)
Change the parameters / variables as instructed in the readme file or in the instructions inside the config file. In other words, carefully read the installation instructions that come with your perl/CGI script. Make any necessary changes to adapt the script to your server. This is where you will likely need to know about the server and program paths supplied by the hosting company.
Upload the script and any library / support files to a directory that allows CGI applications (cgi-bin directory in most cases). VIP: you must use ASCII mode (not binary) when uploading scripts. When using a FTP program, there are two modes of uploading, ASCII and Binary. You can upload the .cgi, pl, .config, .cfg, setup, txt, etc files in ASCII mode because basically they are text. Failure to do this will create some of the most frustrating errors you can imagine (it will make a man bald or a bald man pull out other body hair :)
Set your file permissions. File permissions allow Read(r), eXecute(x), and Write(w) access to the scripts / library files, etc. You use the CHMOD command to change a file's permissions. It's usually more secure and/or easier to use the chmod option in a FTP program (reference the 'help' in your FTP program). The required permissions are supplied in the readme file and/or the instructions. Tip: The most common setting for a script in the cgi-bin directory is 'chmod 755' which is (rxw r-w r-w) in some FTP programs.
Time to 'test' your script i.e. run it. Some times you can do this with a direct address such as www.yourdomain.com/cgi-bin/config.pl (where config.pl is the name of the script). Try this first i.e. type the address to the script in your browser - this is often a quick test to make sure you have the correct permission set and that the file(s) is in the correct directory. The 'preliminary test' may not produce visible results if the output needs to be send to a HTML file. But if the test doesn't produce an error message, you know you have the files in place and the permissions are correct.
Some scripts have to be called from a .shtml file (SSI). If this is the case, open the .shtml file and use the 'include' as shown in the instructions.

Caution: the SSI instructions for some scripts will not work. They may show the use of the #exec command. In other words, you may see instructions that tell you to use something like this: . But it's very uncommon for a hosting company to allow '#exec' commands because of security risk. They often require you to use a 'virtual' include like this:  Then I hate to tell you but that sometimes creates yet another 'problem' with the original instructions. If the script writes or appends to a file or directory, you will more than likely have to set chmod 777 (wide open) for the file and/or the directory Summary: replace any '#exec cgi' statements with 'include virtual' unless your host allows #exec (most Do Not). Then if your script writes or appends to a text file, set the permission (wide open) for the file (and it's directory in some cases). Beware: chmod 777 is not secure so do not use it unless it's essential.

Notes: According to Murphy's Law there will inevitably be some kind of internal server error. Don't panic!! That just means that you are not perfect (yet :) You need to double check once again from the beginning. Here is a check list that may help:
Check:

the first line in the script (check the path to perl)
the absolute path to sendmail, date, library, files as required by the script
to make sure you have saved all files as text files
ASCII or Binary ? Which mode did you upload?
permissions of the script files, directory you created and other text files.
location of the files you uploaded.[Script files - Inside cgi-bin. Others probably outside depending on the instructions]. Did you forget to upload any library / dat / support files?
to see if you made changes in all of the files (as required)?
to make sure you finished all the instruction in the list from your installation / readme file ?
to make sure you used the .shtml extension for files running SSI's.

Example: [Top]

Here is the general info for a simple Text Counter that uses SSI. Or skip the introduction and download the compressed files.
After the files are uncompressed, read (or print) the install.txt. You will discover that this very simple script only requires you to check (and/or change) the path to perl i.e the first line needs to show the path to perl on your server.
The uncompressed files include a .shtml file which is just an example of code to run SSI from a HTML file. You will notice that the 'include' (SSI) is a #exec. The bad news is that the code =  in this script will not work on many servers. Most host providers do not allow you to use 'exec' (execute) because of security risk. They prefer you to use a 'virtual' include like this: 

Hint: One of the area's where many 'newbies' get lost is the path to files (the author may not put the files the same place you do). One basic thing you have to learn is how to handle path information. You must know the location ('path') of the CGI script and the location of the script in relation to the .shtml file containing the 'virtual' include. If the .shtml is located in the directory above the cgi-bin (i.e. probably your home / top directory =www.yourdomain.com) - then the cgi-bin include (shown above), will run the counter script in the cgi-bin folder. Note: The URL that will appear in the browser will be http://www.yourdomain.com/cgi-bin/counter.cgi ) This is an example of how the 'path' relates to the URL i.e. the absolute path is for the server and usually references back to the top directory. The top directory on the server is named by the host, the names vary, such as www, public_html, home, etc. In relation to the browser, the URL for the top directory will show as http://www.yourdomain.com (no matter what name is used on the server as the default) Summary: The top user directory (www, home, public_html, etc) directory on the server is the directory your browser sees when you enter the domain name.
It's difficult to understand how the script will work without an example. Here is a testcounter.shtml file (containing a SSI so the file name has a .shtml extension) <html>
<head>
<title>Test Counter </title>
</head>
<body>
The count is now 
</body>
</html>
The mechanics: open the counter.cgi script in Notepad (or Wordpad) and checked the first line. If your host path to perl is : #!/usr/bin/perl you will have to change the first line to match. Save the file as a text file!
use FTP software to upload the counter.cgi (as ASCII file !) to the cgi-bin directory. Then set the permission as 755 (rwx r-x r-x)
put the counts.txt file in same directory as the counter.cgi. Note: that is the cgi-bin directory in this example. This example will not require a 'path' variable with the counts.txt file in the same directory as the script i.e. he kept it simple as far as setting a path.
In some cases, the instructions assume too much. These instructions were based on #exec but most users will have to use #include virtual. In this case, the script may not 'append/increment' the counts.txt unless it has the permission set to chmod 777 (rwx rwx rwx). (this was the case on my server - I had to reset the counts.txt with chmod 777 command.)
Errors in script: While working on this script I found several errors in the install.txt file. First he assumed that everyone could run the 'exec' command - which is seldom true because of the security issue. Then his instructions have a few mistakes - he indicates the name of the script is allaccounted4.cgi when in fact the zip file for downloading is allaccounted4.zip. But the uncompressed file contains a CGI file named 'counter.cgi' (not allaccounted4.cgi as he mentioned in his instructions and #exec command).
As mentioned, since he didn't mention that your host provider might require you to use the 'virtual include' - he indicates that you can set the permission of the counts.txt to chmod 755 - when in fact, you will need to use chmod 777 (make it wide open = rwx rwx rwx)

Closing Tips: [Top]

I picked the counter.cgi example because it had errors that make you think :) This is what really frustrates new users i.e. having poorly written installation instructions and/or errors that were overlooked (probably during updates / modification). But it's a good example for a newbie because it shows things that typically go wrong. It makes you think about what the files are doing - makes you realize that the script has to 'increment' the counts.txt file so it must be accessible to any visitor - therefore - a chmod 755 does not always work so you try a chmod 777. Caution: I would never use a chmod 777 on a script (.cgi / .pl) file unless the author requires it. (very unlikely). But using a chmod 777 on a .txt file that just stores the count / data is not very dangerous i.e a hacker is not going to care about you count but one may like to modify a script running on your site. I'm beating a dead horse but be careful with chmod 777.

BTW: After you install this counter, you can add a text counter to all your pages (with an include statement). The counts.txt file will keep the counts for each individual page (cool).
Note: Just be sure that you pay attention to the path in the include statement i.e. the  will work for all .shtml files (web pages) in the top / domain directory (www.yourdomain.com) but if you put a .shtml file in a subdirectory you will likely have to make the path statement 'backup' with something like this:  Again - understanding pathnames and how they work is critical (and often a 'real killer' for newbies :( It just takes practice (and a lot of hair to pull out :)

Now for the bad news, counter.cgi was a simple script to set up. Most good scripts require you to set actual path information, including the path to your server directory, the path to the date, the path to sendmail. These are the things that drive most newbies crazy.

There are so many scripts (1000's) that have different requirements that it's impossible to cover all the path's and/or variables you will have to set. But once you learn how these things work then you'll just have to use the instructions from the 'author'

As an example of typical path settings - here are the essential settings from a flat file forum that I use on one host / server. Just so you can see the syntax / typical path info required by a big script.

(1) Specify the locations of your files:

$scripts_dir = "/home/username/www/webbbs";

$webbbs_basic = "$scripts_dir/webbbs_basic.pl";
.
.
etc.

## (2) Define your e-mail notification features:

$mailprog = '/usr/sbin/sendmail';

$admin_name = "Prince";
$maillist_address = "prince\@ibdprince.com";
$notification_address = "prince\@ibdprince.com";

.etc

Another set of examples:

#required changes:
$mailprog = '/usr/sbin/sendmail';
$my_name = 'Prince';
$my_email = 'prince@ibdprince.com';
$date = '/bin/date';
$logfile = "/home/username/public_html/accesslog.html";

Note: both of these examples have 'username' in place of a real username i.e. the username is very simple but some people forget to replace it with the user name that they use for their account. Silly little 'mental lapses' like this (or forgetting to upload files as ASCII (text files) or using a text editor that inserts a carriage return (enter) or not setting the correct permission for the 'config' script (the script that must execute) or not setting the correct permission for a file that must be 'written' to (such as the counts.txt). These various errors can drive a 'newbie' crazy so you often have to just recite a few choice word and/or throw a pillow at the wall to maintain your sanity :)

Glossary: [Top]

CGI: [Top]

An acronym for Common Gateway Interface, CGI is an interface that enables an Internet server to run external programs to perform a specific function. A plain HTML document that the Web daemon retrieves is static, which means it exists in a constant state: a text file that doesn't change. A CGI program, on the other hand, is executed in real-time, so that it can output dynamic information.

The actual programs generally consist of a set of instructions written in a programming language like C or PERL that process requests from a browser, execute a program and format the results in HTML so they can be displayed in the browser.

Summary: CGI, Common Gateway Interface is a way of interfacing computer programs with HTTP or WWW servers, so that a server can offer interactive sites instead of just static text and images

Note: While you hear many people talk about Perl and CGI almost interchangeably, they are not at all the same thing. The Common Gateway Interface (CGI) allows information to pass between a Web site's server and a program (written in Perl or another language) that lives in the "CGI bin" on that server. You send information from your browser to the server; the server passes the information through the CGI gateway to the Perl program; the Perl program does its thing to the information (perhaps conducting a query of a database and creating an HTML page that lists the results), then sends the information back through the CGI gateway to the server, and the server returns the product to your browser. And it all happens in a matter of milliseconds, if everything is running smoothly. Whew.

CHMOD: [Top]

Change Mode (chmod) is the Unix command and system call to change the access permissions of a file. In other words, change Mode (chmod) means to set permission.

The most common chmod command (for scripts) is 755 (rwx r-x r-x)^{See Table}. It's not essential that you completely understand the meaning of the permissions. However, you must have a program / control panel / telnet client that will let you set the required permissions. The following table will help if your FTP programs does not allow numerical values.

Example for 755

	Owner	Group	Public
read=4	X	X	X
write=2	X
execute=1	X	X	X
Totals	(4+2+1)=7	(4+1)= 5	(4+1)=5

config.pl [Top]

Configuration (config) relates to the configuration files that normally set the variables in a perl script. As mentioned in the 'perl' section, the files are text files (ASCII / Dos text) files that must be edited in a text editor. It's just common practice for a perl programmers to name their configuration file as config.pl (or config.cgi). However, these names can be changed to better describe the 'script' e.g. the config.pl file for a calendar script is likely to be renamed to calendar.pl (or calendar.cgi).

FTP [Top]

This is an acronym for File Transfer Protocol -- a very common method of transferring one or more files from one computer to another (usually between a client and a host / server). It's an old standard / protocol with out dated syntax /commands. However, there are now many FTP programs that make it easy to transfer files without having to use these commands. WSFTP-LE is a popular free FTP program that will also allow you to set permissions (chmod).

Host: [Top]

The host is any computer directly connected to a network that provides such services as e-mail, newsgroups, FTP or World Wide Web. Host computer usually references the main computer that shares resources (data, files, images, programs, etc) with clients. While a client is the individual computer requesting the service from the host on the network.

A host and a server often mean the same thing in relation to a network (such as the Internet - the biggest network of them all :). A server is a computer that handles requests for data, e-mail, file transfers, and other network services from other computers (i.e., clients). The only real difference is that a host is typically a computer (or set of computers). While a server may reference a computer or it may reference (server) software running on a computer. In other words, you can have server software (such as an email server program) running on a computer with other software - but the email server functions like a email host (computer) to clients.

Sometimes a reference to 'the host' is really a reference to the 'hosting company' i.e. the company / owner of the host computer - the person(s) who must supply the path, setup information for the server / host computer. So a host can be a computer or the owner of the computer depending on how it's used in a sentence.

Path [Top]

The exact directions to a file, program, etc on a computer. These directions are usually described by means of the hierarchical filing system from the top down, stating the root (top) directory, directory, any sub-directories, the file itself, and its filename extension if it has one. The path is not the same thing as the URL (address / location to a browser). While the URL might be www.yourdomain.com, the path to the site on the host / server's hard-disk might be something like this: /home/username/www/

For perl/cgi scripts, a common requirement is that the path to your site must be specified. Therefore, the host (company) must provide you with the important path information.

A path is sometimes called a Pathname. Pathnames can be absolute or relative. An absolute pathname provides the full path (address) of a file, including the computer system, directories, and sub-directories (if any) it resides in e.g. C:\programs\hopscotch.html Relative pathnames are used to describe a file or directory location on the user's system relating to current position ./cgi-bin/easyscript.cgi

Perl: [Top]

Practical Extraction and Reporting Language (perl) is a scripting language. Perl, is a simple, free, text-processing programming language that pushes much of the Web's inter-activity.

Hint: The fact that PERL is text based means the method used to upload to the host/server is critical. You must upload perl/CGI scripts as text files (often referred to as ASCII or Dos text files). Most FTP programs allow you to set the options so all perl (pl) and CGI scripts are automatically uploaded as ASCII (otherwise expect to forget and unload some as binary files - then they will not execute. Believe me - it happens to best of us - but it sure is confusing to remember to use binary for images, etc but to change to ASCII for uploading CGI/perl scripts.

shtml [Top]

Server-Side Include Hypertext Markup Language (shtml) is the file extension for Web pages that contain server side includes (SSI). Servers have to be configured to use this extension or MIME type as a SSI. It is the filename extension that enables the Web server to differentiate those pages that need to be processed before they are sent to a Web browser. A Web file with the suffix of ".shtml" (rather than the usual ".html") indicates a file that includes some information that will be added "on the fly" by the server before it is sent to you.

SSI [Top]

Server Side Include (SSI) allows a HTML web page to include files from the server. Using server-side includes makes it unnecessary to include multiple copies of the same information in the HTML file, and make it easier to work with frequently-updated information.

A SSI is also a type of comment that directs the Web server to dynamically generate data for the Web page whenever it is requested. The basic format for SSIs are:  (Where #command can be any of various commands).

The simplest command is #include, which inserts the contents of another file. This is especially useful for ensuring that components, such as a header (or footer, menu, etc) are the same on all pages throughout a Web site. For example, to change a header that appears on each page, you only need to modify the include file, instead of updating every individual Web page.

SSIs can also be used to execute programs and insert the results. In other words, you can use SSI to call CGI/perl scripts that display the results directly in the web page. One example of this would be using a SSI to call a counter.cgi script to increment/ display a visitor count.

Text Editor [Top]

A Text Editor is a program that enables you to create and edit text files. Much like any word processor, however not usually as powerful. The distinction between editors and word processors is not clear-cut, but in general, word processors provide many more formatting features. However, one important difference is how the 'files' are saved. A text editor should not insert a carriage return/enter at the end of each line i.e. the formatting options should be suppressed if you use a full featured word processor to edit config files for scripts. That is why it's best to use a pure ASCII text editor (such as Notepad, Wordpad) that allow you to save as a pure ASCII / Dos Text file. (Full word processors often have this option but it's difficult to remember to save as 'dos text' without ANY formatting commands.

BTW: The term HTML editor can refer to source code editors (such as Frontpage, Dreamweaver, Hot Dog, etc) that include many special features for writing and editing HTML source code.

unzip [Top]

To unzip is to return a zip file to its original size with a unzip program. Perl scripts are often zipped (compressed) to speed up the download. When zipped files reach their destination, they must be unzipped (uncompressed) before they can be used - changed in the text editor.

Contact Form

Perl - CGI Scripts 101

CGI Setup - permissions, etc.

Example for 755