Netcom CGI Primer

Under Construction

Introduction
Rules & Guidelines
Paths to Common Programs
Useful Perl Modules

Introduction

This document is intended to provide enough information, rules, and guidelines to get your CGI script accepted for installation onto your web site as fast as possible. It assumes a basic working knowledge of CGI programming.

Examples of good and bad scripts and script fragments are provided in Perl, but the concepts explained adapt equally well to other languages such as C or TCL.

The most important thing to remember about the CGI scripts on your site is that they reside outside your document root. This means that their working directory is also outside your document root. Therefore, any files read or written by your script must use pathnames beneath the DOCUMENT_ROOT environment variables.

Rules & Guidelines

The following rules must be observed:

We will accept scripts written in Perl, C and Tcl. Perl is strongly preferred. If you are using C, you must verify that it compiles on at least one Unix implementation. We cannot accept C source code which has been tested only on Microsoft Windows, nor can we accept executable programs - C source must be supplied. You should also be aware that due to extra complexity of checking C programs, approval is likely to take significantly longer than Perl scripts.
If your CGI will read or write data files on your site, those files must be within your document root. Your document root directory is available to your CGI as the environment variable DOCUMENT_ROOT. Here is a well-behaved Perl script fragment:
```
	$filename = "$ENV{'DOCUMENT_ROOT'}/subdir/file.txt";
	open(FP, $filename) or die;
	  # do some work...
	close(FP);
```
However, this script fragment will not be accepted:
```
	# No good - this file is not within your document root
	$filename = "file.txt"; 
	open(FP, $filename) or die;
	  # do some work...
	close(FP);
```
The path to all of your CGI scripts when called from a HTML form (or directly from a Web browser) is /bin/cgi. e.g. if your script is called myscript, you would use a line like the following in your HTML:
```
	<form method="post" action="/bin/cgi/myscript">
```
All external programs must be called via a full pathname. E.g. you should call /usr/lib/sendmail to send a message, not just sendmail. A list of the correct paths on our system for commonly used programs is supplied in the next section.
If your CGI generates HTML output which refers to pages or images within your website, it must use absolute paths to the page or image. For example, suppose you have an image called button.gif in a subdirectory called images/ on your website. This script fragment will produce the correct HTML:
```
	print '<img src="/images/button.gif">';
```
but this fragment is wrong:
```
	# this will lead to a broken image icon!
	print '<img src="images/button.gif">';
```
If you are passing form arguments to external programs, you must check all of the arguments for special shell characters and either escape or remove them. This is a common security hole in CGI scripts. The following are considered to be dangerous characters:
```
	& ; ` ' \ " | * ? ~ < > ^ ( ) [ ] { } $ \r \n
```
(\r and \n are carriage-return and newline, respectively)
Perl scripts must conform to the Perl5 syntax - scripts which use Perl4-only constructs (these are rare) cannot be accepted. The most common problem here is double-quoting the '@' character; this was fine in Perl4, but in Perl5 must be escaped. E.g.:
```
	$address = "someone\@somewhere.com";	# Fine
	$address = "someone@somewhere.com";	# BAD!
```
If you have access to Perl5 on your local machine, you can (and should) check your script with the following command:
```
	perl -c -w scriptname
```
(-c means to check the script for syntax without executing it, and -w means to warn about dubious syntax which may cause subtle errors)

Paths to Common Programs

Perl5 is /usr/local/bin/perl
Sendmail is /usr/lib/sendmail
cp is /bin/cp

If you need to run programs other than the above, please contact submit-cgi@corp.netcom.net.uk to discuss your requirements.

Useful Perl Modules

In addition to the standard Perl5 module library, we've installed some extra modules which you may find useful in your CGI's:

cgi-lib.pl - old & simple CGI parsing routines
CGI.pm - very powerful & complex object-oriented CGI module
CGI-Lite.pm - lightweight, but very useful, object-oriented CGI module
GD.pm - Perl interface to the GD graphics library, allowing GIF images to be generated on-the-fly
GIFgraph.pm - allows graphs to be drawn and output in GIF format

Documentation for the above modules is available from the CPAN (Comprehensive Perl Archive Network).

If you have written a CGI which requires modules other than the modules in the core Perl5 distribution, or in the list above, please contact submit-cgi@corp.netcom.net.uk to discuss your requirements.