Next Previous Contents

2. Installation and Usage

Boa is currently being developed and tested on GNU/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, GNU/Linux-SPARC, and HP-UX 9.0. Pre-1.2.0 GNU/Linux kernels may not work because of deficient mmap() implementations.

It should be very simple to install and use Boa:


  1. Choose, and cd into, a convenient directory for the package.
  2. tar -xvzf boa-0.94.tar.gz, or for those of you with an archaic (non-GNU) tar,
    gzip -cd < boa-0.94.tar.gz | tar -xvf -
  3. Read the documentation. Really.


  1. cd into the src directory.
  2. (optional) Change the default SERVER_ROOT by setting the #define at the top of src/defines.h
  3. Type ./configure; make
  4. Report any errors to the maintainers for resolution, or strike out on your own.


  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 copy of the configuration file boa.conf.
  3. Choose locations for log files, CGI programs (if any), and the base of your URL tree.
  4. Set the location of the mime.types file.
  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.


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


At this point the server should run and serve documents. If not, check the error_log file for clues.


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.

2.1 Files used by Boa


This file is the sole configuration file for Boa. The directives in this file are defined in the DIRECTIVES section.


The MimeTypes <filename> defines what Content-Type Boa will send in an HTTP/1.0 or better transaction.

2.2 Compile-Time and Command-Line Options


The default server root as #defined by SERVER_ROOT in defines.h can be overridden on the commandline using the -c option. The server root must hold your local copy of the configuration file boa.conf.
Example: /usr/sbin/boa -c /etc/boa

2.3 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.

Note: 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>

Listen: the Internet address to bind(2) to. If you leave it out, it takes the behavior before, which is to bind to all addresses (INADDR_ANY). You only get one "Listen" directive, if you want service on multiple IP addresses, you have three choices:

  1. Run boa without a "Listen" directive
    1. All addresses are treated the same; makes sense if the addresses are localhost, ppp, and eth0.
    2. Use the VirtualHost directive below to point requests to different files. Should be good for a very large number of addresses (web hosting clients).
  2. Run one copy of boa per IP address, each has its own configuration with a "Listen" directive. No big deal up to a few tens of addresses. Nice separation between clients. The name you provide gets run through inet_aton(3), so you have to use dotted quad notation. This configuration is too important to trust some DNS.

User <user name or UID>

The name or UID the server should run as. For Boa to attempt this, the server must be started as root.

Group <group name 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.


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.


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 <path1> <path2>

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.


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.


aliases one path to another. Of course, symbolic links in the file system work fine too.


maps a virtual path to a directory for serving scripts.

2.4 Security

Boa has been designed to use the existing file system security. In boa.conf, the directives user and group determine who Boa will run as, if launched by root. By default, the user/group is nobody/nogroup. This allows quite a bit of flexibility. For example, if you want to disallow access to otherwise accessible directories or files, simply make them inaccessible to nobody/nogroup. If the user that Boa runs as is "boa" and the groups that "boa" belongs to include "web-stuff" then files/directories accessible by users with group "web-stuff" will also be accessible to Boa.

The February 2000 hoo-rah from CERT advisory CA-2000-02 has little to do with Boa. As of version 0.94.4, Boa's escaping rules have been cleaned up a little, but they weren't that bad before. The example CGI programs have been updated to show what effort is needed there. If you write, maintain, or use CGI programs under Boa (or any other server) it's worth your while to read and understand this advisory. The real problem, however, boils down to browser and web page designers emphasizing frills over content and security. The market leading browsers assume (incorrectly) that all web pages are trustworthy.

Next Previous Contents