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