boa

BOA(8)                      System Manager's Manual                     BOA(8)



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)