world leader in high performance signal processing
Trace: » boa

boa - a single tasking HTTP server

What is boa

Boa is a single-tasking HTTP server. That means that unlike traditional web servers, it does not fork for each incoming connection, nor does it fork many copies of itself to handle multiple connections. It internally multiplexes all of the ongoing HTTP connections, and forks only for CGI programs (which must be separate processes), automatic directory generation, and automatic file gunzipping. Preliminary tests show Boa is capable of handling several thousand hits per second on a 300 MHz Pentium and dozens of hits per second on a lowly 20 MHz 386/SX.

The primary design goals of Boa are speed and security. Security, in the sense of can't be subverted by a malicious user, not fine grained access control and encrypted communications. Boa is not intended as a feature-packed server; if you want one of those, check out WN from John Franks. Modifications to Boa that improve its speed, security, robustness, and portability, are eagerly sought. Other features may be added if they can be achieved without hurting the primary goals.

Boa was created in 1991 by Paul Phillips ( It is now being maintained and enhanced by Larry Doolittle ( and Jon Nelson ( Please see the acknowledgment section for further details.

Boa is very low on hardware usage and is therefore used on many embedded systems, including routers and portable devices.

Boa does handle CGI, but not PHP or ASP.

HowTo & man pages

uClinux-dist config

  • Build

In the uclinux-dist configuration menu:

Network Applications  --->
  [*] boa
  • 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 copy of the configuration file boa.conf
    • Choose locations for log files, CGI programs (if any), and the base of your URL tree.
    • Set the location of the mime.types file.
    • 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: ./boa -c /usr/local/boa
      • Example: boa -c /etc &
  • Test
  • At this point the server should run and serve documents. If not, check the error_log file for clues.
  • Files Used by Boa
    • boa.conf This file is the sole configuration file for Boa. The directives in this file are defined in the DIRECTIVES section.
    • mime.types The MimeTypes <filename> defines what Content-Type Boa will send in an HTTP/1.0 or better transaction.

boa.conf Directives

The Boa configuration file is parsed with a lex/yacc or flex/bison generated parser. If it reports an error, the line number will be provided; it should be easy to spot. The syntax of each of these rules is very simple, and they can occur in any order. Where possible, these directives mimic those of NCSA httpd 1.3; I (Paul Phillips) saw no reason to introduce gratuitous differences.

The “ServerRoot” is not in this configuration file. It can be compiled into the server (see defines.h) or specified on the command line with the -c option.

The following directives are contained in the boa.conf file, and most, but not all, are required.

  • Port <Integer> This is the port that Boa runs on. The default port for http servers is 80. If it is less than 1024, the server must be started as root.
  • Listen <IP> The Internet address to bind(2) to, in quadded-octet form (numbers). If you leave it out, it binds to all addresses (INADDR_ANY).
  • User <username or UID> The name or UID the server should run as. For Boa to attempt this, the server must be started as root.
  • Group <groupname or GID> The group name or GID the server should run as. For Boa to attempt this, the server must be started as root.
  • ServerAdmin <email address> The email address where server problems should be sent. Note: this is not currently used.
  • ErrorLog <filename> The location of the error log file. If this does not start with /, it is considered relative to the server root. Set to /dev/null if you don't want errors logged.
  • AccessLog <filename> The location of the access log file. If this does not start with /, it is considered relative to the server root. Comment out or set to /dev/null (less effective) to disable access logging.
  • VerboseCGILogs This is a logical switch and does not take any parameters. Comment out to disable. All it does is switch on or off logging of when CGIs are launched and when the children return.
  • CgiLog <filename> The location of the CGI error log file. If specified, this is the file that the stderr of CGIs is tied to. Otherwise, writes to stderr meet the bit bucket.
  • ServerName <server_name> The name of this server that should be sent back to clients if different than that returned by gethostname.
  • VirtualHost This is a logical switch and does not take any parameters. Comment out to disable. Given DocumentRoot /var/www, requests on interface `A' or IP `IP-A' become /var/www/IP-A. Example: http://localhost/ becomes /var/www/
  • DocumentRoot <directory> The root directory of the HTML documents. If this does not start with /, it is considered relative to the server root.
  • UserDir <directory> The name of the directory which is appended onto a user's home directory if a ~user request is received.
  • DirectoryIndex <filename> Name of the file to use as a pre-written HTML directory index. Please make and use these files. On the fly creation of directory indexes can be slow.
  • DirectoryMaker <full pathname to program> Name of the program used to generate on-the-fly directory listings. The program must take one or two command-line arguments, the first being the directory to index (absolute), and the second, which is optional, should be the “title” of the document be. Comment out if you don't want on the fly directory listings. If this does not start with /, it is considered relative to the server root.
  • DirectoryCache <directory> DirectoryCache: If DirectoryIndex doesn't exist, and DirectoryMaker has been commented out, the the on-the-fly indexing of Boa can be used to generate indexes of directories. Be warned that the output is extremely minimal and can cause delays when slow disks are used. Note: The DirectoryCache must be writable by the same user/group that Boa runs as.
  • KeepAliveMax <integer> Number of KeepAlive requests to allow per connection. Comment out, or set to 0 to disable keepalive processing.
  • KeepAliveTimeout <integer> Number of seconds to wait before keepalive connections time out.
  • MimeTypes <file> The location of the mime.types file. If this does not start with /, it is considered relative to the server root. Comment out to avoid loading mime.types (better use AddType!)
  • DefaultType <mime type> MIME type used if the file extension is unknown, or there is no file extension.
  • AddType <mime type> <extension> extension… Associates a MIME type with an extension or extensions.
  • Redirect, Alias, and ScriptAlias Redirect, Alias, and ScriptAlias all have the same semantics - they match the beginning of a request and take appropriate action. Use Redirect for other servers, Alias for the same server, and ScriptAlias to enable directories for script execution.
  • Redirect <path1> <path2> allows you to tell clients about documents which used to exist in your server's namespace, but do not anymore. This allows you tell the clients where to look for the relocated document.
  • Alias <path1> <path2> aliases one path to another. Of course, symbolic links in the file system work fine too.
  • ScriptAlias <path1> <path2> maps a virtual path to a directory for serving scripts.

For more information

Links to documents relevant to Boa development and usage. Incomplete, we're still working on this. NCSA has a decent page along these lines, too.

Some example Hello World CGI apps cgi_hello_world

Also see Yahoo's List

W3O HTTP page

RFC 1945 HTTP-1.0 (informational)

IETF Working Group Draft 07 of HTTP-1.1

HTTP: A protocol for networked information

The Common Gateway Interface (CGI)

RFC 1738 URL syntax and semantics

RFC 1808 Relative URL syntax and semantics