CGI Documentation


The CGI scripts available are:

cgiwrap - CGI debugging and security filter

cgiwrap and cgiwrapd:

cgiwrap is a "script wrapper" that lets your own USER-CREATED scripts execute under your own userid instead of user nobody. As an added benefit, cgiwrap can also make the standard error output of your scripts visible through your Web browser.

To use cgiwrap with a script in your cgi-bin directory, you need to use a different URL. If the URL to your script is presently:

http://www.domain.com/cgi-bin/program.cgi
You need to rewrite it as follows in order to use cgiwrap:
http://www.domain.com/cgi-sys/cgiwrap/username/program.cgi
These URLs run the non-debugging version of cgiwrap; if you want to use the debugging features, change the cgiwrap to cgiwrapd

Cgiwrap looks in your cgi-bin directory, or subdirectories thereof, for scripts. It will not look anywhere else, for security reasons. Also, the script to be executed must be owned by your userid and default group (normally users).  For more info on cgiwrap refer here.

php-cgiwrap:

php-cgiwrap is a "script wrapper" that lets your scripts execute under your own userid and group instead of user nobody and group www. It works in the same fashion as cgiwrap, but handles paths in such a way that it can be used to run PHP pages under your own userid.  This allows you to use chmod 700 to lock out other users on the server from viewing the source code.

In order to prepare to use PHP with php-cgiwrap, you must first copy php.cgi to your own cgi-bin directory:

cp /usr/www/cgi-bin/php3.cgi ~/public_html/cgi-bin
chmod 755 ~/public_html/cgi-bin/php3.cgi

(For PHP/FI 2, copy the file php.cgi from the same directory, instead.)
You must then add the following lines to your .htaccess file:

           Action application/x-pair-sphp3 /cgi-sys/php-cgiwrap/username/php3.cgi
           AddType application/x-pair-sphp3 .php3

           username should be replaced with your account username, of course. Once this is
           done, all .php3 files are run under your own user ID. If you want to use a different file
           extension, replace .php3 on the second line with whatever you prefer.

           If you are using PHP/FI 2, no .htaccess additions are required -- you can simply use
           URLs of the form:

           http://www.domain.com/cgi-sys/php-cgiwrap/username/php.cgi/filename.phtml

jumpbox - pull down website navigation
(from cgiscripts.net)

Jumpbox is a script which implements drop-down text menu boxes which can be used as navigation aids instead of standard links. The easiest method of implementation is to include the URLs of the other pages in your form.

The HTML code below show an example of that simple format:

<form method=post action="/cgi-sys/jumpbox">
Select:
<select name="goto">
<option value="http://www.webcs.com/">WEBster Computing Services
<option value="http://disney.com/">Disney
<option value="http://yahoo.com/">Yahoo search engine
</select>
<input type=submit value="Go!"> </form>
Below is the fully-functional menu generated by the code:
Select:
In this method, the form's method should be "POST" and it's action "/cgi-sys/jumpbox". You then need to have a select box named "goto" -- each option should have as its value the URL to redirect to.
countdown.pl - count down to a future date
(from Matt's Script Archive)

This is a fairly silly script that accepts a future date and time as its parameters, then returns a page indicating the amount of time remaining until then. Its parameter list is six numeric values separated by commas: year, month, day, hour, minute, and second. The year must be fully specified (eg, 1999), and the month starts at 1 for January. You may omit any value by substituting "XX"; the program will then disregard that time unit when generating the results.

Use this script as a link in your HTML source:

<A HREF="/cgi-sys/countdown.pl?1999,3,21,2,15,20">
Countdown Link</A>
This example links to a countdown page for March 21st, 1999, at 30 seconds past 2:15am.

This example links to a time in the current year:

<A HREF="/cgi-sys/countdown.pl?XX,11,15,0,0,0">
This Year</A>
If you wish, this program can be copied to your own cgi-bin directory from /usr/www/cgi-bin/.
counter 4.0 - text counter
(from the WebTools collection)

This is an intelligent text-only counter script, normally used with Server Side Includes (.shtml extension). To use it, place the following in your SSI-enabled HTML source:

<!--#exec cgi="/cgi-sys/counter" -->
The server will parse this command, execute the counter script, and insert its results in place of the command, as plain text.

counter does not require any parameters in order to determine which counter is being referenced; it uses the current document name to determine this.

form.cgi - form delivery by e-mail
This script delivers the contents of a POSTed form to a local e-mail address. To use this script with your forms, three hidden fields are required, and you must use the POST method. For example:
<FORM METHOD="POST" ACTION="/cgi-sys/form.cgi">

<INPUT TYPE="hidden" NAME="TO" VALUE="username">
<INPUT TYPE="hidden" NAME="OK" VALUE="new-URL">
<INPUT TYPE="hidden" NAME="KW" VALUE="Keywords">
...where username is the local user who should receive the form contents, new-URL is the absolute URL to which the visitor should be sent after a successful form delivery, and Keywords is any phrase that should appear in the Subject: line of the mail being delivered.

The body of the e-mail sent will contain all defined fields in the form, reported in sorted order. For example:

01_NAME:: Joe Blow
02_COMPANY:: Yadda Enterprises
03_ADDRESS:: 45 Somewhere St
To receive the fields in a preferred order, we recommend a naming scheme with numeric prefixes, as shown above.

If new-URL is missing, a generic "Success" message will be shown to the visitor. The Keywords field is also optional.

Please note that the username is always relative to @pair.com, so you will want to use your account login name. Also, the names of the hidden fields must be exactly correct, and in uppercase.

formmail.pl - form delivery by e-mail
(from Matt's Script Archive)

This script, widely available at other sites, has more options than the form.cgi script. it is highly recommend by our staff for ease of use. It accepts forms via either GET or POST methods, and allows e-mail to addresses outside our server's domain.

<FORM METHOD="POST" ACTION="/cgi-sys/formmail.pl">

The following fields can be defined for formmail.pl; only the recipient field is required:

recipient (required)
This field specifies the destination e-mail address for the form contents. Example:
<INPUT TYPE="hidden" NAME="recipient" VALUE="address@domain.com">

See the note at the bottom of this section if you are using an

email address here that is not hosted on your server.
subject
This field specifies the Subject line of the outgoing e-mail. If not given, the default Subject is "WWW Form Submission". Example:
<INPUT TYPE="hidden" NAME="subject" VALUE="Some Subject Line">
You can also allow the user to specify the Subject field:
<INPUT TYPE="text" NAME="subject">
email
This field specifies the return e-mail address of the user submitting the form. If supplied, this should be a field filled in by the user. The e-mail will be generated so that your mailer's reply function should go to this address; if not supplied, the default is nobody@pair.com. Example:
<INPUT TYPE="text" NAME="email">
realname
This field specifies the real name of the user submitting the form. If supplied, this should be a field filled in by the user. The e-mail will be generated with this name in the headers. Example:
<INPUT TYPE="text" NAME="realname">
redirect
This field specifies the URL to which the user should be automatically redirected after successful delivery of the form. If this is not specified, a default response will be generated by the script. Example:
<INPUT TYPE="hidden" NAME="redirect" VALUE="http://domain.com/whatever.html">
required
This field allows you to specify that certain fields in the form are "required"; that is, that they may not be empty when the form is submitted. If any of the specified fields are empty, the user will receive a warning, and the form will not be submitted. Example:
<INPUT TYPE="hidden" NAME="required" VALUE="email,subject">
env_report
This field specifies a list of environment variables that should be submitted along with the form contents. This is useful for recording, for example, the IP address of the user submitting the form. Useful environment variables to record include:
  • REMOTE_ADDR - IP address of the user's host
  • HTTP_USER_AGENT - name and version of the user's browser
script.

Example:

<INPUT TYPE="hidden" NAME="env_report" VALUE="REMOTE_HOST,HTTP_USER_AGENT">
Note: case is important for environment variables.
sort
This field specifies how the fields submitted from the form should be sorted in the outgoing e-mail message. By default, the fields are not in any particular sort order (results are dependent on the user's browser). You may specify "alphabetic" for straight alphabetic sorting (same as form.cgi, described above), or you may specify the exact order with "order:". Examples:
<INPUT TYPE="hidden" NAME="sort" VALUE="alphabetic">
<INPUT TYPE="hidden" NAME="sort" VALUE="order:name,email,phone">
print_config
This field specifies that the formmail.pl control fields, normally removed from the body of the outgoing message, be included for completeness. Example:
<INPUT TYPE="hidden" NAME="print_config" VALUE="email,subject">
title
This field specifies the title for the default response page that is generated by the script in absence of a redirect field. The default is "Thank You". Example:
<INPUT TYPE="hidden" NAME="title" VALUE="Form Results">
return_link_url
This field specifies a URL that will appear on the default response page that is generated by the script in absence of a redirect field. This URL can be used to allow users to return to, for example, your home page. Example:
<INPUT TYPE="hidden" NAME="return_link_url" VALUE="http://domain.com/">
return_link_title
This field specifies the text that will be used inside the link generated when return_link_url is specified. Example:
<INPUT TYPE="hidden" NAME="return_link_title" VALUE="Return to Home Page">
background
This field specifies the URL of a background image that will be used on the default response page that is generated by the script in absence of a redirect field. Example:
<INPUT TYPE="hidden" NAME="background" VALUE="http://domain.com/img/bkgr.gif">
bgcolor
This field specifies the background color that will be used on the default response page that is generated by the script in absence of a redirect field. Example (pure white):
<INPUT TYPE="hidden" NAME="bgcolor" VALUE="#FFFFFF">
text_color
This field specifies the text color that will be used on the default response page that is generated by the script in absence of a redirect field. Example (pure black):
<INPUT TYPE="hidden" NAME="text_color" VALUE="#000000">
link_color
This field specifies the unvisited link color that will be used on the default response page that is generated by the script in absence of a redirect field. Example (pure red):
<INPUT TYPE="hidden" NAME="link_color" VALUE="#FF0000">
vlink_color
This field specifies the visited link color that will be used on the default response page that is generated by the script in absence of a redirect field. Example (pure blue):
<INPUT TYPE="hidden" NAME="vlink_color" VALUE="#0000FF">
alink_color
This field specifies the active link color that will be used on the default response page that is generated by the script in absence of a redirect field. Example (pure green):
<INPUT TYPE="hidden" NAME="alink_color" VALUE="#00FF00">
Sending to addresses off of the server: If you put an address in the recipient field that is not hosting on your server (ie if your domain is mysite.com and you want to send to myaddress@aol.com) then you need to specify valid recipients in a file called .formmail in your home directory /usr/home/username. Using a text editor put each valid email recipient one to a line and upload it to your home directory.  This will tell the server that a recipient is valid.  This is a security check to make sure your account and script is not used by a spammer or an unauthorized user.
Count.cgi - fancy image odometer-style counter
This is a flashy but reliable counter with all sorts of options.

Starter and Starterplus accounts are allowed to use ONE counter per account.  Other accounts may use as many as they wish.  Use this command in your HTML wherever you want to insert a counter in that specific page:

<IMG SRC="/cgi-sys/Count.cgi?df=username-index.html">
The filename for df= must be your username, a dash, and a keyword or filename that will let you keep track of which counter you're using. Slashes and tildes are not allowed. Count.cgi keeps one counter in each file. Please note that your filename can be anything. Each filename you use will produce a different counter. Thus, you are able to create as many different counters with different numbers as you wish.

There is an extensive list of options available with Count.cgi; they are documented fully on its home page.

Presetting the number:
You can specify the starting value of any counter by adding the parameter st=. For example:

<IMG SRC="/cgi-sys/Count.cgi?df=sigma-index.html&st=1000">
This example creates the counter for sigma-index.html, with an initial value of 1000. You can only do this for the first use of a counter. Once you set the initial value and run it on the browser, remove the st= setting or your counter will stick itself at the number you initially fixed it to or break altogether.

Hiding your counter:
In almost all instances it is preferable to hide your counters from users because your stats are basically only your business.  You can do this by setting the image height and width of the counter to 1 like follows:

<IMG height=1 width=1 SRC="/cgi-sys/Count.cgi?df=sigma-index.html">
To view a hidden counter at any time just enter its full name on the web:
http://www.yourdomain.com/cgi-sys/Count.cgi?df=sigma-index.html
test.cgi - environment and UID/GID display (for debugging)
This script simply returns the contents of all environment variables defined when CGI is run, along with the real and effective UIDs of the CGI process. This is useful for a quick reference of environment variables and their settings, as well as to experiment with cgiwrap or password protection. You can copy the test.cgi program from /usr/www/cgi-bin/ to wherever you would like it to run.