CGI scripts
From Blue Lightning Internet
Contents |
Conventions
Throughout this document, the URL "www.yoursite.com" should be replaced with the hostname of your own website, and <cr> indicates a carriage return.
CGI-BIN
Your web hosting account has CGI script facilities as standard. In the root of your FTP account you will see four directories, one of which is called "cgi-bin". This is where you must place your custom CGI scripts, which can either be written in Perl or in normal Bash shell script. Your CGI scripts will then be accessible from:
Any files stored in your cgi-bin directory count towards your quota usage. However, most scripts are extremely small and will therefore make negligible difference.
Please remember to ensure that your scripts have a valid shell header. For Perl scripts use "#!/usr/bin/perl" and for Bash scripts use "#!/bin/bash". You will also more often than not need to include Content-type headers. These must be sent to the browser before any other page content (<cr> denotes carriage return and is not an HTML tag).
Content-type: text/html<cr>
<cr>
Content-type: text/plain<cr> <cr>
You may use any content type header you require, the two examples above are the most common.
Should a CGI script cause a "500 Server Error" when run, the most likely cause is that you have omitted the content type headers. However, this error will appear if the script fails for any other reason too, and the only way to see why it failed is to look in the site's error log. You can view the last 20 lines of the error log by going to:
NOTE: We are unable to provide free support for the development of custom CGI scripts. Additionally if a custom CGI script is found to present a security issue to the server, we will disable it with immediate effect and notify you so you may correct it. We do offer scripting services, but this is a separate chargeable product. Contact us for more details.
CGI-COMMON
cgi-common is a second cgi-bin directory is that is provided to all web hosting accounts that contains a standard set of CGI scripts, designed for customers who do not have expertise in writing CGI scripts of their own. These scripts are accessible from:
The following scripts are available:
errorlog.pl
Usage: /cgi-common/errorlog.pl (no parameters)
Displays the last 20 lines of your website's error log. Useful for determining why a custom CGI script is failing. It may also give hints to broken links on your site as 404 errors are also reported in the error log.
genericform.pl
Usage: /cgi-common/genericform.pl (required parameter = "mailto")
This script is a generic form handler that takes the contents of any form and e-mails it as key=value pairs to the e-mail address provided in the "mailto" parameter. For example:
<form method="post" action="/cgi-common/genericform.pl">
<input type="hidden" name="mailto" value="sales@yoursite.com">
Your name: <input type="text" value="name"> Your e-mail: <input type="text" value="email">
<input type="submit" value="Submit Form"> </form>
This form, when submitted, would submit an e-mail looking something like this:
name=John Smith
email=john@smith.com
You can use any number of form parameters. However, it is not possible to process file upload form fields, the script will simply report some arbitrary information in the case of "file" type input fields. The e-mail you receive will also report the date and time the form was submitted, plus the hostname and/or IP address of the user's connection.
On submitting the form, genericform.pl will return a simple page with the folllowing text:
Your form was submitted successfully.
Return to www.yoursite.com
dump.cgi
Usage: /cgi-common/dump.cgi (no parameters) See example
Displays all CGI environment variables and their values as key=value pairs. Below is a brief explanation of what each environment variable means:
| Variable | Purpose |
|---|---|
| GATEWAY_INTERFACE | CGI version that the server complies with. Example: CGI/1.1 |
| SERVER_NAME / HTTP_HOST | Server's host name. Example: www.yoursite.com |
| SERVER_ADDR | Server's numeric IP address. Example: 212.21.97.241 |
| SERVER_PORT | Port on the server that received the HTTP request. Example: 80 (most servers). |
| SERVER_PROTOCOL | Name and version of the protocol being used by the server to process requests. Example: HTTP/1.0. |
| SERVER_SOFTWARE | Name (and, normally, version) of the server software being run. |
| DOCUMENT_ROOT | The full path on the server's hard disk to your "docs" directory |
| AUTH_TYPE | Authentication scheme used by the server
(NULL if no authentication is present). Example: Basic or Digest. |
| CONTENT_LENGTH | Number of bytes passed to Standard Input (STDIN) as content from a POST request. Example: 9. |
| CONTENT_TYPE | Type of data being sent to the server. Example: text/plain. |
| PATH_INFO | Additional relative path information
passed to the server after the script name, but before any query data. Example: /scripts/forms. |
| PATH_TRANSLATED | Same information as PATH_INFO, but with
virtual paths translated into absolute directory information. Example: /www/htdocs/somebody/forms. |
| QUERY_STRING | Data passed as part of the URL,
comprised of anything after the ? in the URL. Example: part1=hi&part2=there. |
| REMOTE_HOST | End user's hostname. Example: modem1.dial.myisp.co.uk |
| REMOTE_ADDR | End user's IP address or server name. Example: 207.213.172.210 |
| REMOTE_USER | User name, if authorization was used. Example: john |
| REMOTE_PORT | The port on the end user's computer which the server is connected to |
| REQUEST_METHOD | Specifies whether data for the HTTP request was sent as part of the URL (GET) or directly to STDIN (POST). |
| SCRIPT_NAME / SCRIPT_FILENAME | Name of the CGI script being run. Example: log.cgi. |
| ACCEPT | Lists what kind of response schemes are accepted by this request |
| HTTP_REFERER | Identifies the URL of the document that gave the link to the current document |
| USER_AGENT | Identifies the client software, normally including version information |
| ACCEPT_ENCODING | Lists what types of encoding schemes are supported by the client |
| ACCEPT_LANGUAGE | Identifies the ISO code for the language that the client is looking to receive |
| AUTHORIZATION | Identifies verified users |
| FROM | Lists the client's e-mail address. This
very very rarely used these days and its availability should certainly not be assumed. |
| PRAGMA | Sets up server directives or proxies for future use |
| HTTP_COOKIE | Displays the names and values of any valid cookies available to your website |
NOTE: Not all CGI environment variables will be displayed by dump.cgi.
