[BACK]Return to bozohttpd.8 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / libexec / httpd

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>