CGI binaries

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:
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.