
                               BOA DOCUMENTATION
                                       
   In this document:
     * Installation and Usage
     * Performance limits and design philosophy
     * Differences between Boa and other web servers
     * Possible bugs
     * Possible unexpected behavior
     * Acknowledgments
       
   
     _________________________________________________________________
   
Installation and Usage

   Boa is currently being developed and tested on Linux/i386. The code is
   straightforward (more so than most other servers), so it should run
   easily on most modern Unix-alike platforms. Recent versions of Boa
   worked fine on FreeBSD, SunOS 4.1.4, Linux/SPARC, and HP-UX 9.0.
   Pre-1.2.0 Linux kernels may not work because of deficient mmap()
   implementations.
   
   It should be very simple to install and use Boa:
    1. Unpack
         1. Choose, and cd into, a convenient directory for the package.
         2. tar -xvzf boa-0.92.tar.gz, or for those of you with an
            archaic non-GNU tar, gzip -cd <boa-0.92.tar.gz | tar -xvf -
         3. Read the documentation. Really.
    2. Build
         1. If you don't have bison, flex, and gcc installed, adjust the
            definitions for YACC, LEX, and CC near the top of
            src/Makefile.
         2. (optional) Change the default SERVER_ROOT by setting the
            #define at the top of src/defines.h
         3. cd into the src directory and type "make". Report any errors
            to the maintainers for resolution, or strike out on your own.
    3. Configure
         1. Choose a user and server port under which Boa can run. The
            traditional port is 80, and user nobody (create if you need
            to) is often a good selection for security purposes. If you
            don't have (or choose not to use) root privileges, you can
            not use port numbers less than 1024, nor can you switch user
            id.
         2. Choose a server root. The conf directory within the server
            root must hold your local copy of the configuration files
            (boa.conf and mime.types).
         3. Choose locations for log files, CGI programs (if any), and
            the base of your URL tree. It is traditional to make these
            subdirectories of the server root.
         4. If you want Boa to generate directory indexes on the fly,
            choose scratch space to hold Boa's cache of these indexes. It
            has to be writable by the user Boa runs as. One nearly
            universal choice is /tmp/boa.
         5. Edit conf/boa.conf according to your choices above (this file
            documents itself). Read through this file to see what other
            features you can configure.
    4. Start
          + Start Boa. If you didn't build the right SERVER_ROOT into the
            binary, you can specify it on the command line with the -c
            option (command line takes precedence).
            Example: src/boa -c /usr/local/boa
    5. Test
          + At this point the server should run and serve documents. If
            not, check the error_log file for clues.
    6. Install
          + Copy the binary to a safe place, and put the invocation into
            your system startup scripts. Use the same -c option you used
            in your initial tests.
            
   
   
   I realize this isn't exactly comprehensive documentation; most of the
   general concepts are similar to other web servers. The documentation
   for NCSA httpd should be helpful if you are new to HTTP servers.
   
Performance limits and design philosophy

   There are many issues that become more difficult to resolve in a
   single tasking web server than in the normal forking model. Here is a
   partial list -- there are probably many that I haven't encountered
   yet.
     * Slow file systems
       The file systems being served should be much faster than the
       network connection to the HTTP requests, or performance will
       suffer. For instance, if a document is served from a CD-ROM, the
       whole server (including all other currently incomplete data
       transfers) will stall while the CD-ROM spins up. This is a
       consequence of the fact that Boa mmap()'s each file being served,
       and lets the kernel read and cache pages as best it knows how.
       When the files come from a local disk (the faster the better),
       this is no problem, and in fact delivers nearly ideal performance
       under heavy load. Avoid serving documents from NFS and CD-ROM
       unless you have even slower inbound net connections (e.g., POTS
       SLIP).
     * Directory indexing and stat() calls over NFS
       NFS mounted filesystems can be very slow when under heavy load,
       and the directory indexing for a particular request is done all at
       once while the other processes wait. If there are a large number
       of files or the NFS server is slow to respond, other connections
       will suffer.
     * DNS lookups
       Writing a nonblocking gethostbyaddr is a difficult and not very
       enjoyable task. I experimented with several methods, including a
       separate logging process, before removing hostname lookups
       entirely. There is a companion program with Boa (util/resolver.pl)
       that will postprocess the logfiles and replace IP addresses with
       hostnames, which is much faster no matter what sort of server you
       run.
     * Identd lookups
       Same difficulties as hostname lookups; not included. Boa provides
       a REMOTE_PORT environment variable, in addition to REMOTE_ADDR, so
       that a CGI program can do its own ident.
     * Password file lookups via NIS
       If users are allowed to serve HTML from their home directories,
       password file lookups can potentially block the process. To lessen
       the impact, each user's home directory is cached by Boa so it need
       only be looked up once.
     * Running out of file descriptors
       Since a file descriptor is needed for every ongoing connection, it
       is possible though highly improbable to run out of file
       descriptors. The symptoms of this conditions may vary with your
       particular unix variant, but you will probably see log entries
       giving an error message for accept. Try to build your kernel to
       give an adequate number for your usage - Linux provides 256 out of
       the box, more than enough for most people.
       
Differences between Boa and other web servers

   In the pursuit of speed and simplicity, some aspects of Boa differ
   from the popular web servers. In no particular order:
     * REMOTE_HOST environment variable not set for CGI programs
       The REMOTE_HOST environment variable is not set for CGI programs,
       for reasons described above. This is easily worked around because
       the IP address is provided in the REMOTE_ADDR variable, so (if the
       CGI program actually cares) gethostbyaddr or a variant can be
       used.
     * CGI output handled differently
       CGI programs output directly to the client rather than to the
       server. In most web servers, data from the CGI goes through the
       server before reaching the client. This allows the server to log
       the size of the transfer, and to buffer the data for more
       efficient use of the network. Since Boa does not do this, it
       cannot log the size of CGI transfers, nor can it handle error
       conditions in CGI programs. Once the CGI has begun, Boa is no
       longer aware of it. The advantage is that this is one less
       connection Boa has to participate in.
     * CGI "nph-" handled differently
       On other servers, "nph-" CGIs speak directly to the client. In
       Boa, the only difference between a regular CGI and an nph- CGI is
       that the server does not output any header lines in an nph-
       script.
     * There are no server side includes in Boa
       We don't like them, and they are too slow to parse. We will
       consider more efficient alternatives, see the to-do list.
     * There are no access control features
       Boa will follow symbolic links, and serve any file that it can
       read. The expectation is that you will configure Boa to run as
       user "nobody", and only files configured world readable will come
       out. See the to-do list.
     * No chroot option
       There is no option to run chrooted. If anybody wants this, and is
       willing to try out experimental code, contact the maintainers.
       
Possible bugs

     * No bugs are known
     * Recent changes
       Anything that has been touched recently might have broken
       something that previously worked. The Changelog gives some clues.
       
Possible unexpected behavior

     * Directory cache generation
       Be careful of configuration and permissions on the directory that
       the caches are stored in; Boa enforces some restrictions on
       ownership and permissions of the cache directory.
       No provisions are made yet to delete obsolete cache entries,
       although updates happen properly.
     * SIGHUP handling
       Like any good server, Boa traps SIGHUP and rereads boa.conf.
       However, under normal circumstances, it has already given away
       permissions, so many items listed in boa.conf can not take effect.
       No attempt is made to change uid, gid, log files, or server port.
       All other configuration changes should take place smoothly.
     * Relative URL handling
       Not all browsers handle relative URLs correctly. Boa will not
       cover up for this browser bug, and will typically report 404 Not
       Found for URL's containing "../"'s.
       
License

   This program is distributed under the GNU General Public License, as
   noted in each source file:

/*
 *  Boa, an http server
 *  Copyright (C) 1995 Paul Phillips <psp@well.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 1, or (at your option)
 *  any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 */

Acknowledgments

   You may notice inconsistent use of "I" and "we" in this document. In
   general, "I" refers to Paul Phillips, who actually wrote Boa. On the
   other hand, "we" refers to shared opinions of Larry Doolittle, Charles
   Randall, Jon Nelson, and Paul Phillips, who have all actively
   developed pieces of this code. Larry Doolittle takes the blame for the
   current release. We are all grateful that Russ Nelson stepped forward
   to host a real net presence for Boa. Of course, Larry, Charles, and
   Jon wish to thank Paul for writing code that is worth maintaining and
   supporting.
   
   Paul Phillips records his acknowledgments as follows: Thanks to
   everyone in the WWW community, in general a great bunch of people.
   Special thanks to Clem Taylor <ctaylor@eecis.udel.edu>, who provided
   invaluable feedback on many of my ideas, and offered good ones of his
   own. Also thanks to John Franks, author of wn, for writing what I
   believe is the best webserver out there.
     _________________________________________________________________
   
   Boa home page
   Last update: 16 December, 1996
   Larry Doolittle
