The server, as of version 2.0, supports running system and user CGI
binaries. This means that anyone can run their own CGI binaries.
What is different about this server is that it runs users' CGI binaries
under their own user ID. This means that they have full access to their
files - they can read/write/update any file that they own.
CGI binaries must be in the directory named cgi-bin which
must be in either the WWW server's virtual / or in the user's
WWW directory (see the local
configuration
section about a user's WWW directory). Since version 2.2, the CGI
binaries can be in a subdirectory of the cgi-bin directory.
The server is completely CGI/1.1 compliant (except that it cheats with
local file redirections). You can read about the CGI specification at
NCSA's WWW site.
Supported environment variables are:
- SERVER_SOFTWARE
- The name and version of the xs-httpd that started the binary.
Format: xs-httpd/version
- SERVER_NAME
- The server's hostname, DNS alias, or IP address as it would appear
in self-referencing URLs.
- GATEWAY_INTERFACE
- The revision of the CGI specification to which this server
complies. Format: CGI/revision
- SERVER_PROTOCOL
- The name and revision of the information protcol this request came
in with. Format: protocol/revision
- SERVER_PORT
- The port number to which the request was sent.
- REQUEST_METHOD
- The method with which the request was made. For HTTP, this is
"GET", "HEAD", "POST", etc.
- 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.
- 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 the script is protected, this is the username the remote
user has authenticated with.
- REMOTE_PASSWORD
- If the the script is protected, this is the password the remote
user used.
- CONTENT_TYPE
- For queries which have attached information, such as HTTP POST and
PUT, this is the content type of the data.
- CONTENT_LENGTH
- The length of the said content as given by the client.
The XS-HTTPD has one enhancement on the CGI specifications. It
doesn't only support the nph- naming convention (No Parse
Headers), but also the nid- naming convention (to use both,
first put nph- and then nid-). This makes the CGI
binary run under nobody/nogroup, instead of the user's own UID.
For example, if you name your CGI binary nid-form.cgi,
it will run that binary under nobody/nogroup instead of your own
UID (this is to protect yourself from accidental damage).
There is one reserved CGI binary name known as error.
This binary gets called whenever something goes wrong. Users may have
their own personal error CGI binary. This binary gets called
if the server can decode the user's name but something goes wrong
anyway (for instance, one of that user's files can't be found).
If there is a system error CGI binary, that one will be called if
anything goes wrong, except in the case that the user has a personal
error CGI binary.
This can be used to create friendly error messages with links to
appropriate (existing :) pages.
A few environment variables are set before error is called:
- ERROR_CODE
- This variable is set to one of the following values:
- USER_UNKNOWN - the specified user is unknown
- POST_ON_NON_CGI - a POST method was attempted to
a non-CGI binary
- INVALID_PATH - an invalid path was specified,
for example one with .. in it
- DIR_NOT_AVAIL - the directory is protected by
a .noxs file
- NOT_REGULAR - the file to be retrieved is not a
regular file
- PERMISSION - the file's permission deny access to
the file
- NOT_FOUND - the requested file cannot be found
- NO_RELATIVE_URLS - URL not starting with a /
are not supported
- UNKNOWN_METHOD - the requested method is not
POST, GET or HEAD.
- UNAUTHORIZED - a user tried an invalid
usercode/password combination to get to a file.
The values in REMOTE_USER and REMOTE_PASSWORD
are what the user has tried to use.
- 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 process some of the ERROR_CODEs
above.
- ERROR_URL
- The URL that was requested (without the server name)
- ERROR_URL_EXPANDED
- The URL that was requested with /~user/ expanded
- ERROR_URL_ESCAPED
- The request URL as above, but with <, >
and & substituted to make it printable
Of course, regular CGI variables are also set, such as
REQUEST_METHOD.