XS-HTTPD version 2.3

Contents


Overview

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

  1. It is pronounced as "access-HTTP-daemon"
  2. It is SMALL (very small in fact: a factor two to three smaller than normal servers on disk and in memory)
  3. It is FAST (because it is so small and does not do unnecessary things)
  4. Uses very little CPU time
  5. Configurable (configuration compiled in to make it small, but largely overridable on the command line)
  6. Runs user CGI binaries under their own user ID!
  7. Gets users' pages under their own user ID, allowing them to really have protected pages (using the built-in authentication mechanism)!
  8. Does not fork for every connection (has a fixed number of servers), only to replace a lost server (in case of timeouts).
  9. Comes with some other useful programs

Installation

Installing these programs should be very simple.

Adjust the Makefile. There should not be a lot to adjust, probably only the CC, CFLAGS and the LDFLAGS. Instructions on how to set up the Makefile are in the file itself. If something goes wrong while you're editing the Makefile, the original version is in Makefile.original.

Next, adjust config.h (detailed instructions are in the file itself) to contain the necessary information for your system. I have supplied a shell script that determines as much of your system's information as possible. This script is called autodetect. When you run it, it will create a config.h for you. Run it by typing: sh autodetect.

If you need to edit config.h by hand, you will need to copy config.h.generic to config.h first.

Then, type make. This should compile the programs without any warnings (with Linux though, I've been getting the warnings: `MAP_FILE' redefined; it does not matter - it can be fixed, by the way, by installing the latest version of the C library and its include files). If you are having trouble compiling the package, see the troubleshooting help.

If that is successful, type make install to install the programs and data files in the correct locations. You might want to type make -n install first to see where the programs and the others files are going to be stored. If you do not like the directories, edit the Makefile and retry.


Running the program

The manual page that comes with the httpd describes in detail how to run the WWW server. Type man httpd on a prompt after installing the entire package. Please do not forget to install a cron entry for clearxs. See its manual page for the details (type man clearxs on a prompt after installing the entire package).

Other programs

When you compile the server as described above, some other programs will be compiled as well. Some of these programs are for the authentication part of the WWW server. Others are for accessing the counter file. And there are the imagemaper, the graphical counter, the daemon controller and the index creator. Manual pages of these programs will be installed when the package is installed. Read them!

The programs are: xspasswd, xschpass, imagemap, readxs, clearxs, xsindex, httpdc and gfxcount.


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

Server side includes

There is more information about SSI's in another file.

Custom configuration

As with every program, the defaults that I've given are probably not what your system requires or what you want. Therefore, you might need to edit the Makefile and config.h files. Documentation is in those files themselves. Just follow the step by step instructions and all should be fine.

The WWW server has a provision for supplying your own local ~ expansion. In other words, you can determine where /~USER/ is physically. Normally, you would take that user's home directory from the password file and add /.html to it (or /public_html on some systems). But you can make much more elaborate constructions.

The file that performs this task (convert /~USER/ to a physical directory) is local.c. It contains a function transform_user_dir which takes three parameters: a buffer to place the name of the directory in, the struct passwd pointer to the user's information, and a flags which turns off or on error messages.

You can make your own transform_user_dir if you wish. The routine may use the variable localmode, which is set to 1 by default, but can be overridden by the -l command line option. For example, the default local.c uses it to call one of three routines, depending on the variable localmode. See the default file for elaborate examples of routines that you may want to adapt for your personal use.

There is not much else that you can configure. If you want to add some things to the WWW server, please contact me first to verify that nobody else is working on an equal feature.


Troubleshooting help

If you are having any trouble compiling this server or one of its accompanying programs, perhaps you can find an answer here:

This concludes the troubleshooting help so far. If you have any useful tips that others might be able to use, please do not hesitate to contact me.

About the author

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