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