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.

Version 0.94                                       Jan 22 2000                                            BOA(8)