\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename boa.info
@settitle The Boa HTTP Daemon
@set UPDATED Last Updated: 2 Jan 2001
@set COPYPHRASE Copyright @copyright{} 1996-2001 Jon Nelson and Larry Doolittle
@set VERSION $Revision: 1.5 $

@paragraphindent asis
@iftex
@parindent 0pt
@end iftex
@c @setchapternewpage odd
@c %**end of header

@iftex
@titlepage
@title The Boa HTTP Daemon
@c @sp 2
@end iftex

@ifinfo
This file documents Boa, an HTTP daemon for UN*X like machines.
@end ifinfo

@html
<h1 align="center">The Boa HTTP Daemon</h1>
<center><img src="boa_banner.png"></center>
@end html

@ifinfo
@dircategory Networking
@direntry
* Boa: (boa).           The Boa Webserver
@end direntry
@end ifinfo

@comment node-name,     next,           previous, up
@node Top, Introduction, , (dir)

Welcome to the documentation for Boa, a high performance
HTTP Server for UN*X-alike computers, covered by the
@uref{Gnu_License,GNU General Public License}.
The on-line, updated copy of this documentation lives at
@uref{http://www.boa.org/,http://www.boa.org/}
@sp 1
@center @value{COPYPHRASE}
@center @value{UPDATED}, @value{VERSION}

@iftex
@end titlepage
@contents
@end iftex

@menu
* Introduction::
* Installation and Usage::
* Limits and Design Philosophy::
* Appendix::

 -- Detailed Node Listing --

Installation

* Files Used by Boa::
* Compile-Time and Command-Line Options::
* boa.conf Directives::
* Security::

Limits and Design Philosophy 

* Limits::
* Differences between Boa and other web servers::
* Unexpected Behavior::

Appendix 

* License::
* Acknowledgments::
* Reference Documents::
* Other HTTP Servers::
* Benchmarks::
* Tools::
* Authors::

@end menu

@comment node-name,     next,           previous, up
@node    Introduction, Installation and Usage,top,top
@chapter Introduction

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 @emph{can't be subverted by a malicious user,} not
@emph{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 (@uref{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 (@email{psp@@well.com}).
It is now being maintained and enhanced by Larry Doolittle
(@email{ldoolitt@@boa.org}) and Jon Nelson
(@email{jnelson@@boa.org}).
Please see the acknowledgement 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.

@comment node-name,     next,           previous, up
@node    Installation and Usage, Limits and Design Philosophy, Introduction,top
@chapter 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.

@menu
* Installation::
* Files Used by Boa::
* Compile-Time and Command-Line Options::
* Security::
@end menu

@comment node-name,     next,           previous, up
@node Installation,Files Used by Boa,,Installation and Usage
@section Installation

@enumerate
 @item Unpack
 @enumerate
  @item Choose, and cd into, a convenient directory for the package.
  @item @kbd{tar -xvzf boa-0.94.tar.gz}, or for those of you with an archaic
(non-GNU) tar; @kbd{gzip -cd &lt; boa-0.94.tar.gz | tar -xvf -}
  @item Read the documentation.  Really.
 @end enumerate
 @item Build
  @enumerate
   @item cd into the @t{src} directory.
   @item (optional) Change the default SERVER_ROOT by setting the #define
    at the top of src/defines.h
   @item Type @kbd{./configure; make}
   @item Report any errors to the maintainers for resolution, or strike
    out on your own.
  @end enumerate
  @item Configure
  @enumerate 
   @item Choose a user and server port under which Boa can run.  The
    traditional port is 80, and user @t{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.
   @item Choose a server root.  The @t{conf} directory within the
    server root must hold your copy of the configuration file
   @emph{boa.conf}
   @item Choose locations for log files, CGI programs (if any), and
    the base of your URL tree.
   @item Set the location of the @t{mime.types} file.
   @item Edit @emph{conf/boa.conf} according to your
    choices above (this file documents itself).  Read through this file
    to see what other features you can configure.
 @end enumerate
 @item Start
  @itemize
   @item 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
    Example: ./boa -c /usr/local/boa
    @end example
  @end itemize
  
 @item Test
  @itemize
   @item At this point the server should run and serve documents.
    If not, check the error_log file for clues.
  @end itemize
  
 @item Install
  @itemize
   @item 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.
  @end itemize
@end enumerate

@comment node-name,     next,           previous, up
@node    Files Used by Boa, Compile-Time and Command-Line Options, Installation,Installation and Usage
@section Files Used by Boa

@ftable @file
@item boa.conf
  This file is the sole configuration file for Boa. The directives in this 
  file are defined in the DIRECTIVES section. 
@item mime.types
  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!)
@end ftable

@comment node-name,     next,           previous, up
@node    Compile-Time and Command-Line Options, boa.conf Directives, Files Used by Boa,Installation and Usage
@section Compile-Time and Command-Line Options

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

@end table

@comment node-name,     next,           previous, up
@node    boa.conf Directives, Security, Compile-Time and Command-Line Options, (top)
@section 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 @file{defines.h}) or specified on the command
line with the @command{-c} option. 

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

@table @option
 @item 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.
 
 @item 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).
  
  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:
  
  @enumerate
   @item Run boa without a "Listen" directive:
    @itemize @bullet
    @item All addresses are treated the same; makes sense if the addresses 
     are localhost, ppp, and eth0.
    @item Use the VirtualHost directive below to point requests to different files.
     Should be good for a very large number of addresses (web hosting clients).
   @end itemize
    @item Run one copy of boa per IP address:
    @itemize @bullet
     @item Each instance has its own configuration with its own
     "Listen" directive.  No big deal up to a few tens of addresses. Nice separation
     between clients.
    @end itemize
  @end enumerate
 
 @item 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. 
 
 @item 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. 
 
 @item ServerAdmin <email address>
 The email address where server problems should be sent. Note: this is not
 currently used.
 
 @item 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. 
 
 @item 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. 
 
 @item 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.
 
 @item 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.
 
 @item ServerName <server_name>
 The name of this server that should be sent back to clients if different
 than that returned by gethostname.
 
 @item 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 
 
 @item DocumentRoot <directory>
 The root directory of the HTML documents. If this does not start with /, 
 it is considered relative to the server root. 
 
 @item UserDir <directory>
 The name of the directory which is appended onto a user's home directory 
 if a ~user request is received. 
 
 @item 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. 
 
 @item 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. 
 
 @item 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.
 
 @item KeepAliveMax <integer>
 Number of KeepAlive requests to allow per connection. Comment out, or set 
 to 0 to disable keepalive processing. 
 
 @item KeepAliveTimeout <integer>
 Number of seconds to wait before keepalive connections time out. 
 
 @item 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!)
 
 @item DefaultType <mime type>
 MIME type used if the file extension is unknown, or there is no file 
 extension. 
 
 @item AddType <mime type> <extension> extension...
 Associates a MIME type 
 with an extension or extensions. 
 
 @item 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.
 
 @item 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. 
  
 @item Alias <path1> <path2>
  aliases one path to another. Of course, symbolic links in the 
  file system work fine too.