Manual Reference Pages  - HTTPD_CGI (7)

NAME

httpd_cgi Common Gateway Interface (CGI) for xs-httpd

CONTENTS

Description
File Uploading
Environment Variables
See Also
Standards

DESCRIPTION

The WWW server supports running system and user CGI binaries. This means any user can run their own CGI binaries. Any CGI binary runnig for a user run as the user. As a consequence these CGI binaries are allowed to read, write, update and delete files owned or accessible by the user.

CGI binaries must be in the directory named cgi-bin which must be in either the WWW server’s virtual root, or in the user’s WWW directory (see the local configuration section about a user directories). CGI binaries may also be in subdirectories of the cgi-bin directory. It is also possible to run CGI binaries outside this directory, see the xsscripts(5) configuration file documentation.

CGI binaries can be written in any language, as long as it is installed as an executable program on the webserver machine. Scripting in shell languages, PHP or Perl is common, but compiled programs can be used just as well. It is important that the executable bit (chmod u+x) is set for a CGI binary.

The CGI binary should output HTTP headers and content, separated by an empty line. The following headers are frequently set by CGI binaries
Content-type:
  used to determine the type of content. Common values include 'text/plain' and 'image/png'. The default is 'text/html' when this header is not set.
Status:
  will be used to generate the HTTP response code. Should only be set when generating an error message, otherwise it will default to '200 OK'.
Location:
  sets the URL to which the client should be redirected. When setting a location header, the HTTP status code will default to '302 Moved'.

Note that a CGI script may omit all headers and let the server automatically generates sensible defaults. In this case the output of the CGI script should start with an empty line.

A CGI must be able to read its arguments from the correct place. If the request method is GET then arguments will be included in the environment variable QUERY_STRING, but on a POST (or PUT) request the user data must be read from standard input. When handling a HEAD request, only the headers must be written and no body content.

By default the headers generated by a CGI script will be parsed by the server and any missing headers will be added. However to give the author full control, it is possible to let the script output all headers. If the name of the CGI binary starts with nph-’ (no parse headers) then the server won’t do any header validation. It is generally not a good idea to use nph, unless you really know what you are doing.

By default the output of a CGI script is not parsed for server-side includes. Usually there is no point, because CGI allows you to do all the fancy stuff SSI offers and more but for some features (like the built-in counters) parsing may be desired. If the name of the CGI binary starts with ssi-’ then the output will be parsed.

There is one special purpose CGI binary error which, if it exists, gets called in case of an HTTP error (404, 403, ..). Users can have their own personal error CGI binary. If a user has a personal error CGI binary it will be called in case an error occurs on a request pertaining to that user. Extra environment variables that describe the situation, will be available to this error script (see below).

FILE UPLOADING

Apart from the standard GET, HEAD and POST methods, HTTP/1.1 allows file uploading and deletion using the PUT and DELETE methods respectively. These methods are required to implement WebDav support. The methods must be explicitly handled by CGI scripts if you want to support these: there is no built-in default action. The scripts can be configured on a per directory basis using the PutScript and DeleteScript directives; see the xsconf(5) configuration file.

The CGI script (environment) should take care of proper sanity checking and permission handling. Use of HTTP or SSL authentication is strongly recommended. Keep in mind that CGI scripts run with normal user privileges and access to all your files.

ENVIRONMENT VARIABLES

The server sets the following environment variables for a CGI binary:
GATEWAY_INTERFACE
  The revision of the CGI specification to which this server complies. Format: CGI/revision
SERVER_SOFTWARE
  The name and version of the httpd that started the binary. Format: xs-httpd/version branch/subversion ...
SERVER_PROTOCOL
  The name and revision of the information protocol this request came in with. Format: protocol/revision
SERVER_NAME
  The server’s hostname, DNS alias, or IP address as it would appear in self-referencing URLs.
SERVER_PORT
  The port number the request was sent to (usually 80).
REQUEST_METHOD
  The method with which the request was made. For HTTP, this can be 'GET', 'HEAD', 'POST', etc.
REQUEST_URI
  The URI part of the original request. That is the URL without protocol and hostname/port specification (but including the QUERY_STRING parameters.
REDIRECT_STATUS
  The return status of the request. This should always be 200 for normal CGI binaries. Some php tools rely on this.
PATH_INFO
  The extra path information, as given by the client. In other words, scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. This information is decoded by the server if it comes from a URL before it is passed to the CGI script.
PATH_TRANSLATED
  The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it.
SCRIPT_NAME
  A virtual path to the script being executed, used for self-referencing URLs.
QUERY_STRING
  The information which follows the ?’ in the URL which referenced this script. This is the query information. It will not be decoded in any fashion. This variable is always set when there is query information, regardless of command line decoding.
REMOTE_HOST
  The hostname making the request. If the server does not have this information, it will set REMOTE_ADDR and leave this unset.
REMOTE_ADDR
  The IP address in text of the remote host making the request. See also HTTP_CLIENT_IP and HTTP_VIA.
AUTH_TYPE
  If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user.
REMOTE_USER
  If the script is protected, this is the username the remote user has authenticated with.
REMOTE_PASSWORD
  If the script is protected with basic authentication, this is the password the remote user used.
CONTENT_TYPE
  For queries which have attached information, such as HTTP POST and PUT requests, this is the content type of the data.
CONTENT_LENGTH
  The length of the content as given by the client.

Whenever a connection is made using a secure SSL or TLS transport, the following environment variables will also be made available:

HTTPS Set to on’ whenever the connection uses secure SSL or TLS transport. This can be used to check if a connection is encrypted.

SSL_CIPHER
  The cipher used for encryption via SSL or TLS.

SSL_CLIENT_S_DN
  The Distinguished Name of the subject of the client certificate. This variable contains all information available about the user.

SSL_CLIENT_S_DN_CN
  The Common Name of the subject. This is a part of SSL_CLIENT_S_DN and gives the name that can be used to identify the certificate user. This should always be present in client certificates.

SSL_CLIENT_S_DN_Email
  The email address of the subject. This is an optional part of SSL_CLIENT_S_DN and may not always be available.

SSL_CLIENT_I_DN
SSL_CLIENT_I_DN_CN
SSL_CLIENT_I_DN_Email
  The Distinguished Name, Common Name and email address respectively of the issuer of the client certificate. These contain information available about the organisation that signed the certificate for this user.

In addition to the aforementioned CGI environment variables a variable of the form HTTP_ header will be generated for each header in the request. Common header generated CGI environment variables include HTTP_REFERER, HTTP_COOKIE, HTTP_HOST and HTTP_ACCEPT.

In the case that the CGI is called as the error CGI, the following environment variables describing the error condition are also set:
ERROR_CODE
  depending on the error this variable is set to one of the following values:
'NOT_FOUND'
  The requested file cannot be found.
'NOT_AVAILABLE'
  The (filesystem) permission deny access to the file.
'USER_UNKNOWN'
  The specified user is not known.
'BAD_REQUEST'
  The client sent a request that cannot be processed by the server.
'METHOD_NOT_ALLOWED'
  A POST request was attempted to a non-CGI binary.
'PRECONDITION_FAILED'
  The client sent a conditional request (If-...) of which the condition is not met.
ERROR_READABLE
  This variable contains the text that the server would normally send to the remote client. This can be used in case you do not want to generate your own error message.
ERROR_URL
  The URL that was requested (without the server name) when the error occurred.
ERROR_URL_EXPANDED
  The full pathname of the file on disk that is associated with the request.
ERROR_URL_ESCAPED
  A HTML-escaped representation of the ERROR_URL value. The '<', '>' and '&' are replaced with their SGML entities so the variable can be shown in a HTML page.

SEE ALSO

httpd(1)

The project homepage: http://www.xs-httpd.org/

STANDARDS


.Rs The Common Gateway Interface (CGI) Version 1.1
.Re


May 9, 2007 HTTPD_CGI (7) xs-httpd/3.5