NAME¶
boa - a single-tasking high performance http server
SYNOPSIS¶
boa [
-c server_root] [
-r chroot] [
-d]
DESCRIPTION¶
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.) Preliminary tests show Boa is more than twice as fast
as Apache.
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.
OPTIONS¶
- -d
- instruct Boa not to fork itself (non-daemonize).
- -c server_root
- choose a server root overriding the default SERVER_ROOT
#define in defines.h
The server root must hold your local copy of the configuration file
- -r chroot
- instruct Boa where to chdir and chroot to. The chdir/chroot
is done before the configuration file is read, or any log files are
opened.
FILES¶
- boa.conf - 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.
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; We 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.
- 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.
- PidFile <filename>
- 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.
- 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.
- CGILog <filename>
- 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.
- CGIumask <umask>
- 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.
- 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/127.0.0.1
- VHostRoot <directory>
- 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.
- DefaultVHost <hostname>
- 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.
- 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 <directory>
- 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, contains what Boa would have 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.
- 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. Set to
/dev/null if you do not want to load a mime types file. Do *not* comment
out (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.
Redirect 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 aliases one path to another. Of course, symbolic links in the file
system work fine too.
ScriptAlias maps a virtual path to a directory for serving scripts.
Please see the included
boa.conf for defaults and examples.
HISTORY¶
Like the Linux kernel, even numbered versions are "stable", and odd
numbered versions are "unstable", or rather,
"development". Versions 0.91 and 0.91beta of Boa were released by
Paul Phillips <paulp@go2net.com>
Version 0.92 was released by Larry Doolittle on December 12, 1996.
Version 0.93 was the development version of 0.94.
Version 0.94 was released 22 Jan 2000.
BUGS¶
There are probably bugs, but we are not aware of any at this time.
AUTHOR¶
Boa was created by Paul Phillips <paulp@go2net.com>. It is now being
maintained and enhanced by Larry Doolittle <ldoolitt@boa.org> and Jon
Nelson <jnelson@boa.org>.
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.
LICENSE¶
This program is distributed under the GNU General Public License, as noted in
each source file.