CGI Reference
Overview
The server executes a CGI script by forking a child process which executes the CGI binary. Before creating the child process, the parent process sets up communication channels between the web server and CGI process. The CGI script reads the input provided by the web server, generates the document to be sent to the client, sends it back to the web server and exits. The web server processes the response, for example adding extra header lines and encrypting the data for transfer over an SSL session, and then sends the result to the client.![]()
Input
The CGI script gets input from two sources, the environment and optionally from standard input for POST requests.ENVIRONMENT
The following variables will be set in the environment:
PATH This is set to the same value as the PATH variable in the environment the web server was started in.
Example: /usr/local/bin:/usr/bin:/binSERVER_SOFTWARE The name of the web server software that executed the CGI script.
Example: Zeus/3.0GATEWAY_INTERFACE The version of the CGI specification that the web server supports. Zeus Server supports the latest CGI/1.1 format.
Value: CGI/1.1SERVER_PROTOCOL The version of the HTTP protocol that the web server supports. Zeus Server supports the latest HTTP/1.1 specification. CGI scripts run by the Zeus Server can also generate responses for newer versions of the HTTP specification.
Value: HTTP/1.1AUTH_TYPE The protocol the web server uses for client authentication.
Value: Basic.SCRIPT_FILENAME The absolute filename of the CGI script being run.
Example: /usr/local/zeus/cgi/counter.cgiSERVER_NAME The DNS name of the Virtual Server the client sent this request to.
Example: www.zeus.co.uk
If the Virtual Server does not have a valid DNS address, it will be a textual IP-address.
Example: 10.0.0.5).SERVER_PORT The port number of the Virtual Server that the client sent this request to.
Example: 80REQUEST_METHOD The HTTP method that client used for this request.
Example: GET or POSTPATH_INFO The extra path information associated with this request. For example, if the CGI script being executed has a URL of /cgi-bin/counter.cgi and the client makes a request for /cgi-bin/counter.cgi/sales/index.html, this environment variable will be set to /sales/index.html. PATH_TRANSLATED The extra path information associated with this request translated into an absolute filename. For example if the CGI script being executed has a URL of /cgi-bin/counter.cgi and the client makes a request of /cgi-bin/counter.cgi/sales/index.html and this Virtual Server has a document root of /disk2/docs, this environment variable will be set to /disk2/docs/sales/index.html. SCRIPT_NAME The URL the client requested to execute this script.
Example: /cgi-bin/counter.cgiQUERY_STRING Query information sent as part of the URL for this request. This is information supplied after the '?' in a URL. This information will be encoded by the client's browser in the usual fashion.
Example: open+id+32REMOTE_HOST The DNS name (or textual IP-address) of the client.
Example: olympus.zeus.co.ukREMOTE_USER If authentication information is issued by the client in a request, this is set to the user name supplied. Usually this is sent after a "401 Unauthorized" response, although clients may preempt this challenge in future requests. REMOTE_ADDR The textual IP-address of the client.
Example: 192.34.98.1CONTENT_LENGTH The amount of data available on standard input. For GET requests, this is always zero.
Example: 382HTTP_* Any request information sent by the client that does not fit into one of the above variables is added to the environment for the CGI to access. The client request line is converted to upper-case, hyphens "-" are converted into underscores "_" and then it is prefixed with HTTP_ before being inserted into the environment.
Example: HTTP_ACCEPT_LANGUAGE=enSSI ENVIRONMENT EXTENSIONS
When a CGI script is invoked as a sub-request of a SSI page, for example through the <--#exec cgi="..."> command, the following extra environment settings will also be present.In the following descriptions, "master document" refers to the document referenced by the client request's original URL, and "sub-request" means the SSI request itself.
DOCUMENT_ARGS This will be set to the QUERY_STRING of the master document. The value of QUERY_STRING for an SSI sub-request will contain the query string in the sub-request URL, if present, else the master document's QUERY_STRING. DOCUMENT_URI This will be set to the SCRIPT_NAME of the master document. DOCUMENT_PATH_INFO This will be set to the PATH_INFO of the master document. SSL ENVIRONMENT EXTENSIONS
When a CGI script is invoked through an SSL session (https://) to the web server, the following extra environment settings will also be present.
HTTPS This will be set to the value 'on' HTTPS_KEYSIZE This will be set to the size of the bulk encryption key used in the SSL session. Most encryption methods use a 128-bit key. HTTPS_SECRETKEYSIZE This will be set to the effective size of the bulk encryption key used in the SSL session. This is usually the same as the real size (HTTPS_KEYSIZE), but older export strength browsers may select the key using a lower strength method resulting in a lower strength 'effective key'. HTTPS_SESSIONID The value of the session id used by the SSL session. This value is unique for each distinct SSL session In addition, if the SSL client provides a client certificate, elements of this certificate are presented through the CGI environment. Check the SSL Client Certificate documentation for details.
COMMAND LINE ARGUMENTS
If the CGI script has some QUERY_STRING information, and this information does not include an '=' symbol (encoded in the request by the browser from a form input), then the CGI script is also given supplied command line arguments. This is to enable the execution of non-CGI programs as if they were CGIs, and is called an ISINDEX request. Specifically, the QUERY_STRING is split into substrings on the '+' symbol and each substring is from left to right is assigned to a subsequent command line argument.For example, if a CGI has a request with a QUERY_STRING of a+b+c then it will also be provided with argv[1] = "a", argv[2] = "b" and argv[3] == "c".
STANDARD INPUT
Information from the POST method is available to the CGI script from standard input (file descriptor 0 under UNIX). The amount of information available is set in the CONTENT_LENGTH environment variable. This information is encoded in the usual fashion, with spaces converted to '+' symbols and any non-alphanumeric characters converted to %xx where xx is a two-digit hexadecimal string describing the ASCII character it represents.
Output
Output from the CGI script to the web server is via standard output (file descriptor 1 under UNIX). The web server also multiplexes standard error onto standard output so any errors in the script processing get sent to the client, this greatly eases debugging of CGI scripts.The output from the CGI script consists of two parts, the CGI headers, and the content body.
CGI HEADERS
The CGI headers consist of a sequence of HTTP response lines in any order terminated by either a \r\n\r\n or \n\n or a non-HTTP response line (where \r and \n stand for the ASCII characters 13 and 10 respectively).A HTTP response line has a format <text>: <text>(\n|\r\n).
For example, generally a CGI will output something similar to:
Content-Type: text/html\r\n\r\nor a more complicated example:Content-Length: 30 Content-Type: text/html Expires: Wed, 25 Jun 1997 15:21:39 GMT \r\nThe web server processes the CGI header that is generated by the CGI script. For example, an ISAPI filter might want to add a HTTP header to all responses returned from the Virtual Server. The web server also corrects many mistakes found in CGI scripts while it is performing this processing stage to keep CGI scripts in line with the HTTP specification, such as converting Content-type lines into Content-Type lines.
SPECIAL HEADER LINES
If the first line of the CGI output has a special format of HTTP/x.y aaa desc the CGI can return a HTTP response of an arbitrary version of the HTTP protocol. For example, the HTTP/1.2 protocol might support a HTTP response code 420 - Credit Card Invalid. In which case the web server can be extended to support this new format by a CGI script which generates the HTTP response for this error message, such as:HTTP/1.2 420 Credit Card Invalid Content-Type: text/html <h1>Credit Card Invalid</h1>Note the HTTP response lines are still processed by the server in exactly the same way as a normal CGI response. This allows ISAPI filters to add / remove header lines for example.The following HTTP response lines are also considered special:
Response line Action taken by the web server Status Sets the HTTP status code for this response. For example: Status: 504 Gateway TimeoutLocation Forces a 302 Moved Temporarily HTTP response to be sent to the client. The Location line should specify where the client's browser should be redirected to. For example: Location: http://www9.zeus.co.uk/mirrorCONTENT BODY
The content body is the data to be sent to the client, normally a HTML page, but could just as easily be a GIF image for example. If the CGI set a Content-Length header then the content-body should consist of exactly this amount of data.Notes
For performance reasons, if the CGI script knows at the time of generating the CGI header the size of the content-body it will output, it should set a Content-Length line in the headers. This will let the web server use the HTTP/1.1 Keep-Alive feature with browsers that support this performance extension.