Boa Documentation
In this document:
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:
- Unpack
- Choose, and cd into, a convenient directory for the package.
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 -
- Read the documentation. Really.
- Build
- If you don't have bison, flex, and gcc installed, adjust the definitions
for YACC, LEX, and CC near the top of src/Makefile.
- (optional) Change the default SERVER_ROOT by setting the #define
at the top of src/defines.h
- cd into the src directory and type "make". Report any
errors to the maintainers for resolution, or strike out on your own.
- Configure
- 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.
- 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).
- 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.
- 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
.
- 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.
- 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
- Test
- At this point the server should run and serve documents.
If not, check the error_log file for clues.
- 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.
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.
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.
- No bugs are known
- Recent changes
Anything that has been touched recently might have broken something
that previously worked. The Changelog gives some
clues.
- 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.
*
*/
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