boa.texi

ｂｏａ：著名嵌入式系统网页服务器源代码。

 @item ScriptAlias <path1> <path2>
  maps a virtual path to a directory for serving scripts. 
@end table

@comment node-name,     next,           previous, up
@node    Security, , boa.conf Directives, Installation and Usage
@section Security

Boa has been designed to use the existing file system security.   In
@file{boa.conf}, the directives @emph{user} and 
@emph{group} determine who Boa will run as, if launched by root.
By default, the user/group is nobody/nogroup.  This allows quite a bit
of flexibility.  For example, if you want to disallow access to otherwise
accessible directories or files, simply make them inaccessible to 
nobody/nogroup. If the user that Boa runs as is "boa" and the groups that 
"boa" belongs to include "web-stuff" then files/directories accessible 
by users with group "web-stuff" will also be accessible to Boa.

The February 2000 hoo-rah from 
@uref{http://www.cert.org/advisories/CA-2000-02.html,CERT advisory CA-2000-02}
has little to do with Boa.  As of version 0.94.4, Boa's escaping rules have 
been cleaned up a little, but they weren't that bad before.  The example CGI
programs have been updated to show what effort is needed there.  If you
write, maintain, or use CGI programs under Boa (or any other server) it's
worth your while to read and understand this advisory.  The real problem,
however, boils down to browser and web page designers emphasizing frills
over content and security.  The market leading browsers assume (incorrectly)
that all web pages are trustworthy.

@comment node-name,     next,           previous, up
@node    Limits and Design Philosophy,Appendix, Installation and Usage,top
@chapter Limits and Design Philosophy

There are many issues that become more difficult to resolve in a single 
tasking web server than in the normal forking model.  Here is a partial 
list -- there are probably others that haven't been encountered yet.

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

@comment node-name,     next,           previous, up
@node    Limits,Differences between Boa and other web servers,,Limits and Design Philosophy
@section Limits

@itemize @bullet
 @item Slow file systems
 
 The file systems being served should be much faster than the
 network connection to the HTTP requests, or performance will suffer.
 For instance, if a document is served from a CD-ROM, the whole server
 (including all other currently incomplete data transfers) will stall
 while the CD-ROM spins up.  This is a consequence of the fact that Boa
 mmap()'s each file being served, and lets the kernel read and cache
 pages as best it knows how.  When the files come from a local disk
 (the faster the better), this is no problem, and in fact delivers
 nearly ideal performance under heavy load.  Avoid serving documents
 from NFS and CD-ROM unless you have even slower inbound net
 connections (e.g., POTS SLIP).
 
 @item DNS lookups
 
 Writing a nonblocking gethostbyaddr is a difficult and not very
 enjoyable task.  Paul Phillips experimented with several methods, 
 including a separate logging process, before removing hostname 
 lookups entirely. There is a companion program with Boa 
 @file{util/resolver.pl} that will postprocess the logfiles and 
 replace IP addresses with hostnames, which is much faster no matter 
 what sort of server you run.
 
 @item Identd lookups
 
 Same difficulties as hostname lookups; not included.
 Boa provides a REMOTE_PORT environment variable, in addition
 to REMOTE_ADDR, so that a CGI program can do its own ident.
 See the end of @t{examples/cgi-test.cgi}.

 @item Password file lookups via NIS
 
 If users are allowed to serve HTML from their home directories,
 password file lookups can potentially block the process.  To lessen
 the impact, each user's home directory is cached by Boa so it need
 only be looked up once.
 
 @item Running out of file descriptors
 
 Since a file descriptor is needed for every ongoing connection
 (two for non-nph CGIs, directories, and automatic gunzipping of files),
 it is possible though highly improbable to run out of file
 descriptors.  The symptoms of this conditions may vary with
 your particular unix variant, but you will probably see log
 entries giving an error message for @t{accept}.
 Try to build your kernel to give an adequate number for
 your usage - GNU/Linux provides 256 out of the box, more than
 enough for most people.
@end itemize

@comment node-name,     next,           previous, up
@node    Differences between Boa and other web servers,Unexpected Behavior,Limits,Limits and Design Philosophy
@section Differences between Boa and other web servers

In the pursuit of speed and simplicity, some aspects of Boa differ
from the popular web servers.  In no particular order:

@itemize @bullet
 @item @var{REMOTE_HOST} environment variable not set for CGI programs
 
  The @var{REMOTE_HOST} environment variable is not set for CGI programs,
  for reasons already described.  This is easily worked around because the
  IP address is provided in the @var{REMOTE_HOST} variable, so (if the CGI
  program actually cares) gethostbyaddr or a variant can be used.
  
 @item There are no server side includes (@acronym{SSI}) in Boa
 
  We don't like them, and they are too slow to parse.  We will consider
  more efficient alternatives.
  
 @item There are no access control features
 
  Boa will follow symbolic links, and serve any file that it can
  read.  The expectation is that you will configure Boa to run as user
  "nobody", and only files configured world readable will come
  out.
  
 @item No chroot option
 
  There is no option to run chrooted.  If anybody wants this, and is
  willing to try out experimental code, contact the maintainers.
@end itemize

@comment node-name,     next,           previous, up
@node    Unexpected Behavior,,Differences between Boa and other web servers,Limits and Design Philosophy
@section Unexpected Behavior

@itemize @bullet
 @item SIGHUP handling
 
 Like any good server, Boa traps SIGHUP and rereads @file{boa.conf}.
 However, under normal circumstances, it has already given away
 permissions, so many items listed in @file{boa.conf} can not take effect.
 No attempt is made to change uid, gid, log files, or server port.
 All other configuration changes should take place smoothly.
 
 @item Relative URL handling
 
 Not all browsers handle relative URLs correctly.  Boa will not
 cover up for this browser bug, and will typically report 404 Not Found
 for URL's containing odd combinations of "../" 's.
 
 Note: As of version 0.95.0 (unreleased) the URL parser has been 
 rewritten and *does* correctly handle relative URLs. 
@end itemize

@comment node-name,     next,           previous, up
@node     Appendix,,Limits and Design Philosophy,top
@appendix Appendix

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

@comment node-name,     next,           previous, up
@node    License,Acknowledgments,,Appendix
@section License

This program is distributed under the
 @uref{http://www.gnu.org/copyleft/gpl.html,GNU General Public License}.
as noted in each source file:
@*

@smallexample
/*
 *  Boa, an http server
 *  Copyright (C) 1995 Paul Phillips <psp@@well.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 1, or (at your option)
 *  any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 */
 
@end smallexample

@comment node-name,     next,           previous, up
@node    Acknowledgments,Reference Documents,License,Appendix
@section Acknowledgments

Paul Phillips wrote the first versions of Boa, up to and including
version 0.91.  Version 0.92 of Boa was officially released December 1996
by Larry Doolittle.  Version 0.93 was the development version of 0.94,
which was released in February 2000.

The Boa Webserver is currently (Feb 2000) maintained and enhanced by 
Larry Doolittle (@email{ldoolitt@@boa.org}) 
and Jon Nelson (@email{jnelson@@boa.org}).

We would like to thank Russ Nelson (@email{nelson@@crynwr.com})
for hosting the @uref{http://www.boa.org,web site}.

We would also like to thank Paul Philips for writing code that is
worth maintaining and supporting.

Many people have contributed to Boa, including (but not
limited to) Charles F. Randall (@email{randall@@goldsys.com})
Christoph Lameter (@email{<chris@@waterf.org>}), 
Russ Nelson (@email{<nelson@@crynwr.com>}), Alain Magloire
(@email{<alain.magloire@@rcsm.ee.mcgill.ca>}),
and more recently, M. Drew Streib (@email{<dtype@@linux.com>}).

Paul Phillips records his acknowledgments as follows: 
@quotation
Thanks to everyone in the WWW community, in general a great bunch of people.
Special thanks to Clem Taylor (@email{<ctaylor@@eecis.udel.edu>}), who
provided invaluable feedback on many of my ideas, and offered good
ones of his own.  Also thanks to John Franks, author of wn, for
writing what I believe is the best webserver out there.
@end quotation

@comment node-name,     next,           previous, up
@node Reference Documents,Other HTTP Servers,Acknowledgments,Appendix
@section Reference Documents

Links to documents relevant to 
@uref{http://www.boa.org/,Boa}
development and usage.  Incomplete, we're still working on this.
NCSA has a decent 
@uref{http://hoohoo.ncsa.uiuc.edu/docs/Library.html,page} along
these lines, too.

Also see Yahoo's List
@* @uref{http://www.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/}

@itemize
 @item W3O HTTP page
 @* @uref{http://www.w3.org/pub/WWW/Protocols/}
 
 @item RFC 1945 HTTP-1.0 (informational)
 @* @uref{http://ds.internic.net/rfc/rfc1945.txt}

 @item IETF Working Group Draft 07 of HTTP-1.1 
 @* @uref{http://www.w3.org/pub/WWW/Protocols/HTTP/1.1/draft-ietf-http-v11-spec-07.txt}

 @item HTTP: A protocol for networked information
 @* @uref{http://www.w3.org/pub/WWW/Protocols/HTTP/HTTP2.html}

 @item The Common Gateway Interface (CGI)
 @* @uref{http://hoohoo.ncsa.uiuc.edu/cgi/overview.html}

 @item RFC 1738 URL syntax and semantics
 @* @uref{http://ds.internic.net/rfc/rfc1738.txt}

 @item RFC 1808 Relative URL syntax and semantics
 @* @uref{http://ds.internic.net/rfc/rfc1808.txt}
@end itemize

@comment node-name,     next,           previous, up
@node    Other HTTP Servers,Benchmarks,Reference Documents,Appendix
@section Other HTTP Servers

For unix-alike platforms, with published source code.

@itemize
 @item tiny/turbo/throttling httpd very similar to Boa, with a throttling
 feature
 @* @uref{http://www.acme.com/software/thttpd/}

 @item Roxen: based on ulpc interpreter, non-forking (interpreter implements
 threading), GPL'd
 @* @uref{http://www.roxen.com/}

 @item WN: featureful, GPL'd
 @* @uref{http://hopf.math.nwu.edu/}

 @item Apache: fast, PD
 @* @uref{http://www.apache.org/}

 @item NCSA: standard, legal status?
 @* @uref{http://hoohoo.ncsa.uiuc.edu/}

 @item CERN: standard, PD, supports proxy
 @* @uref{http://www.w3.org/pub/WWW/Daemon/Status.html}

 @item xs-httpd 2.0: small, fast, pseudo-GPL'd
 @* @uref{http://www.stack.nl/~sven/xs-httpd/}

 @item bozohttpd.tar.gz sources, in perl
 @* @uref{ftp://ftp.eterna.com.au/bozo/bsf/attware/bozohttpd.tar.gz}

 @item Squid is actually an "Internet Object Cache"
 @* @uref{http://squid.nlanr.net/Squid/}
@end itemize

Also worth mentioning is Zeus.
It is commercial, with a free demo, so it doesn't belong on the list above.
Zeus seems to be based on technology similar to Boa and thttpd,
but with more bells and whistles.
@* @uref{http://www.zeus.co.uk/products/server/} 

@comment node-name,     next,           previous, up
@node    Benchmarks,Tools,Other HTTP Servers,Appendix
@section Benchmarks

@itemize
@item ZeusBench (broken link)
@* @uref{http://www.zeus.co.uk/products/server/intro/bench2/zeusbench.shtml}

@item WebBench (binary-ware)
@* @uref{http://web1.zdnet.com/zdbop/webbench/webbench.html}

@item WebStone
@* @uref{http://www.mindcraft.com/benchmarks/webstone/}

@item SpecWeb96
@* @uref{http://www.specbench.org/osg/web96/}
@end itemize

@comment node-name,     next,           previous, up
@node    Tools,Authors,Benchmarks,Appendix
@section Tools

@itemize
@item Analog logfile analyzer
@* @uref{http://www.statslab.cam.ac.uk/@~sret1/analog/}

@item wwwstat logfile analyzer
@* @uref{http://www.ics.uci.edu/pub/websoft/wwwstat/}

@item gwstat wwwstat postprocessor
@* @uref{http://dis.cs.umass.edu/stats/gwstat.html} 

@item The Webalizer logfile analyzer
@* @uref{http://www.usagl.net/webalizer/}

@item cgiwrap
@* @uref{http://www.umr.edu/@~cgiwrap/}

@item suEXEC (Boa would need to be ..umm.. "adjusted" to support this)
@* @uref{http://www.apache.org/docs/suexec.html}
@end itemize

Note: References last checked: 06 October 1997

@comment node-name,     next,           previous, up
@node    Authors,,Tools,Appendix
@section Authors

@itemize
 @item Conversion from linuxdoc SGML to texinfo by Jon Nelson
 @item Conversion to linuxdoc SGML by Jon Nelson
 @item Original HTML documentation by Larry Doolittle
 @item @value{COPYPHRASE}
@end itemize

@c variable
@c @printindex vr
@c concept
@c @printindex cp
@c function
@c @printindex fn
@c key
@c @printindex ky
@c program
@c @printindex pg
@c data type
@c @printindex tp

@bye