197 lines
7.0 KiB
Groff
197 lines
7.0 KiB
Groff
.TH BOA 8 "Jan 22 2000" "Version 0.94"
|
|
.SH NAME
|
|
.B boa \- a single\-tasking high performance http server
|
|
.SH SYNOPSIS
|
|
.B boa
|
|
.RB [ -c
|
|
.IR server_root ]
|
|
.RB [ -r
|
|
.IR chroot ]
|
|
.RB [ -d ]
|
|
.SH 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.
|
|
.PP
|
|
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.
|
|
.SH OPTIONS
|
|
.IP \fB-d\fR
|
|
instruct Boa not to fork itself (non-daemonize).
|
|
|
|
.IP "\fB-c \fIserver_root\fR"
|
|
choose a server root overriding the default SERVER_ROOT #define in
|
|
.I defines.h
|
|
|
|
The server root must hold your local copy of the configuration file
|
|
|
|
.IP "\fB-r \fIchroot\fR"
|
|
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.
|
|
|
|
.SH FILES
|
|
.TP
|
|
\fBboa.conf\fR \- the sole configuration file for Boa.
|
|
The directives in this file are defined in the
|
|
.B DIRECTIVES
|
|
section.
|
|
|
|
.TP
|
|
\fBmime.types\fR \- the
|
|
MimeTypes <filename>
|
|
defines what Content-Type Boa will send in an HTTP/1.0
|
|
or better transaction.
|
|
.SH 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.
|
|
.PP
|
|
Note: the "ServerRoot" is not in this configuration file. It can be compiled
|
|
into the server (see
|
|
.I defines.h
|
|
) or specified on the command line with the
|
|
.B -c
|
|
option.
|
|
|
|
The following directives are contained in the
|
|
.I boa.conf
|
|
file, and most, but not all, are required.
|
|
.TP
|
|
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.
|
|
.TP
|
|
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.
|
|
.TP
|
|
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.
|
|
.TP
|
|
ServerAdmin <email address>
|
|
The email address where server problems should be sent.
|
|
Note: this is not currently used.
|
|
.TP
|
|
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.
|
|
.TP
|
|
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.
|
|
.TP
|
|
VerboseCGILogs
|
|
This is a logical switch and does not take any parameters.
|
|
Comment out to disable.
|
|
.TP
|
|
ServerName <server_name>
|
|
The name of this server that should be sent back to
|
|
clients if different than that returned by gethostname.
|
|
.Tp
|
|
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
|
|
.TP
|
|
DocumentRoot <directory>
|
|
The root directory of the HTML documents. If this does not start with
|
|
/, it is considered relative to the server root.
|
|
.TP
|
|
UserDir <directory>
|
|
The name of the directory which is appended onto a user's home directory if a
|
|
~user request is received.
|
|
.TP
|
|
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.
|
|
.TP
|
|
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.
|
|
.TP
|
|
KeepAliveMax <integer>
|
|
Number of KeepAlive requests to allow per connection. Comment out, or set
|
|
to 0 to disable keepalive processing.
|
|
.TP
|
|
KeepAliveTimeout <integer>
|
|
Number of seconds to wait before keepalive connections time out.
|
|
.TP
|
|
MimeTypes <file>
|
|
The location of the
|
|
.I 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!)
|
|
.TP
|
|
DefaultType <mime type>
|
|
MIME type used if the file extension is unknown, or there is no file extension.
|
|
.TP
|
|
AddType <mime type> <extension> [extension...]
|
|
Associates a MIME type with an extension or extensions.
|
|
.TP
|
|
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.
|
|
.PP
|
|
Please see the included
|
|
.I boa.conf
|
|
for defaults and examples.
|
|
.SH 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>
|
|
.PP
|
|
Version 0.92 was released by Larry Doolittle on
|
|
December 12, 1996.
|
|
.PP
|
|
Version 0.93 was the development version of 0.94.
|
|
.PP
|
|
Version 0.94 was released 22 Jan 2000.
|
|
.SH BUGS
|
|
There are probably bugs, but we are not aware of any at this time.
|
|
.SH 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>.
|
|
.PP
|
|
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.
|
|
.SH LICENSE
|
|
This program is distributed under the GNU General Public License, as noted in
|
|
each source file.
|