1.\" $NetBSD: bozohttpd.8,v 1.53 2015/08/13 12:30:08 wiz Exp $ 2.\" 3.\" $eterna: bozohttpd.8,v 1.101 2011/11/18 01:25:11 mrg Exp $ 4.\" 5.\" Copyright (c) 1997-2015 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 May 1, 2015 30.Dt BOZOHTTPD 8 31.Os 32.Sh NAME 33.Nm bozohttpd 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 500.Nm 501was first written in perl, based on another perl http server 502called 503.Dq tinyhttpd . 504It was then rewritten from scratch in perl, and then once again in C. 505From 506.Dq bozohttpd 507version 20060517, it has been integrated into 508.Nx . 509The focus has always been simplicity and security, with minimal features 510and regular code audits. 511This manual documents 512.Nm 513version 20150501. 514.Sh AUTHORS 515.An -nosplit 516.Nm 517was written by 518.An Matthew R. Green 519.Aq Mt mrg@eterna.com.au . 520.Pp 521The large list of contributors includes: 522.Bl -dash 523.It 524.An Marc Balmer 525.Aq Mt mbalmer@NetBSD.org 526added Lua support for dynamic content creation 527.It 528.An Christoph Badura 529.Aq Mt bad@bsd.de 530provided Range: header support 531.It 532.An Sean Boudreau 533.Aq Mt seanb@NetBSD.org 534provided a security fix for virtual hosting 535.It 536.An Julian Coleman 537.Aq Mt jdc@coris.org.uk 538provided an IPv6 bugfix 539.It 540.An Chuck Cranor 541.Aq Mt chuck@research.att.com 542provided cgi-bin support fixes, and more 543.It 544.An Alistair G. Crooks 545.Aq Mt agc@NetBSD.org 546cleaned up many internal interfaces, made 547.Nm 548linkable as a library and provided the Lua binding. 549.It 550.An DEGROOTE Arnaud 551.Aq Mt degroote@NetBSD.org 552provided a fix for daemon mode 553.It 554.An Andrew Doran 555.Aq Mt ad@NetBSD.org 556provided directory indexing support 557.It 558.An Per Ekman 559.Aq Mt pek@pdc.kth.se 560provided a fix for a minor (non-security) buffer overflow condition 561.It 562.An Roland Dowdeswell 563.Aq Mt elric@NetBSD.org 564added support for serving gzipped files and better SSL handling 565.It 566.An Jun-ichiro itojun Hagino, KAME 567.Aq Mt itojun@iijlab.net 568provided initial IPv6 support 569.It 570.An Martin Husemann 571.Aq Mt martin@NetBSD.org 572provided .bzabsredirect support, and fixed various redirection issues 573.It 574.An Arto Huusko 575.Aq Mt arto.huusko@pp2.inet.fi 576provided fixes cgi-bin 577.It 578.An Roland Illig 579.Aq Mt roland.illig@gmx.de 580provided some off-by-one fixes 581.It 582.An Zak Johnson 583.Aq Mt zakj@nox.cx 584provided cgi-bin enhancements 585.It 586.An Nicolas Jombart 587.Aq Mt ecu@ipv42.net 588provided fixes for HTTP basic authorisation support 589.It 590.An Antti Kantee 591.Aq Mt pooka@NetBSD.org 592provided fixes for HTTP basic authorisation support 593.It 594.An Thomas Klausner 595.Aq Mt wiz@NetBSD.org 596provided many fixes and enhancements for the man page 597.It 598.An Mateusz Kocielski 599.Aq Mt shm@NetBSD.org 600fixed memory leaks, various issues with userdir support, 601information disclosure issues, added support for using CGI handlers 602with directory indexing and provided various other fixes. 603.It 604.An Arnaud Lacombe 605.Aq Mt alc@NetBSD.org 606provided some clean up for memory leaks 607.It 608.An Johnny Lam 609.Aq Mt jlam@NetBSD.org 610provided man page fixes 611.It 612.An Julio Merino 613.Aq Mt jmmv@NetBSD.org 614Added the 615.Fl P 616option. 617.It 618.An Luke Mewburn 619.Aq Mt lukem@NetBSD.org 620provided many various fixes, including cgi-bin fixes and enhancements, 621HTTP basic authorisation support and much code clean up 622.It 623.An Rajeev V. Pillai 624.Aq Mt rajeev_v_pillai@yahoo.com 625provided several fixes for virtual hosting 626.It 627.An Jeremy C. Reed 628.Aq Mt reed@NetBSD.org 629provided several clean up fixes, and man page updates 630.It 631.An Scott Reynolds 632.Aq Mt scottr@NetBSD.org 633provided various fixes 634.It 635.An Tyler Retzlaff 636.Aq Mt rtr@eterna.com.au 637provided SSL support, cgi-bin fixes and much other random other stuff 638.It 639.An rudolf 640.Aq Mt netbsd@eq.cz 641provided minor compile fixes and a CGI content map fix 642.It 643.An Steve Rumble 644.Aq Mt rumble@ephemeral.org 645provided the 646.Fl V 647option. 648.It 649.An Thor Lancelot Simon 650.Aq Mt tls@NetBSD.org 651enhanced cgi-bin support. 652.It 653.An Joerg Sonnenberger 654.Aq Mt joerg@NetBSD.org 655implemented If-Modified-Since support 656.It 657.An ISIHARA Takanori 658.Aq Mt ishit@oak.dti.ne.jp 659provided a man page fix 660.It 661.An Holger Weiss 662.Aq Mt holger@CIS.FU-Berlin.DE 663provided http authorisation fixes 664.It 665.Aq Mt xs@kittenz.org 666provided chroot and change-to-user support, and other various fixes 667.It 668Coyote Point provided various CGI fixes. 669.It 670.An Julio Merino 671added pidfile support and provided some man page fixes. 672.El 673.Pp 674There are probably others I have forgotten (let me know if you care) 675.Pp 676Please send all updates to 677.Nm 678to 679.Aq Mt mrg@eterna.com.au 680for inclusion in future releases. 681.Sh BUGS 682.Nm 683does not handle HTTP/1.1 chunked input from the client yet. 684