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