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