|
Custom CGI programs can be an effective way to tailor the experience
of your site to the needs of your clients. If you have some knowledge
of Perl scripting, then you may want to consider implementing your
own Perl scripts. All of our Web 25 accounts or higher come with custom
CGI enabled. This document is meant to be a general outline of our
custom CGI access. It will help you in implementing your own Perl CGI
scripts on our servers.
Introduction to Perl
According to Larry Wall, the father of this programming language,
"Perl (Practical Extraction and Reporting Language) is an interpreted
language optimized for scanning arbitrary text files, extracting
information from those text files, and printing reports based on
that information". Perl is a powerful programming language that has
grown explosively in popularity since its initial debut in 1987.
Since then, it has become the de facto standard for CGI programming,
and has been described as the duct tape of the World Wide Web. For
more background information on Perl, please consult the Resource
Section (Section 6) of this document
Server Variables
In order to write your own Perl scripts, you need to know certain
things about the configuration of our web server. Please find all
the essential variables here below:
Perl Version:
5.005_03
Path to Perl:
/usr/local/bin/perl
The first line(the shebang line) of you script should be:
#!/usr/local/bin/perl
Absolute path to your home directory:
/www/home/domain_name.com/htdocs
Absolute path to your cgi-bin:
/www/home/domain_name.com/cgi-bin
Path to sendmail:
/lib/sendmail
Demonstration Script
Please find here below a sample CGI script that you can use to
get started. Just copy the lines between "Start Script" and
"End Script" and save them as a text file with the name "samplecgi.pl".
Then, using your FTP client, upload the file into your cgi-bin
directory and set the execute permissions for this file. Here's how,
if you use WS-FTP (http://www.allstream.com/customercare/business/internet/wsftp.permission.html)
Then, call the script in your browser. The script can be accessed with
the following URL: http://www.domain_name.com/cgi-bin/samplecgi.pl
where you have to replace "domain_name.com" with your domain name.
----------------------- Start Script -----------------------
use CGI qw(:cgi-lib);
$|=1;
my( $time ) = scalar( localtime( time ));
$contenthead = "Content-type: text/html\n\n";
print $contenthead;
print "";
print "<html>\n";
print "<head>\n";
print "<title>Hello World!</title>\n";
print "</head>\n";
print "<body bgcolour=\"#FFFFFF\">\n";
print "<h1 align="center">Hello World </h1>";
print "<p>The current date and time is $time.<p>\n";
print "<p>We are running on an $ENV{'SERVER_SOFTWARE'} server, ";
print "you are coming from the host $ENV{'REMOTE_HOST'} with the ";
print "IP address $ENV{'REMOTE_ADDR'}</p>\n";
print "<p> This CGI is working fine.</p>";
print "</body>\n";
print "</html>\n";
----------------------- End Script -----------------------
Perl Modules
Perl modules contain pre-written Perl code that can help you write
your scripts in a lot less time. A module is a freely available Perl 5
utility that you can download and use with your scripts. Most modules
are single Perl files with the extension ".pm". For information on
existing modules and where to download them, CPAN is the authoritative
site to consult. (http://www.perl.com/CPAN-local/CPAN.html )
In the case where you want to use any Perl modules or libraries, we
suggest you create a directory (for example "lib") in your cgi-bin
and place any modules or libraries locally in this directory. This
is also called a local installation. You can then refer to these
modules with the following syntax,
#!/usr/local/bin/perl
use lib '/www/home/domain_name.com/cgi-bin/lib';
use ModuleName;
where "domain_name.com" would be your domain name and "ModuleName"
would be the name of the module you want to use.
Please note that for security reasons we do not install any new
modules server wide on our systems. Such "root" installations
would compromise the security of our servers.
Troubleshooting your Perl script
Rarely will scripts run the first time without error. This section
intends to give you some guidance towards what to do when your script
returns an error message.
First of all you should make sure that your account is set up correctly
for custom CGI. When we create your account, we place a script named
"test.cgi" in your cgi-bin. You can try to access it by calling it in your browser.
You just have to go to http://www.domain_name.com/cgi-bin/test.cgi,
where you have to replace "domain_name.com" with your domain name.
As an alternative method, you can also copy our example script in order
to see if your can get it to run. Please see section 3 of this document.
Once you know that your cgi-bin is functioning correctly, you can focus
on "debugging" your script. Here below, please find listed some of the
most common error messages and their possible causes:
"404 File Not Found" Error
As the error message says, the web server was not able to find the file
that you specified in the URL. You should verify the following:
- Have you subscribed to a Web 25 account or higher that comes with
custom CGI scripting ? Only Web 25 accounts and higher come with custom
CGI enabled.
- Have you placed your script in the cgi-bin directory, and have you
specified the right file name in the URL?
ATTENTION: URLs are case sensitive:
http://www.domain_name.com/cgi-bin/test.cgi is not the same as
http://www.domain_name.com/cgi-bin/TEST.cgi
"403 Forbidden" Errors
A 403 Forbidden error occurs when the web server finds itself with insufficient
permissions to run your script. Generally speaking, you should verify two things:
- Verify that the permissions on the cgi-bin directory are the following: 751
or read write execute by owner, read execute by user and execute by everyone.
Here's how, if you use WS-FTP (http://www.allstream.com/customercare/business/internet/wsftp.permission.html )
or CuteFTP (http://www.allstream.com/customercare/business/internet/cuteftp.permission.html ) or
Fetch (http://www.allstream.com/customercare/business/internet/fetch.permission.html ).
- Verify that you haven't implemented an "htaccess" that prohibits you from
accessing the cgi-bin. For more information on "htaccess", please consult our
document "How to password protect a directory".
(http://www.allstream.com/bin/customercare/business/internet/htaccess.help.html)
"500 Internal Server" Error
The dreaded "500 Internal Server" error is by far the most common, not to mention
useless, error message you'll see while debugging your scripts. Any little script
problem can cause it. So you need to use a systematic approach in order to get
your script working.
First and foremost, you should always take the time to verify the following:
If your script still returns an "Error 500" after all these verifications, then
the problem resides most likely within your Perl code and you may want to revise
it. Any small coding mistake, like a missing semicolon for example, can cause an
"Error 500".
In order to obtain a more meaningful error message than just "Error 500", you
can save standard error messages, that you cannot see in your browser, into a file.
This can be done by adding the following lines to your Perl script directly under
your shebang ( first line of your Perl script ) line.
#!/usr/local/bin/perl
BEGIN {
open (STDERR, ">/www/home/doamin_name.com/htdocs/error.txt");
}
You will have to replace "domain_name.com" with your domain name. After running
your script, you can look up the error by going to the following URL:
http://www.domain_name.com/error.txt
Again, please replace domain_name.com with your domain name.
This error.txt file should provide you with a more detailed description of the
problem and should give you some guidance as to where the problem resides in your script.
More Resources
If you have more questions about Allstream's custom CGI access, you may want to
consult our CGI FAQ (http://www.allstream.com/customercare/business/internet/cgi.faq.html&t=Misc ).
Furthermore, please find below some links to sites that provide helpful resources for
implementing your own Perl CGI scripts.
Tutorials
An Introduction to The Common Gateway Interface
http://www.utoronto.ca/webdocs/CGI/cgi1.html
Picking Up Perl (a Perl tutorial)
http://www.ebb.org/PickingUpPerl/
Perl
http://www.perl.org/
http://www.perldoc.com/
http://www.perl.com/pub
Prewritten Perl CGI scripts
Matt's Script Archive
http://www.worldwidemart.com/scripts/
The CGI Resource Index
http://cgi-resources.com/
Dave Central's CGI Library
http://davecentral.com/cgilib.html
|
![[Allstream]](/images/logos/company_logo1.gif "Allstream"){kind=logo}
![[Search]](/images/nav/tlbx_go.gif "search")
