# XS-HTTPD version 2.3

## Contents

- Overview
- Installation
- Running the WWW server
- Other programs
- Features
- Server side includes
- CGI binaries
- Local configuration
- About the author

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

- Problem: The compiler cannot find a `.h` file
- Answer: If the file is listed in `config.h` and there is the word `#define` before it, then change `#define` to `#undef`. If it is not listed in `config.h` then try removing the line which includes that file. In any case, if you cannot change `config.h` in such a way that the programs can find the include file (or forget about it), please mail me.

- Problem: The compiler aborts while compiling
- Answer: There is not simple way to tell you how to fix this. Try changing `config.h`. If you can not find anything in `config.h` that remedies your problem, please contact me.

- Problem: The linker complains about symbols that cannot be found
- Answer: Check that you have specified all the necessary libaries for your system in the `Makefile`. Typical libraries that you have to add are `crypt`, `intl` and `resolv`. The way to do this is to find the line `LDFLAGS=`something and add `-l`libraryname to the end of the line.

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.nl). I made all the programs, except the imagemapper, which I took from the NCSA distribution and cleaned up.