HTTPD(1)

NAME
httpd - WWW server conforming to HTTP/1.0

SYNOPSIS
httpd [ options ]

DESCRIPTION OF HTTPD
What is XS-HTTPD? XS-HTTPD is a WWW server that has the following features:

o   It is pronounced as "access-HTTP-daemon"

o   It is SMALL (very small in fact: a factor two to three smaller than normal servers on disk and in memory)

o   It is FAST (because it is so small and does not do unnecessary things)

o   Uses very little CPU time

o   Configurable (configuration compiled in to make it small, but largely overridable on the command line)

o   Runs user CGI binaries under their own user ID!

o   Gets users' pages under their own user ID, allowing them to really have protected pages (using the built-in authentication mechanism)!

o   Does not fork for every connection (has a fixed number of servers), only to replace a lost server (in case of timeouts).

o   Comes with some other useful programs

RUNNING THE HTTPD
Note that if you are going to use a port number below or equal to 1024 (for example 80, the default port number), you will have to be root to start the WWW server. Also, if you want users' CGI binaries to be executed under their own user ID, you will have to start the WWW server as root. The server has a number of options:

-p portnumber
    Uses port number portnumber instead of the default (the factory default is 80).

-u username
    Runs the server under username's user id instead of the default (the factory default is nobody).

-g groupname
    Runs the server under groupname's group id instead of the default (the factory default is nogroup).

-n number
    Uses number as the number of servers to start (the factory default is 20).

-d rootdir
    Uses rootdir as the base directory for other directories like the logs directory, the htdocs directory and the cgi-bin directory. The factory default is /usr/local/lib/httpd.

-r referdomain
    Uses referdomain as the "refer-ignore-domain". References coming from this domain will not be logged in the refer_log. This is usually your own domain. Note that it is wise to start the domain with a dot (.). You may also give a machine name instead of a domain name.

-l localmode
    Uses localmode as the parameter to transform_user_dir(). This way, you can build different options into your local configuration. Not recommended for non-experts.

-a address
    Uses address as the internet address to listen on. This is very handy on "multi-homing" server with multiple interfaces. Uses this option, you can place servers with different functionality on different interfaces. This name is also used for redirecting requests back to this host. Therefore, you must use a "full" (complete with the host's name and the domain) internet address, otherwise remote hosts will not be able to resolve the name.

-m service-message
    If you give this option to the server, it will not function as it normally would. Instead of supplying documents, all it will do is display the service-message. This is very useful to at least give users an idea of what you are doing when the server is temporarily out of order. Remember that if you are supplying an entire sentence, then you have to enclose that sentence in quotes (").

-A access-log-path
    If you give this option to the server, you will override the default file in which the server will place all retrieved files.

-E error-log-path
    If you give this option to the server, you will override the default file in which the server will place all error messages.

-R referer-log-path
    If you give this option to the server, you will override the default file in which the server will place references to local files.

EXAMPLE
A typical startup sequence could be:

httpd -n 64 -u http -g www -r .stack.nl -l 2

which will start 64 servers (64 concurrent connections possible), and run it under user ID http and group ID www. It will ignore any references coming from *.stack.nl and it will pass 2 as a parameter to transform_user_dir.

Other features

Automatic decompression
One of the nice features of the WWW server is automatic decompression. This feature is dealt with in the file called compress.methods.

This file lists the possible compression types that are understood by the WWW server. It works very simply: if somebody asks for (for example) index.html, and this file does not exist, but index.html.gz does exist, then index.html will be `generated' out of index.html.gz using the method specified with .gz. Note that this process does not actually create index.html in that same directory. It creates a file in the temporary directory, which is removed immediately after usage.

If somebody asks directly for index.html.gz, he will get it in the compressed format. This way, nice things like the following can be done:

Get <A HREF="xshttpd.tar">the uncompressed tar</A>, or get the <A HREF="xshttpd.tar.gz">the compressed tar</A>.

The user only has to have the compressed version, because if somebody asks for the uncompressed version, the server will uncompress it on the fly for that user.

Note that only one compression type per file is possible. Of course, you can make frontends for types that require multiple filters. In that case, it can be helpful to know that the list is traversed from top to bottom.

Authentication
This server supports the basic authentication protocol. This means that users can protect their pages with a username/password combination. Other servers can do this too, but they lack one thing: the "protected" files have to be world-readable. Because this server retrieves pages under users' own UID, this problem is avoided.

More information about authentication can be found in the manual pages of xspasswd and xschpass.

Special files
There are a number of files that this WWW server considers special:

.noxs
    If this file exists in a certain directory, that entire directory is considered closed. If somebody attempts to retrieve a file from that directory, he will get a Permission denied notice. This is useful for users and system administrators: users can use it when they are updating the directory and system administrators can use it to easily shut down a group of pages. Note that only the directory in which the file is present is blocked. Subdirectories are not blocked.

.xsuid
    If this file exists in a certain directory, all files in that directory will be retrieved as (by default) nobody/nogroup instead of under your own UID. This can be useful if you want a file permission of say 600 to mean: do not allow retrieval (by default, the file is retrieved under your own UID, so the daemon could have still read those files).

.redir
    If this file is present in a certain directory, and a file is requested from that directory, then a redirection message will be sent to the remote user's browser. It works simply by substituting the server name and the directory that the remote user to get to this file by the contents of the file. This way, an entire directory can be automatically be redirected.

*.redir
    If a file is requested and a file exists with the same name but with .redir appended to it, the file will not be sent. Instead, the server will send a redirection message to the remote user's browser. The redirected location is retrieved from the *.redir file.

.xsauth
    If this file exists, all files in that directory (NOT the subdirectories) are protected by usercode/password combinations. Read the manual page of xspasswd for more details about this.

XS-HTTPD SSI's
One of the most advanced features of this WWW server is its server side includes. Server side includes (SSI's) are "commands" to the server to do something. These may be embedded in HTML documents.

The format of such a directive is as follows:
<!--#name [argument(s)]-->

name is the name of the directive. You may specify arguments to the directive if needed or wanted, seperated from the directive's name by one space. Note also that a directive must start and end on the same line. You may have other things on that line, including other directives.

When the server sends a HTML document to the remote client, it will parse all of the directives that are embedded in that document. The possible directives are:

count-total
    This directive inserts the number of times that this page has ever been retrieved. You may use counters as many times as you wish per page, they will only increment once.

count-month
    This directive inserts the number of times that this page has been retrieved this month.

count-today
    This directive inserts the number of times that this page has been retrieved today.

count-total-gfx [location]
    This directive inserts a HTML tag to include a graphical representation of the number of times that this page has ever been retrieved. If location is specified, it will be used as a base location for the font. A font has 10 digits in it, each in a seperate file, all PPM's. Say location is /~user/font1, and digit 1 is needed, then /~user/font1/1.ppm will be used as that digit. Two default fonts are supplied with this WWW server. They may be accessed using the locations: /fonts/digital and /fonts/large.

count-month-gfx [location]
    This directive inserts a HTML tag to include a graphical representation of the number of times that this page has been retrieved this month. See above for location.

count-today-gfx [location]
    This directive inserts a HTML tag to include a graphical representation of the number of times that this page has been retrieved today. See above for location.

date
    This directive inserts the current date and time, optionally in your own format. You can specify your own date and time format using the date-format directive (see below).

date-format format
    This directive uses format as the new date and time format. You must specify the format in strftime(3) format. Type man strftime for help on how to use this format.

include-file file
    This directive allows you to include another file in this document. Very useful for standard headers and footers. Note that included files may be nested and that directives are parsed in them. Note also that counters and such always count the original file, so you can use the count-* directives in your standard headers and footers.

last-mod
    [file] This directive (with a pseudonym last-modified inserts the last modification date of either the originally request file (the current document) or the optionally specified file. The date will be in the format specified by the date-format directive.

remote-host
    Inserts the name (or the IP number if the name cannot be resolved) of the remote computer that is asking for this document.

run-cgi cgi
    Runs the CGI binary cgi and inserts its output at this point. Standard PATH_INFO and PATH_TRANSLATED parsing is done, so you can give argumens to the CGI binary. All standard CGI environment variables will be set up appriopriately. See the CGI section for more details on CGI's.

agent-short
    This directive inserts the name of the browser that the remote user is using in the short version (i.e. without the version number). Note that Netscape is displayed as Mozilla, which is Netscape's real name.

agent-long
    This directive inserts the name of the browser that the remote user is using in the long version (i.e. with version numbers and other comments that the browser sends).

if keyword pattern(s)
    The following four directive are the most powerful: they allow a kind of flow control in your documents. This directive displays all text and directives after it until it encounters an endif or a else directive, if the query evaluates to true.

Possible keywords are:

browser
    If any of the patterns match the browser name that the remote user if using, the query evaluates to true, otherwise it evaluates to false. See below on how to specify patterns.

remote-host
    If any of the patterns match the remote host's name or IP number, the query evaluates to true, otherwise it evaluates to false.

remote-name
    If any of the patterns match the remote host's name, the query evaluates to true, otherwise it evaluates to false.

remote-addr
    If any of the patterns match the remote host's IP number, the query evaluates to true, otherwise it evaluates to false.

argument
    It is possible (since version 2.1) to pass arguments to HTML documents. If any of the patterns match the given argument, the query evaluates to true, otherwise it evaluates to false.

Arguments are passed by appending a question mark to the page's URL and giving the arguments after that. For example:
http://www.foo.bar/~test/blah.html?this_is_an_argument Patterns are simple wildcard patterns (case-insensitive). For example, to match any version of Netscape (which is really called Mozilla), you would use mozilla/*. If you want to match any Mosaic version 2, you would use *Mosaic*/2*.

A browser's name is always constructed in the following way:
browsername/version extra/version

if-not keyword pattern(s)
    This does exactly the same as if, except that it displays the following text only if the query evaluates to false instead of true.

else
    This can be used after an if or if-not directive. The meaning is obvious.

endif
    Ends an if or not-if. Note that these constructions may be nested!

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, CGI binaries can be in subdirectories 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.

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 (by default) 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 those 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 message 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:

o   USER_UNKNOWN - the specified user is unknown

o   POST_ON_NON_CGI - a POST method was attempted to a non-CGI binary

o   INVALID_PATH - an invalid path was specified, for example one with .. in it

o   DIR_NOT_AVAIL - the directory is protected by a .noxs file

o   NOT_REGULAR - the file to be retrieved is not a regular file

o   PERMISSION - the file's permission deny access to the file

o   NOT_FOUND - the requested file cannot be found

o   NO_RELATIVE_URLS - URL not starting with a / are not supported

o   UNKNOWN_METHOD - the requested method is not POST, GET or HEAD.

o   UNAUTHORIZED - the user has attempted to access a file that is protected by a username and password combination. The user has filled in wrong username/password combination.

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.

ACKNOWLEDGEMENTS
I thank all the members at MCGV Stack who are actively involved in the entire WWW happening.

SEE ALSO
http://www.stack.nl/~sven/xs-httpd/
xspasswd(1), imagemap(1), clearxs(1), readxs(1), gfxcount(1), xsindex(1), httpdc(1)

COPYRIGHT
All the programs in the XS-HTTPD package are copyright (C) 1995, 1996 by Sven Berkvens, except the imagemapper.

AUTHOR
The author of this WWW server and its accompanying programs is Sven Berkvens (sven@stack.nl). I made all the programs, except the imagemapper, which I took from the NCSA distribution, but I cleaned it up.