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