1BOA(8) System Manager's Manual BOA(8)
2
6 boa - a single-tasking high performance http server
7
9 boa [-c server_root] [-r chroot] [-d]
10
12 Boa is a single-tasking HTTP server. That means that unlike traditional
13 web servers, it does not fork for each incoming connection, nor does it
14 fork many copies of itself to handle multiple connections. It inter‐
15 nally multiplexes all of the ongoing HTTP connections, and forks only
16 for CGI programs (which must be separate processes.) Preliminary tests
17 show Boa is more than twice as fast as Apache.
18 The primary design goals of Boa are speed and security. Security, in
20 the sense of "can't be subverted by a malicious user", not "fine
21 grained access control and encrypted communications". Boa is not
22 intended as a feature-packed server; if you want one of those, check
23 out WN from John Franks. Modifications to Boa that improve its speed,
24 security, robustness, and portability, are eagerly sought. Other fea‐
25 tures may be added if they can be achieved without hurting the primary
26 goals.
27
29 -d instruct Boa not to fork itself (non-daemonize).
30 -c server_root
33 choose a server root overriding the default SERVER_ROOT #define
34 in defines.h
35 The server root must hold your local copy of the configuration
37 file
38 -r chroot
41 instruct Boa where to chdir and chroot to. The chdir/chroot is
42 done before the configuration file is read, or any log files are
43 opened.
44
47 boa.conf - the sole configuration file for Boa.
48 The directives in this file are defined in the DIRECTIVES sec‐
49 tion.
50 mime.types - the
53 MimeTypes <filename> defines what Content-Type Boa will send in
54 an HTTP/1.0 or better transaction.
55
57 The Boa configuration file is parsed with a lex/yacc or flex/bison gen‐
58 erated parser. If it reports an error, the line number will be pro‐
59 vided; it should be easy to spot. The syntax of each of these rules is
60 very simple, and they can occur in any order. Where possible, these
61 directives mimic those of NCSA httpd 1.3; We saw no reason to introduce
62 gratuitous differences.
63 Note: the "ServerRoot" is not in this configuration file. It can be
65 compiled into the server (see defines.h ) or specified on the command
66 line with the -c option.
67 The following directives are contained in the boa.conf file, and most,
69 but not all, are required.
70 Port <integer>
72 This is the port that Boa runs on. The default port for http
73 servers is 80. If it is less than 1024, the server must be
74 started as root.
75 User <user name or UID>
77 The name or UID the server should run as. For Boa to attempt
78 this, the server must be started as root.
79 Group <group name or GID>
81 The group name or GID the server should run as. For Boa to
82 attempt this, the server must be started as root.
83 ServerAdmin <email address>
85 The email address where server problems should be sent. Note:
86 this is not currently used.
87 PidFile <filename>
89 Where to put the pid of the process. Comment out to write no
90 pid file. Note: Because Boa drops privileges at startup, and
91 the pid file is written by the UID/GID before doing so, Boa does
92 not attempt removal of the pid file.
93 ErrorLog <filename>
95 The location of the error log file. If this does not start with
96 /, it is considered relative to the server root. Set to
97 /dev/null if you don't want errors logged.
98 AccessLog <filename>
100 The location of the access log file. If this does not start
101 with /, it is considered relative to the server root. Comment
102 out or set to /dev/null (less effective) to disable access log‐
103 ging.
104 VerboseCGILogs
106 This is a logical switch and does not take any parameters. Com‐
107 ment out to disable.
108 CGILog <filename>
110 The location of the CGI error log file. If this does not start
111 with /, it is considered relative to the server root. If speci‐
112 fied, this is the file that the stderr of CGIs is tied to,
113 *instead* of to the ErrorLog.
114 CGIumask <umask>
116 The CGIumask is set immediately before execution of the CGI.
117 The default value is 027. The number must be interpretable unam‐
118 biguously by the C function strtol. No base is specified, so one
119 may use a hexadecimal, decimal, or octal number if it is pre‐
120 fixed accordingly.
121 ServerName <server_name>
123 The name of this server that should be sent back to clients if
124 different than that returned by gethostname.
125 VirtualHost
127 This is a logical switch and does not take any parameters. Com‐
128 ment out to disable. Given DocumentRoot /var/www, requests on
129 interface 'A' or IP 'IP-A' become /var/www/IP-A. Example:
130 http://localhost/ becomes /var/www/127.0.0.1
131 VHostRoot <directory>
133 The root location for all virtually hosted data Comment out to
134 disable. Incompatible with 'Virtualhost' and 'DocumentRoot'!!
135 Given VHostRoot /var/www, requests to host foo.bar.com, where
136 foo.bar.com is ip a.b.c.d, become /var/www/a.b.c.d/foo.bar.com
137 Hostnames are "cleaned", and must conform to the rules specified
138 in rfc1034, which are be summarized here:
139 Hostnames must start with a letter, end with a letter or digit,
141 and have as interior characters only letters, digits, and
142 hyphen. Hostnames must not exceed 63 characters in length.
143 DefaultVHost <hostname>
145 Define this in order to have a default hostname when the client
146 does not specify one, if using VirtualHostName. If not speci‐
147 fied, the word "default" will be used for compatibility with
148 older clients.
149 DocumentRoot <directory>
151 The root directory of the HTML documents. If this does not start
152 with /, it is considered relative to the server root.
153 UserDir <directory>
155 The name of the directory which is appended onto a user's home
156 directory if a ~user request is received.
157 DirectoryIndex <filename>
159 Name of the file to use as a pre-written HTML directory index.
160 Please make and use these files. On the fly creation of direc‐
161 tory indexes can be slow.
162 DirectoryMaker <directory>
164 Name of the program used to generate on-the-fly directory list‐
165 ings. The program must take one or two command-line arguments,
166 the first being the directory to index (absolute), and the sec‐
167 ond, which is optional, contains what Boa would have the "title"
168 of the document be. Comment out if you don't want on the fly
169 directory listings. If this does not start with /, it is con‐
170 sidered relative to the server root.
171 KeepAliveMax <integer>
173 Number of KeepAlive requests to allow per connection. Comment
174 out, or set to 0 to disable keepalive processing.
175 KeepAliveTimeout <integer>
177 Number of seconds to wait before keepalive connections time out.
178 MimeTypes <file>
180 The location of the mime.types file. If this does not start
181 with /, it is considered relative to the server root. Set to
182 /dev/null if you do not want to load a mime types file. Do *not*
183 comment out (better use AddType!)
184 DefaultType <mime type>
186 MIME type used if the file extension is unknown, or there is no
187 file extension.
188 AddType <mime type> <extension> [extension...]
190 Associates a MIME type with an extension or extensions.
191 Redirect, Alias, and ScriptAlias <path1> <path2>
193 Redirect, Alias, and ScriptAlias all have the same semantics --
194 they match the beginning of a request and take appropriate
195 action. Use Redirect for other servers, Alias for the same
196 server, and ScriptAlias to enable directories for script execu‐
197 tion.
198 Redirect allows you to tell clients about documents which used
200 to exist in your server's namespace, but do not anymore. This
201 allows you tell the clients where to look for the relocated doc‐
202 ument.
203 Alias aliases one path to another. Of course, symbolic links in
205 the file system work fine too.
206 ScriptAlias maps a virtual path to a directory for serving
208 scripts.
209 Please see the included boa.conf for defaults and examples.
211
213 Like the Linux kernel, even numbered versions are "stable", and odd
214 numbered versions are "unstable", or rather, "development". Versions
215 0.91 and 0.91beta of Boa were released by Paul Phillips
216 <paulp@go2net.com>
217 Version 0.92 was released by Larry Doolittle on December 12, 1996.
219 Version 0.93 was the development version of 0.94.
221 Version 0.94 was released 22 Jan 2000.
223
225 There are probably bugs, but we are not aware of any at this time.
226
228 Boa was created by Paul Phillips <paulp@go2net.com>. It is now being
229 maintained and enhanced by Larry Doolittle <ldoolitt@boa.org> and Jon
230 Nelson <jnelson@boa.org>.
231 Linux is the development platform at the moment, other OS's are known
233 to work. If you'd like to contribute to this effort, contact Larry or
234 Jon via e-mail.
235
237 This program is distributed under the GNU General Public License, as
238 noted in each source file.
239Version 0.94 Jan 22 2000 BOA(8)