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