Boa Documentation

• Installation and Usage
• Performance limits and design philosophy
• Differences between Boa and other web servers
• Possible bugs
• Possible unexpected behavior
• Acknowledgments

Installation and Usage

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

• 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

• 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. This feature has been added to Boa-0.93 (still under development).

Bugs

• Signal handling isn't compatible with SunOS
  A Sun-specific patch will fix things up, although of course it breaks the source for any non-SVR4 system. Boa-0.93 changes to POSIX-style signal handling, which is intended to be more portable.
• CGI HEAD is broken.
  Boa does not run the program, but spits out an almost complete header instead. Related to Boa's lack of header parsing. This problem is addressed in Boa-0.93.
• CGI only good for 200 OK output.
  The CGI implementation of Boa works fine if the CGI program sticks to normal content - fancy stuff like redirects will not. The way to achieve functionality like this in Boa-0.92 is through the use of nph- style CGI programs, since they send their own response code. Such programs will also run more efficiently on all servers, including Boa. Proper server parsed headers are in progress in Boa-0.93.
• On-the-fly directory index pages can go stale.
  If a file changes size, the mtime of the directory containing it will not normally be updated. Since Boa uses that mtime to determine when to regenerate the index cache, the file sizes reported by Boa's on-the-fly indexes can lie. To force an update, touch(1) the directory.
• Redirect, Alias, and ScriptAlias can generate unexpected results, especially if some patterns are short (three or fewer letters).
  Don't use short patterns. If this cramps your style, contact the authors to make sure our hypothesized fixes do you some good.
• SIGHUP does not treat all the aliases and mime.types stuff properly.
  If you want to change aliases or mime.types, you have to shut down and restart the server.
• Boa does not daemon itself as the documentation says it should.
  The code to do so is in boa.c, but commented out to make debugging easier. Either uncomment the code, or add & to the startup command.
• It's too slow.
  Boa-0.92 will never set any speed records. Three strftime()'s and an 18K memcpy per transaction take several milliseconds on most machines. Even with this handicap, you can expect performance at least as good as Apache at low load, and dramatically better performance at high load, when Apache can thrash RAM and overload the kernel's context switching. Look for a dramatic reduction of user-space CPU cycles in Boa-0.93.

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. Some other configuration changes should take place smoothly, but mime.types and alias changes don't (see the Bugs section).
• 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

/*
 *  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

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.