boa.texi

用于移植到嵌入式linux系统的boa http服务器

 @item BackLog <integer>
 BackLog sets the value sent to listen(2).
 The default value is whatever SO_MAXCONN is defined to.
 
 @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 ServerRoot <root>
 This parameter is analogous to the '-c' command line option -- it sets
 a default server root. The server root is where Boa expects to find
 boa.conf, and from which all relative alias paths are constructed.
 
 @item UseLocaltime
 Tell Boa to output time in the local time zone instead of GMT (UTC).
 
 @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 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.
 
 @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 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 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.

 @item 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.
 
 @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 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.
 
 @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 DefaultCharset <default charset>
 If set, the default character set will be appended to the 
 Content-Type for all 'text' mime types.
 
 @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. 
  
 @item ScriptAlias <path1> <path2>
  maps a virtual path to a directory for serving scripts. 

 @item SinglePostLimit <integer>
 If defined, the maximum number of bytes that a client may send
 in a POST request. The default is 1024*1024 bytes, or 1 megabyte.
 
 @item CGIPath <string>
 CGIPath sets the string that is used for the 'PATH' environment
 variable for CGIs.  The default is defined in defines.h.
 
 @item 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.
 
 @item MaxConnections <integer>
 MaxConnections defines the maximum number of concurrent connections
 that Boa will handle.  Once Boa reaches this limit, it stops
 accepting connections until the number of active connections goes
 down. The default is the maximum number of available file descriptors.
 
 @item Allow, Deny
 Only supported if Boa is compiled with --enable-access-control. 
 Allow and Deny allows pattern based access control using shell
 wildcards. The string the matching is performed on is the absolute
 filesystem filename. The Allow, Deny directives are processed in
 order until the first match is found, and are processed using fnmatch.
 
 @item Deny <pattern>
  Disallow files matching <pattern>
  
 @item Allow <pattern>
  Allow files matching <pattern>
 
@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