Introduction

Before you think about installing a Perl script you must make sure
that you are able to run a Perl script on your site. Also youíll need some
basic software tools.

System Requirements

There are two requirements that must be met before you can run a Perl/CGI
script.

A. Youíll need to have access to run a Perl Script and have CGI enabled
on your hosting account. If your hosting service does not offer this service
(many donít) we suggest getting a host that charges a small monthly fee.
We recommend TheSuperSite.

B. Youíll need the ability to run a Perl script. This means the Perl
interpreter must be installed.

Web Server Configuration

Before you can run a Perl script, you'll need to know a few things.

1. You must know the path to the Perl interpreter.

2. You must know the server path to your account.

You need to consult the documentation for your web site provider to
see if you have access to Perl. Most scripts require Perl 5, but some only
require Perl 4. Most hosts have both Perl interpreters installed each having
itís own path.

The first line in a script points to the location (or path) of the perl
interpreter on your server. If you're on a UNIX system (via Telnet or direct
connection), you can type

which perl

and you'll get the path, which should look something like this:

/usr/bin/perl

On every CGI script at the top there is a path to Perl. It usually
looks like this:

#!/usr/bin/perl

or

#!/usr/local/bin/perl

Normally, anything following '#' is considered to be a comment,
but the first line in a script is the exception.

Frequently, you will have to configure scripts in order to work on your
server, especially those that write to files such as counters and guest
books. It is important to understand the difference between URLs and server
paths. A URL looks like the lines you type into your browser window:

http://www.domain.com

A server path tells the server where to find a file. You'll need
to ask your ISP for the correct server path to your root directory. Subdirectories
are added to this path. For instance, suppose your server path is

/usr/www/domain

Now let's say that you must put all your CGI scripts in a special
subdirectory named 'cgi-bin'. The correct server path to your scripts would
then be

/usr/www/domain/cgi-bin/If your script requires additional files, you can create them with
your text editor and upload them with your script.

Tools

There are a few tools youíll need to installing scripts: a text editor,
and an FTP program.

Text Editor

You'll need a text editor to make minor changes to downloaded scripts,
or to write your own. Windows users can use Notepad, MacOS users can try
Mactext or BBEdit, and UNIX users can try vi or emacs.

FTP Programs

The easiest way to move your script onto your server is to use a graphical
FTP program. There are many that are available, such as CuteFTP or WSFTP
for Windows, or Fetch for the Mac. Whatever program you choose, the graphical
interface works in much the same way. You can upload the file to your server,
then you can change the permissions. If you need an FTP program we suggest
you visit FREEPrograms.com.

Installing Your Script

One important thing to remember is to use ASCII mode when you upload
scripts to the server. If you think you have everything configured properly
but the script won't run, reload it using ASCII mode, just to be sure.
It's a common source of error.

If you click on a file or subdirectory located on the server you will
have the option of changing the permissions. For example, in WSFTP, if
you highlight a file on the server, then click the right mouse button,
you can set the permissions on a file. Check your software documentation
to see how your program handles it.

The permissions on a file are best understood as a matrix, in the form
shown below. Three columns designate three groups, Owner, Group, and Everyone.
Owner is the person who owns the file (you). Group is designated for any
groups that are set up by your network administrator, and may or may not
apply to your script. Check with your network administrator if you're not
sure. Everyone refers to the world-at-large, like anyone who will use your
script on the Internet.

The three rows of the matrix are the three actions that may be performed
on your file: Read, Write, and Execute. Read means that the file can be
read, but not changed in any way. Write means that data can be written
to the file, and Execute means that the file can be run as a program. Each
is valued in the following way: Read=4, Write=2, Execute=1. The values
for each column are added up, then the three-digit number is used as your
programís permissions on your server.

Here's a typical example:

Owner

Group

Everyone

Read

= 4

|

4

4

4

|

Write

= 2

|

2

|

Execute

= 1

|

1

1

1

Add them up:

|

-----------------

|

7

5

5

Therefore, on your FTP program the matrix should be filled out like
this:

Owner

Group

Everyone

Read

X

X

X

Write

X

Execute

X

X

X

Please note that you do NOT want to assign Write privileges to Group
or Everyone! The only updates to your files should be by your script, and
not by any hacker who happens upon your site.

A Simple Script

Naturally, you'll need a script to upload. Here's a simple Perl script
you can use for testing.

Upload the file using the steps outlined above. Type in the URL
to the script in your browser. It will look something like "http://www.domain.com/cgi-bin/hello.cgi".
If you see Hello Internet World! you're all set. Otherwise,
you'll need to start a little troubleshooting.

First of all, check with your ISP to make sure the following information
is correct:

1. Is perl installed on the server?

2. Do you have CGI privileges? If so, what is the correct subdirectory
or cgi-bin?

3. What is the correct server path for your account?

Also, make sure that you uploaded the file using ASCII mode. Itís easy
to forget, so just reload it if you aren't sure.

Finally, be sure you have set the permissions for the file correctly.

Here are some server errors that you may see.

"403 Forbidden"

If you see this, check the permissions on your script. Sometimes you
may have to also set the permissions of the subdirectory. Check the documentation
on the script to be sure.

"404 File Not Found"

This means that the server can't find your file. You'll need to check
the URL or the server path, depending on how the script is configured.
Remember that some operating systems are case sensitive, so make sure itís
not just a typo. Also, verify that the file is in the correct location.

"500 Server Error"

This error means that your script is producing output that the server
doesn't understand. In other words something in the code is wrong. Most
common errors are leaving out a semicolon at the end of a line or uploading
the script in binary and not ASCII. It could be that there's a typo in
one of your variables.

Additional Information

In some cases, you will need to know if you can use SSI, or Server
Side Includes. This allows the server to execute the script automatically
every time the page is accessed. Generally, you'll need to change the extension
of your .html page to .shtml. However, check with your ISP to be sure.