| blob | 93146df76f48b36f65bb4ff592632c2da11db5e9 |
1 .\" $NetBSD: bozohttpd.8,v 1.15 2009/05/23 20:26:18 wiz Exp $
2 .\"
3 .\" $eterna: bozohttpd.8,v 1.91 2009/05/23 00:55:22 mrg Exp $
4 .\"
5 .\" Copyright (c) 1997-2009 Matthew R. Green
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
22 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
24 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" SUCH DAMAGE.
28 .\"
29 .Dd May 22, 2009
30 .Dt HTTPD 8
31 .Os
32 .Sh NAME
33 .Nm httpd
34 .Nd hyper text transfer protocol version 1.1 daemon
35 .Sh SYNOPSIS
36 .Nm
37 .Op Fl befHnrsuVX
38 .Op Fl C Ar suffix cgihandler
39 .Op Fl c Ar cgibin
40 .Op Fl I Ar port
41 .Op Fl i Ar address
42 .Op Fl M Ar suffix type encoding encoding11
43 .Op Fl p Ar pubdir
44 .Op Fl S Ar server_software
45 .Op Fl t Ar chrootdir
46 .Op Fl v Ar virtualroot
47 .Op Fl x Ar index
48 .Op Fl Z Ar cert privkey
49 .Ar slashdir
50 .Op Ar myname
51 .Sh DESCRIPTION
52 The
53 .Nm
54 program reads a
55 .Em HTTP
56 request from the standard input, and sends a reply to the standard output.
57 Besides ~user translation and virtual hosting support (see below), all file
58 requests are from
59 .Ar slashdir
60 directory.
61 The server uses
62 .Ar myname
63 as its name, which defaults to the local hostname, obtained from
64 .Xr gethostname 3
65 (but see the
66 .Fl v
67 option for virtual hosting.)
68 .Nm
69 is designed to be small, simple and relatively featureless,
70 hopefully increasing its security.
71 .Ss OPTIONS
72 The following options are available:
73 .Bl -tag -width xxxcgibin
74 .It Fl b
75 This option enables daemon mode, where
76 .Nm
77 detaches from the current terminal, running in the background and
78 servicing HTTP requests.
79 .It Fl C Ar suffix cgihandler
80 This option adds a new CGI handler program for a particular file type.
81 The
82 .Ar suffix
83 should be any normal file suffix, and the
84 .Ar cgihandler
85 should be a full path to an interpreter.
86 This option is the only way to enable CGI programs that exist
87 outside of the cgibin directory to be executed.
88 Multiple
89 .Fl C
90 options may be passed.
91 .It Fl c Ar cgibin
92 This option enables the CGI/1.1 interface.
93 The
94 .Ar cgibin
95 directory is expected to contain the CGI programs to be used.
96 .Nm
97 looks for URL's in the form of
98 .Em /cgi-bin/\*[Lt]scriptname\*[Gt]
99 where
100 .Aq scriptname
101 is a valid CGI program in the
102 .Ar cgibin
103 directory.
104 In other words, all CGI URL's must begin with
105 .Em \%/cgi-bin/ .
106 Note that the CGI/1.1 interface is not available with
107 .Em ~user
108 translation.
109 .It Fl e
110 This option causes
111 .Nm
112 to not clear the environment when used with either the
113 .Fl t
114 or
115 .Fl U
116 options.
117 .It Fl f
118 This option stops the
119 .Fl b
120 flag from
121 .Nm
122 detaching from the tty and going into the background.
123 .It Fl H
124 This option causes directory index mode to hide files and directories
125 that start with a period, except for
126 .Pa .. .
127 Also see
128 .Fl X .
129 .It Fl I Ar port
130 This option is only valid with the
131 .Fl b
132 option.
133 It causes
134 .Ar port
135 to use used as the port to bind daemon mode.
136 The default is the
137 .Dq http
138 port.
139 .It Fl i Ar address
140 This option is only valid with the
141 .Fl b
142 option.
143 It causes
144 .Ar address
145 to use used as the address to bind daemon mode.
146 If otherwise unspecified, the address used to bind is derived from the
147 .Ar myname ,
148 which defaults to the name returned by
149 .Xr gethostname 3 .
150 Only the last
151 .Fl i
152 option is used.
153 .It Fl M Ar suffix type encoding encoding11
154 This option adds a new entry to the table that converts file suffixes to
155 content type and encoding.
156 This option takes four additional arguments containing
157 the file prefix, its
158 .Dq Content-Type ,
159 .Dq Content-Encoding ,
160 and
161 .Dq Content-Encoding
162 for HTTP/1.1 connections, respectively.
163 If any of these are a single dash
164 .Pq Dq - ,
165 the empty string is used instead.
166 Multiple
167 .Fl M
168 options may be passed.
169 .It Fl n
170 This option stops
171 .Nm
172 from doing IP address to name resolution of hosts for setting the
173 .Ev REMOTE_HOST
174 variable before running a CGI program.
175 This option has no effect without the
176 .Fl c
177 option.
178 .It Fl p Ar pubdir
179 This option changes the default user directory for
180 .Em /~user/
181 translations from
182 .Dq public_html
183 to
184 .Ar pubdir .
185 .It Fl r
186 This option forces pages besides the
187 .Dq index.html
188 (see the
189 .Fl X
190 option) page to require that the Referrer: header be present and
191 refer to this web server, otherwise a redirect to the
192 .Dq index.html
193 page will be returned instead.
194 .It Fl S Ar server_software
195 This option sets the internal server version to
196 .Ar server_software .
197 .It Fl s
198 This option forces logging to be set to stderr always.
199 .It Fl t Ar chrootdir
200 When this option is used,
201 .Nm
202 will chroot to the specified directory
203 before answering requests.
204 Every other path should be specified relative
205 to the new root, if this option is used.
206 Note that the current environment
207 is normally replaced with an empty environment with this option, unless the
208 .Fl e
209 option is also used.
210 .It Fl U Ar username
211 This option causes
212 .Nm
213 to switch to the user and the groups of
214 .Ar username
215 after initialization.
216 This option, like
217 .Fl t
218 above, causes
219 .Nm
220 to clear the environment unless the
221 .Fl e
222 option is given.
223 .It Fl u
224 This option enables the transformation of Uniform Resource Locators of
225 the form
226 .Em /~user/
227 into the directory
228 .Pa ~user/public_html
229 (but see the
230 .Fl p
231 option above).
232 .It Fl V
233 This option sets the default virtual host directory to
234 .Ar slashdir .
235 If no directory exists in
236 .Ar virtualroot
237 for the request, then
238 .Ar slashdir
239 will be used.
240 The default behaviour is to return 404 (Not Found.)
241 .It Fl v Ar virtualroot
242 This option enables virtual hosting support.
243 Directories in
244 .Ar virtualroot
245 will be searched for a matching virtual host name, when parsing
246 the HTML request.
247 If a matching name is found, it will be used
248 as both the server's real name,
249 .Op Ar myname ,
250 and as the
251 .Ar slashdir .
252 See the
253 .Sx EXAMPLES
254 section for an example of using this option.
255 .It Fl X
256 This option enables directory indexing.
257 A directory index will be generated only when the default file (i.e.
258 .Pa index.html
259 normally) is not present.
260 .It Fl x Ar index
261 This option changes the default file read for directories from
262 .Dq index.html
263 to
264 .Ar index .
265 .It Fl Z Ar certificate_path privatekey_path
266 This option sets the path to the server certificate file and the private key file
267 in pem format.
268 It also causes
269 .Nm
270 to start SSL mode.
271 .El
272 .Pp
273 Note that in
274 .Nm
275 versions 20031005 and prior that supported the
276 .Fl C
277 and
278 .Fl M
279 options, they took a single space-separated argument that was parsed.
280 since version 20040828, they take multiple options (2 in the case of
281 .Fl C
282 and 4 in the case of
283 .Fl M . )
284 .Ss INETD CONFIGURATION
285 As
286 .Nm
287 uses
288 .Xr inetd 8
289 by default to process incoming TCP connections for HTTP requests
290 (but see the
291 .Fl b
292 option),
293 .Nm
294 has little internal networking knowledge.
295 (Indeed, you can run it on the command line with little change of functionality.)
296 A typical
297 .Xr inetd.conf 5
298 entry would be:
299 .Bd -literal
300 http stream tcp nowait:600 _httpd /usr/libexec/httpd httpd /var/www
301 http stream tcp6 nowait:600 _httpd /usr/libexec/httpd httpd /var/www
302 .Ed
303 .Pp
304 This would serve web pages from
305 .Pa /var/www
306 on both IPv4 and IPv6 ports.
307 The
308 .Em :600
309 changes the
310 requests per minute to 600, up from the
311 .Xr inetd 8
312 default of 40.
313 .Pp
314 Using the
315 .Nx
316 .Xr inetd 8 ,
317 you can provide multiple IP-address based HTTP servers by having multiple
318 listening ports with different configurations.
319 .Ss NOTES
320 This server supports the
321 .Em HTTP/0.9 ,
322 .Em HTTP/1.0 ,
323 and
324 .Em HTTP/1.1
325 standards.
326 Support for these protocols is very minimal and many optional features are
327 not supported.
328 .Pp
329 .Nm
330 can be compiled without CGI support (NO_CGIBIN_SUPPORT), user
331 transformations (NO_USER_SUPPORT), directory index support (NO_DIRINDEX_SUPPORT),
332 daemon mode support (NO_DAEMON_MODE), and dynamic MIME content
333 (NO_DYNAMIC_CONTENT), and SSL support (NO_SSL_SUPPORT) by defining the listed
334 macros when building
335 .Nm .
336 .Ss HTTP BASIC AUTHORISATION
337 .Nm
338 has support for HTTP Basic Authorisation.
339 If a file named
340 .Pa .htpasswd
341 exists in the directory of the current request,
342 .Nm
343 will restrict access to documents in that directory
344 using the RFC 2617 HTTP
345 .Dq Basic
346 authentication scheme.
347 .Pp
348 Note:
349 This does not recursively protect any sub-directories.
350 .Pp
351 The
352 .Pa .htpasswd
353 file contains lines delimited with a colon containing
354 usernames and passwords hashed with
355 .Xr crypt 3 ,
356 for example:
357 .Bd -literal
358 heather:$1$pZWI4tH/$DzDPl63i6VvVRv2lJNV7k1
359 jeremy:A.xewbx2DpQ8I
360 .Ed
361 .Pp
362 On
363 .Nx ,
364 the
365 .Xr pwhash 1
366 utility may be used to generate hashed passwords.
367 .Pp
368 While
369 .Nm
370 distributed with
371 .Nx
372 has support for HTTP Basic Authorisation enabled by default,
373 in the portable distribution it is excluded.
374 Compile
375 .Nm
376 with
377 .Dq -DDO_HTPASSWD
378 on the compiler command line to enable this support.
379 It may require linking with the crypt library, using
380 .Dq -lcrypt .
381 .Ss SSL SUPPORT
382 .Nm
383 has support for SSLv2, SSLv3, and TLSv1 protocols that is included by
384 default.
385 It requires linking with the crypto and ssl library, using
386 .Dq -lcrypto -lssl .
387 To disable SSL SUPPORT compile
388 .Nm
389 with
390 .Dq -DNO_SSL_SUPPORT
391 on the compiler command line.
392 .Sh FILES
393 .Nm
394 looks for a couple of special files in directories that allow certain features
395 to be provided on a per-directory basis.
396 In addition to the
397 .Pa .htpasswd
398 used by HTTP basic authorisation,
399 if a
400 .Pa .bzdirect
401 file is found (contents are irrelevant)
402 .Nm
403 will allow direct access even with the
404 .Fl r
405 option.
406 If a
407 .Pa .bzredirect
408 symbolic link is found,
409 .Nm
410 will perform a smart redirect to the target of this symlink.
411 The target is assumed to live on the same server.
412 If a
413 .Pa .bzabsredirect
414 symbolic link is found,
415 .Nm
416 will redirect to the absolute url pointed to by this symlink.
417 This is useful to redirect to different servers.
418 .Sh EXAMPLES
419 To configure set of virtual hosts, one would use an
420 .Xr inetd.conf 5
421 entry like:
422 .Bd -literal
423 http stream tcp nowait:600 _httpd /usr/libexec/httpd httpd -v /var/vroot /var/www
424 .Ed
425 .Pp
426 and inside
427 .Pa /var/vroot
428 create a directory (or a symlink to a directory) with the same name as
429 the virtual host, for each virtual host.
430 Lookups for these names are done in a case-insensitive manner.
431 .Pp
432 To use
433 .Nm
434 with PHP, one must use the
435 .Fl C
436 option to specify a CGI handler for a particular file type.
437 Typically this, this will be like:
438 .Bd -literal
439 httpd -C .php /usr/pkg/bin/php /var/www
440 .Ed
441 .Sh SEE ALSO
442 .Xr inetd.conf 5 ,
443 .Xr inetd 8
444 .Sh HISTORY
445 The
446 .Nm
447 program is actually called
448 .Dq bozohttpd .
449 It was first written in perl, based on another perl http server
450 called
451 .Dq tinyhttpd .
452 It was then rewritten from scratch in perl, and then once again in C.
453 From
454 .Dq bozohttpd
455 version 20060517, it has been integrated into
456 .Nx .
457 The focus has always been simplicity and security, with minimal features
458 and regular code audits.
459 This manual documents
460 .Nm
461 version 20090522.
462 .Sh AUTHORS
463 .Nm
464 was written by Matthew R. Green
465 .Aq mrg@eterna.com.au .
466 .Pp
467 The large list of contributors includes:
468 .Bl -dash
469 .It
470 Arnaud Lacombe
471 .Aq alc@netbsd.org
472 provided some clean up for memory leaks
473 .It
474 Christoph Badura
475 .Aq bad@bsd.de
476 provided Range: header support
477 .It
478 Julian Coleman
479 .Aq jdc@coris.org.uk
480 provided an IPv6 bugfix
481 .It
482 Chuck Cranor
483 .Aq chuck@research.att.com
484 provided cgi-bin support fixes, and more
485 .It
486 DEGROOTE Arnaud
487 .Aq degroote@netbsd.org
488 provided a fix for daemon mode
489 .It
490 Andrew Doran
491 .Aq ad@netbsd.org
492 provided directory indexing support
493 .It
494 Per Ekman
495 .Aq pek@pdc.kth.se
496 provided a fix for a minor (non-security) buffer overflow condition
497 .It
498 Jun-ichiro itojun Hagino, KAME
499 .Aq itojun@iijlab.net
500 provided initial IPv6 support
501 .It
502 Martin Husemann
503 .Aq martin@netbsd.org
504 provided .bzabsredirect support
505 .It
506 Arto Huusko
507 .Aq arto.huusko@pp2.inet.fi
508 provided fixes cgi-bin
509 .It
510 Roland Illig
511 .Aq roland.illig@gmx.de
512 provided some off-by-one fixes
513 .It
514 Zak Johnson
515 .Aq zakj@nox.cx
516 provided cgi-bin enhancements
517 .It
518 Nicolas Jombart
519 .Aq ecu@ipv42.net
520 provided fixes for HTTP basic authorisation support
521 .It
522 Thomas Klausner
523 .Aq wiz@danbala.ifoer.tuwien.ac.at
524 provided many fixes and enhancements for the man page
525 .It
526 Johnny Lam
527 .Aq jlam@netbsd.org
528 provided man page fixes
529 .It
530 Luke Mewburn
531 .Aq lukem@netbsd.org
532 provided many various fixes, including cgi-bin fixes and enhancements,
533 HTTP basic authorisation support and much code clean up
534 .It
535 Jeremy C. Reed
536 .Aq reed@netbsd.org
537 provided several clean up fixes, and man page updates
538 .It
539 Scott Reynolds
540 .Aq scottr@netbsd.org
541 provided various fixes
542 .It
543 Tyler Retzlaff
544 .Aq rtr@eterna.com.au
545 provided SSL support, cgi-bin fixes and much other random other stuff
546 .It
547 Steve Rumble
548 .Aq rumble@ephemeral.org
549 provided the
550 .Fl V
551 option.
552 .It
553 Joerg Sonnenberger
554 .Aq joerg@netbsd.org
555 implemented If-Modified-Since support
556 .It
557 ISIHARA Takanori
558 .Aq ishit@oak.dti.ne.jp
559 provided a man page fix
560 .It
561 Holger Weiss
562 .Aq holger@CIS.FU-Berlin.DE
563 provided http authorisation fixes
564 .It
565 .Aq xs@kittenz.org
566 provided chroot and change-to-user support, and other various fixes
567 .It
568 Coyote Point provided various CGI fixes
569 .El
570 .Pp
571 There are probably others I have forgotten (let me know if you care)
572 .Pp
573 Please send all updates to
574 .Nm
575 to
576 .Aq mrg@eterna.com.au
577 for inclusion in future releaases.
578 .Sh BUGS
579 .Nm
580 does not handled HTTP/1.1 chunked input from the client yet.