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