HELPME.TXT

by Joe DePasquale

Latest revison: June 24, 1998
E-Mail: crypt@getcruising.com
Website: http://www.getcruising.com

General Instructions for Installing and Configuring
"JOE'S CGI SCRIPTS FROM THE CRYPT" Plus Troubleshooting Tips.

Specific installation instructions for each script can be found
in the "how2...." file included in each zip archive:
(how2ban.txt, how2bbm.txt, how2hit.txt, how2link.txt, how2mail.txt)

===========================================================================

[1] GENERAL REQUIREMENTS

You will hopefully already know how to upload, configure, and run
Perl scripts on your web server, because this is not by any means a
complete introduction to CGI and Perl.

These scripts are written in Perl v5.002 - v5.004 and should be
compatible with any UNIX web server running Perl. The standard of
security assumes users from the web will access your scripts as group
'nobody' and username 'nobody'. Some servers will have different
security, but the 'chmod' permissions suggested in the scripts are
general enough to permit running under almost any restrictions.
If you are unfamiliar with permissions, see the section herein.

[2] YOUR CGI DIRECTORY

You need to have access to a server-defined cgi-directory,
usually referred to as 'cgi-bin'. There are restrictions on
placing .cgi files outside the cgi-directory and conversely, you
might be restricted from placing non-.cgi (or non-.pl) files inside
the cgi-directory or in subdirectories of the cgi-directory.

You will need to know how to write a URL to access a script from
the web. Frequently, the cgi-directory has an alias name. For
example, on my server the actual directory is named 'cgi-shl',
but the alias is 'cgi-bin' when written in a URL.

Your website provider should have this information posted. If
not, find out because you will need it frequently when setting up
CGI scripts.

[3] FINDING PERL, MAIL and DATE COMMANDS

Read the 'how2....' document and follow the instructions for
setting up the script and associated files.

The first line of a .cgi script is the command line, which must
point to the location of the Perl executable program on your
web server. If you don't know where it is, go to your Unix shell
and type 'which perl' (or 'whereis perl') .. the response will
be the command you should use, frequently '/usr/local/bin/perl'.
In that case the first line of the script must be:

#!/usr/local/bin/perl

In most scripts you will also need to set paths to your sendmail
and date programs. You can find the path to any program by
typing 'which program-name' (or 'whereis program-name') at the
Unix prompt, ie 'which sendmail' and 'which date'. If you
don't find sendmail this way, look for it in '/usr/sbin' or
'/usr/local/sbin'. If you still don't find it, type 'which mail'
(or 'whereis mail') and use the mail program instead.

If the path to Perl is NOT '/usr/local/bin/perl', change the top
line of the script. If the variable declarations include a call
to '/bin/date' or '/bin/mail', you must substitute the correct
path to your server's date or mail command.

[4] UPLOADING TO YOUR WEB SPACE

All filenames are lower-case in SCRIPTS FROM THE CRYPT! If your
unzipping program (ie WINZIP) extracts files in upper-case, go to
the configuration settings and look for a 'lower-case' option.

Change all sample paths in the 'CONFIGURE THE SCRIPT' section of
the '.cgi' script(s) to the path corresponding to your web space.
All the variables that you need to modify will be in the top portion
of the script before the executable code. For example, if this
line appears:

$banmatDir = '/usr/home/you/htdocs/banmat';

and the path to your web documents directory is '/home/bozo/',
then change the line to:

$banmatDir = '/home/bozo/banmat';

and create a subdirectory named 'banmat'. Refer to the 'how2....'
document for the correct locations and instructions on creating the
new directories.

Upload the files to your web server. Use the correct file
transfer mode for each file. As a guide, a BINARY file looks
like a mess of unreadable characters when opened in a text editor,
whereas an ASCII file has all readable characters. The only
BINARY files in these scripts are the .gif or .jpg files.
Everything else is ASCII including .cgi, .pl, .html, .txt,
.dat, .cnt, .pwd etc. etc. Hope you get the idea, but if you
butcher a file, just upload it again correctly.

[5] RENAMING HTML FILES

You may have some files to be uploaded that end with the'.htm'
extension. They must be renamed as '.html' before using them
on the web. If your operating system allows it, you can rename
them before uploading them, otherwise rename them using
your FTP program or at the Unix prompt 'mv *.htm *.html'

[6] CHMOD (UNIX PERMISSIONS)

If you grew up on MS-DOS or WINDOWS, then the most alien property
of Unix is 'permissions'. That includes proper use of the 'chmod'
command on files and directories. Incorrect permissions is the most
frequent reason for scripts failing to run. Further, the diagnostics
from Perl usually won't give you a clue if you have a permissions error.

Your server has restrictions on which permissions can be changed
by you so it's important to scan your directories and files
after you think you have set everything correctly. You might
find one of your settings wasn't accepted.

Use the Unix command 'ls -alF' to see the most detailed directory
listing. This is what a Unix directory called 'myweb' might look like..

/home/myweb> ls -alF

total 192
drwxr-xr-x 5 usergroup users512 Nov 28 12:16 .
drwx------ 5 usergroup users45568 Feb 14 17:31 ..
drwxr-xr-x 7 usergroup users 2650 Nov 14 14:21 banmat/
drwxrwxrwx 6 usergroup users 2650 Nov 14 14:21 bbmat/
drwxr-xr-x 5 usergroup users512 Oct 27 19:58 cgi-bin/
drwxr-xr-x 1 usergroup users807 Nov 14 14:02 linkmat/
-rw-r--r-- 1 usergroup users807 Nov 14 14:02 aboutme.html
-rw-r--r-- 1 usergroup users807 Nov 14 14:02 index.html
-rw-r--r-- 1 usergroup users807 Nov 14 14:02 taxidermy.html

Directory names end with slash /
Executable programs/scripts end with asterisk * (not shown above)

The groups of 10 characters in the left column is the permission
list: d=directory, r=readable, w=writable, x=executable, -=not.

If position 1 is 'd', the line describes a directory, else it's
a file. Next are 3 groups of 3 characters each. Positions 2/3/4
are the read/write/execute permissions for the owner (usually you).
Likewise positions 5/6/7 are for a group (usually not used), and
positions 8/9/10 are for users (usually all those creeps on the web).

'Usually' means it's up to YOUR lonesome self to find out how the
owner, group and users are defined by your web provider.

The line ending with one dot is the current directory. You can set
permission of the current directory using 'chmod 755 .'

The line ending with two dots is the next higher directory.
Set its permission using 'chmod 755 ..'

These are the general rules for permissions, but be guided by the
specific chmod instructions for each file in the 'how2....'
document for each script.

Command Result Used For

For Files:
-----------------------------------------------------------------
chmod 644 -rw-r--r-- Files that will be read but never
changed by a script. Examples are .gif,
.pl and .html

chmod 666 -rw-rw-rw- Files that must be writeable (changable)
by the script. Most common types are .dat,
.cnt and .pwd files

chmod 755 -rwxr-xr-x Executable files like .cgi

For Directories:
-----------------------------------------------------------------
chmod 755 drwxr-xr-x Directories must have the 'x' permission
set to allow access to their files. The
'r' permission allows commands like 'ls'
to read (search) in the directory.

chmod 777 drwxrwxrwx The 'world-writeable' permission is
used when a directory must allow
scripts to create new files by writing
in the directory.

Notice the distinction between permission to write to a file
and permission to write to a directory.

You can also set directory or file permissions by entering a
full or relative path and wildcards (*) in the chmod command:

chmod 644 /home/myweb/*.html
chmod 644 ./index.html(same as 'chmod 644 index.html')
chmod 755 ../somefile.html
chmod 755 /cgi-bin/*.cgi

[7] NAVIGATING IN UNIX

It can be confusing to be instructed to 'go up one directory' or
to the 'next lower directory'. Think of the entire directory structure
as a tree. The narrow part is at the top (forget that it's called
the 'root'!). Moving 'up' or 'higher' means toward the top of the
tree, where there are fewer and fewer branches. Moving 'down' or
'lower' means toward the bottom where the tree is fuller with
many branches (subdirectories).

'cd ..' - moves up the tree one level.
'cd ../../cgi-bin'- moves up 2 levels and changes to the
'cgi-bin' directory.

[8] DE-BUGGING

In order to properly install a script (without losing your sanity)
you need a Unix shell account on your web server. Simple FTP
access will not be much help when you need to diagnose errors
because you'll have no clue what went wrong.

When all the files are in place and the permissions are set
correctly, you can run the script in your Unix shell,
by entering:

perl -w scriptname.cgi

You may see various warnings, but if the last line doesn't say ..

"Execution of 'scriptname.cgi' halted due to compilation errors."

then you're OK. It's very helpful to have your script loaded in
a text editor which displays line numbers, since Perl diagnostics
will refer by line number to where it finds errors. Don't panic
if you get several screens full of error messages. Usually the
first error is the cause of all or most of the following errors.
Just correct the first error and rerun the script as before.
Then repeat .. and repeat .. and repeat .. until you no longer
get the 'Execution halted' message.


===========================================================================

TROUBLESHOOTING TIPS:

[1] If you get the error message "File not found" when the script is run,
and you know the file is where it is supposed to be, then you
will probably have to do this:

TELNET to your CGI-BIN directory. Run the Unix word processor program.
On my server it is "pico". Yours might be different. Open the .cgi
file and type a character or two, then delete them and save the file.

The server should now recognize the file. You might have to do the same
with other files, but in my experience it only happens with scripts.

[2] One of the common mistakes in setting up a script is designating
incorrect file locations. If a script cannot find the files it needs,
the script might run, but the results may be unexpected.

When editing the default file locations in the .cgi (or .pl) files,
notice there are two types of paths: Web URL's and Unix server paths.
In my scripts, variable names which end with 'Url' require a Web URL.
Names ending with 'Dir' require a Unix server paths.

Examples:

$myDir = "/home/you/html/path/to/my";
$myUrl = "http://your.server.com/you/path/to/cgi-bin/my";
$mypageUrl = "http://your.server.com/you/path/to/my/mypage.html";

[3] On many web servers, there are security restrictions on the CGI
directory which prevent placing non-script files there or in its
sub-directories. If you suspect this is true, create the script-
required subdirectories anywhere else where the script will be able
to access them. Simply point the script to the correct path(s)
when you edit the variable declaration section of the script.

[4] When files are edited in a DOS text editor, sometimes an invisible
character is appended to a line. This may cause Unix to fail when
reading a text file (.cgi, .dat, .html etc.). Uploading a file as
BINARY (rather than ASCII) can cause this.

If you suspect this has happened, either upload a new copy of the
file as ASCII or examine the file and delete the extra characters by
backspacing until the cursor is on the blank space following the last
readable character on a line. Press 'ENTER' just once. Do the same
for each line!

Every line in a Unix file must end with the linefeed character, which
is ASC 10. In a binary editor, it looks like a solid square with a
circle cut out of it.

[5] The instructions for some scripts call for a "Server-Side-Include"
to be added to your HTML page(s). Some servers require that these
page(s) must be named with an '.shtml' or '.shtm' extension (instead
of '.html' or '.htm') otherwise the server ignores the script.

[6] I don't recommend you alter anything in a script unless you are
sure of what you are doing. Nevertheless, if you find you absolutely
must change some of the HTML code in a 'print' statement here are some
precautions to prevent you from taking down the Internet.

Note these basic rules:
1. Text following the 'print' command must be enclosed in quotes " "
2. When quotes appear inside quotes they must be \"escaped\" by
preceeding the inner quote characters with a backslash.
3. Every Perl statement must end with a semicolon ;

Example:
print "There are some things man was not meant to know.<br>\n";

If you want this BOLD and you want to add a font color, change to:
print "<b>There are some things man <font color=\"#FF0000\">was not meant to know</font>.</b><br>\n";

[7] Starting with new scripts or revisions dated from March 13, 1997,
these are the naming conventions of my script variables. This may
be of main interest to programmers, but this might also help
everyone to deal with the configuration section of each script:

Type: Format:

Scalar array First letter $days[0], @badwords
is lower-case

Associative First letter $Form{'foo'}, %Question
array (hash) is upper-case

Unix directory Ends with 'Dir' $mailmatDir, $flkDir
path

Internet URL Ends with 'Url' $formUrl, $scriptUrl

Filenames All letters $HITLOG1, $MAINPAGE
are upper-case

HOME|PLEASE VISIT GETCRUISING'S SPONSOR: