HTTPD_CGI(7) BSD Miscellaneous Information Manual HTTPD_CGI(7)NAMEhttpd_cgi Common Gateway Interface (CGI) for xs-httpd
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 pos‐
sible 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 set‐
ting a location header, the HTTP status code will default to
‘307 Moved’.
X-Sendfile:
discard all output and send the file that is specified as argu‐
ment of this header instead. An absolute path must be specified.
Note that a CGI script may omit all headers and let the server automati‐
cally 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 privi‐
leges 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 com‐
plies. Format: CGI/revision
SERVER_SOFTWARE
The name and version of the httpd that started the binary. For‐
mat: 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, fol‐
lowed 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-refer‐
encing 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 trans‐
port. 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 respec‐
tively of the issuer of the client certificate. These contain
information available about the organisation that signed the cer‐
tificate 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 envi‐
ronment variables describing the error condition are also set:
ERROR_CODE
depending on the error this variable is set to one of the follow‐
ing values:
‘NOT_FOUND’
The requested file cannot be found.
‘NOT_AVAILABLE’
The (file system) 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 ALSOhttpd(1)
The project homepage: http://www.xs-httpd.org/
STANDARDS
The Common Gateway Interface (CGI) Version 1.1, RFC 3875, October 2004.
xs-httpd/3.5 May 9, 2007 xs-httpd/3.5
