Boa Documentation

In this document:

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
  5. Test
  6. Install

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.

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:

Possible bugs

Possible unexpected behavior


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