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.