Welcome to the documentation for Boa, a high performance HTTP Server for UN*X-alike computers, covered by the GNU General Public License. The on-line, updated copy of this documentation lives at http://www.boa.org/
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 (http://hopf.math.nwu.edu/) 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 (psp@well.com). It is now being maintained and enhanced by Larry Doolittle (ldoolitt@boa.org) and Jon Nelson (jnelson@boa.org). Please see the acknowledgment section for further details.
GNU/Linux is the development platform at the moment, other OS’s are known to work. If you’d like to contribute to this effort, contact Larry or Jon via e-mail.
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.
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.
mime.types file.
Example: ./boa -c /usr/local/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. Set to /dev/null if you do not want to load a mime types file. Do *not* comment out (better use AddType!)
The default server root as #defined by SERVER_ROOT in defines.h can be overridden on the command line 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
The Boa configuration file is parsed with a custom 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.
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.
The Internet address to bind(2) to, in quadded-octet form (numbers). If you leave it out, it binds to all addresses (INADDR_ANY).
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.
You only get one "Listen" directive, if you want service on multiple IP addresses, you have three choices:
BackLog sets the value sent to listen(2). The default value is whatever SO_MAXCONN is defined to.
The name or UID the server should run as. For Boa to attempt this, the server must be started as root.
The group name or GID the server should run as. For Boa to attempt this, the server must be started as root.
The email address where server problems should be sent. Note: this is not currently used.
This parameter is analogous to the ’-c’ command line option – it sets a default server root. The server root is where Boa expects to find boa.conf, and from which all relative alias paths are constructed.
Tell Boa to output time in the local time zone instead of GMT (UTC).
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.
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.
The location of the CGI error log file. If this does not start with /, it is considered relative to the server root. If specified, this is the file that the stderr of CGIs is tied to, *instead* of to the ErrorLog.
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.
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/127.0.0.1
The root location for all virtually hosted data. Comment out to disable. Incompatible with ’Virtualhost’ and ’DocumentRoot’!! Given VHostRoot /var/www, requests to host foo.bar.com, where foo.bar.com is ip a.b.c.d, become /var/www/a.b.c.d/foo.bar.com Hostnames are "cleaned", and must conform to the rules specified in rfc1034, which are be summarized here:
Hostnames must start with a letter, end with a letter or digit, and have as interior characters only letters, digits, and hyphen. Hostnames must not exceed 63 characters in length.
Define this in order to have a default hostname when the client does not specify one, if using VirtualHostName. If not specified, the word "default" will be used for compatibility with older clients.
The root directory of the HTML documents. If this does not start with /, it is considered relative to the server root.
The name of the directory which is appended onto a user’s home directory if a ~user request is received.
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.
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: 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.
Where to put the pid of the process. Comment out to write no pid file. Note: Because Boa drops privileges at startup, and the pid file is written by the UID/GID before doing so, Boa does not attempt removal of the pid file.
Number of KeepAlive requests to allow per connection. Comment out, or set to 0 to disable keepalive processing.
Number of seconds to wait before keepalive connections time out.
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!)
MIME type used if the file extension is unknown, or there is no file extension.
If set, the default character set will be appended to the Content-Type for all ’text’ mime types.
Associates a MIME type with an extension or extensions.
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.
If defined, the maximum number of bytes that a client may send in a POST request. The default is 1024*1024 bytes, or 1 megabyte.
CGIPath sets the string that is used for the ’PATH’ environment variable for CGIs. The default is defined in defines.h.
The CGIumask is set immediately before execution of the CGI. The default value is 027. The number must be interpretable unambiguously by the C function strtol. No base is specified, so one may use a hexadecimal, decimal, or octal number if it is prefixed accordingly.
MaxConnections defines the maximum number of concurrent connections that Boa will handle. Once Boa reaches this limit, it stops accepting connections until the number of active connections goes down. The default is the maximum number of available file descriptors.
Only supported if Boa is compiled with –enable-access-control. Allow and Deny allows pattern based access control using shell wildcards. The string the matching is performed on is the absolute filesystem filename. The Allow, Deny directives are processed in order until the first match is found, and are processed using fnmatch.
Disallow files matching <pattern>
Allow files matching <pattern>
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.
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 others that haven’t been encountered yet.
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).
Writing a nonblocking gethostbyaddr is a difficult and not very enjoyable task. Paul Phillips 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.
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.
See the end of examples/cgi-test.cgi.
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.
Since a file descriptor is needed for every ongoing connection
(two for non-nph CGIs, directories, and automatic gunzipping of files),
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 - GNU/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:
The REMOTE_HOST environment variable is not set for CGI programs, for reasons already described. 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.
We don’t like them, and they are too slow to parse. We will consider more efficient alternatives.
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. If Boa is compiled with –enable-access-control, access control is supported using the Allow, Deny directives.
There is no option to run chrooted. If anybody wants this, and is willing to try out experimental code, contact the maintainers.
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.
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 odd combinations of "../" ’s.
Note: As of version 0.95.0 (unreleased) the URL parser has been rewritten and *does* correctly handle relative URLs.
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. * */
Paul Phillips wrote the first versions of Boa, up to and including version 0.91. Version 0.92 of Boa was officially released December 1996 by Larry Doolittle. Version 0.93 was the development version of 0.94, which was released in February 2000.
The Boa Webserver is currently (Feb 2000) maintained and enhanced by Larry Doolittle (ldoolitt@boa.org) and Jon Nelson (jnelson@boa.org).
We would like to thank Russ Nelson (nelson@crynwr.com) for hosting the web site.
We would also like to thank Paul Phillips for writing code that is worth maintaining and supporting.
Many people have contributed to Boa, but instead of listing them here, their names and specific contributions have been listed in the CREDITS file.
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.
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.
Also see Yahoo’s List
http://www.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/
For Unix-alike platforms, with published source code.
Also worth mentioning is Zeus.
It is commercial, with a free demo, so it doesn’t belong on the list above.
Zeus seems to be based on technology similar to Boa and thttpd,
but with more bells and whistles.
http://www.zeus.co.uk/products/server/
Note: References last checked: 06 October 1997