XS-HTTPD version 2.3
Contents
What is XS-HTTPD? XS-HTTPD is a WWW server that has
the following features:
- It is pronounced as "access-HTTP-daemon"
- It is SMALL (very small in fact: a factor two to three smaller than
normal servers on disk and in memory)
- It is FAST (because it is so small and does not do
unnecessary things)
- Uses very little CPU time
- Configurable (configuration compiled in to make it small, but
largely overridable on the command line)
- Runs user CGI binaries under their own user ID!
- Gets users' pages under their own user ID, allowing them to
really have protected pages (using the built-in authentication
mechanism)!
- Does not fork for every connection (has a fixed number of
servers), only to replace a lost server (in case of timeouts).
- Comes with some other useful programs
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.
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).
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.
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.
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.
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
-llibraryname 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.
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.