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