Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BOZOHTTPD(8)		FreeBSD	System Manager's Manual		  BOZOHTTPD(8)

     bozohttpd -- hyper	text transfer protocol version 1.1 daemon

     bozohttpd [-EGHVXdefhnsu] [-C suffix cgihandler] [-I port]
	       [-L prefix script] [-M suffix type encoding encoding11]
	       [-P pidfile] [-R	readme]	[-S version] [-T type timeout]
	       [-U username] [-Z cert privkey] [-c cgibin] [-i address]
	       [-p pubdir] [-t chrootdir] [-v virtualroot] [-x index]
	       [-z ciphers] slashdir [myname]

     The bozohttpd program reads a HTTP	request	from the standard input, and
     sends a reply to the standard output.  Besides ~user translation and vir-
     tual hosting support (see below), all file	requests are from slashdir di-
     rectory.  The server uses myname as its name, which defaults to the local
     hostname, obtained	from gethostname(3) (but see the -v option for virtual
     hosting.)	bozohttpd writes logs to syslog(3) using the ftp facility (but
     see the -s	option for testing.)  bozohttpd	is designed to be small, sim-
     ple and relatively	featureless, hopefully increasing its security.

     The following options are available:

     -b		Enables	daemon mode, where bozohttpd detaches from the current
		terminal, running in the background and	servicing HTTP re-

     -C	suffix cgihandler
		Adds a new CGI handler program for a particular	file type.
		The suffix should be any normal	file suffix, and the
		cgihandler should be a full path to an interpreter.  This op-
		tion is	the only way to	enable CGI programs that exist outside
		of the cgibin directory	to be executed.	 Multiple -C options
		may be passed.

     -c	cgibin	Enables	the CGI/1.1 interface.	The cgibin directory is	ex-
		pected to contain the CGI programs to be used.	bozohttpd
		looks for URL's	in the form of /cgi-bin/_scriptname_ where
		<scriptname> is	a valid	CGI program in the cgibin directory.
		In other words,	all CGI	URL's must begin with /cgi-bin/.  Note
		that the CGI/1.1 interface is available	with ~user translation
		using -E switch.

     -d		Enables	debug support.

     -E		Enables	CGI/1.1	interface for ~user translation.  Note that
		enabling this support implies that users can run commands as
		the web	server user. This may have security implications.

     -e		Causes bozohttpd to not	clear the environment when used	with
		either the -t or -U options.

     -f		Stops the -b flag from detaching bozohttpd from	the tty	and
		going into the background. This	implies	the -b flag.

     -G		Get the	bozohttpd version string, print	it on standard output,
		and exit.

     -H		Causes directory index mode to hide files and directories that
		start with a period, except for	...  Also see -X.

     -I	port	Causes bozohttpd to use	port instead of	the default "http"
		port.  When used with the -b option, it	changes	the bound
		port.  Otherwise it forces redirections	to use this port in-
		stead of the value obtained via	getsockname(2).

     -i	address
		Causes address to be used as the address to bind daemon	mode.
		If otherwise unspecified, the address used to bind is derived
		from the myname, which defaults	to the name returned by
		gethostname(3).	 Only the last -i option is used.  This	option
		is only	valid with the -b option.

     -L	prefix script
		Adds a new Lua script for a particular prefix.	The prefix
		should be an arbitrary text, and the script should be a	full
		path to	a Lua script.  Multiple	-L options may be passed.  A
		separate Lua state is created for each prefix.	The Lua	script
		can register callbacks using the httpd.register_han-
		dler('<name>', function) Lua function, which will trigger the
		execution of the Lua function function when a URL in the form
		http://_hostname_/_prefix_/_name_ is being accessed.  The
		function is passed three tables	as arguments, the server envi-
		ronment, the request headers, and the decoded query string
		plus any data that was sent as application/x-www-form-urlen-

     -M	suffix type encoding encoding11
		Adds a new entry to the	table that converts file suffixes to
		content	type and encoding.  This option	takes four additional
		arguments containing the file prefix, its "Content-Type",
		"Content-Encoding", and	"Content-Encoding" for HTTP/1.1	con-
		nections, respectively.	 If any	of these are a single dash
		("-"), the empty string	is used	instead.  Multiple -M options
		may be passed.

     -n		Stops bozohttpd	from doing IP address to name resolution of
		remote hosts.  This affects the	REMOTE_HOST environment	vari-
		able for CGI programs and Lua scripts.

     -P	pidfile
		Causes bozohttpd to create a PID file in pidfile when run in
		daemon mode with the -b	option.

     -p	pubdir	Changes	the default user directory for /~user/ translations
		from "public_html" to pubdir.

     -R	readme	When directory indexing	is enabled, include the	contents of
		the file readme	in the footer of the directory index.

     -S	version
		Sets the internal server version to version.

     -s		Forces logging to be set to stderr always.

     -T	type timeout
		Set the	timeout	for type to timeout.  The valid	values of type
		are "ssl timeout", "initial timeout", "header timeout",	and
		"request timeout".  The	default	values are 30 seconds, 30 sec-
		onds, 10 seconds and 600 seconds, respectively.

     -t	chrootdir
		Makes bozohttpd	chroot to the specified	directory before an-
		swering	requests.  Every other path should be specified	rela-
		tive to	the new	root, if this option is	used.  Note that the
		current	environment is normally	replaced with an empty envi-
		ronment	with this option, unless the -e	option is also used.

     -U	username
		Causes bozohttpd to switch to the user and the groups of
		username after initialization.	This option, like -t above,
		causes bozohttpd to clear the environment unless the -e	option
		is given.

     -u		Enables	the transformation of Uniform Resource Locators	of the
		form /~user/ into the directory	~user/public_html (but see the
		-p option above).

     -V		Sets the backup	virtual	host directory to the slashdir argu-
		ment.  If no directory exists in virtualroot for the request,
		then slashdir will be used.  The default behavior is to	return
		404 (Not Found.)

     -v	virtualroot
		Enables	virtual	hosting	support.  Directories in virtualroot
		will be	searched for a matching	virtual	host name, when	pars-
		ing the	HTML request.  If a matching name is found, it will be
		used as	both the server's real name, [myname], and as the
		slashdir.  See the EXAMPLES section for	an example of using
		this option.

     -X		Enables	directory indexing.  A directory index will be gener-
		ated only when the default file	(i.e.  index.html normally) is
		not present.

     -x	index	Changes	the default file read for directories from
		"index.html" to	index.

     -Z	certificate_path privatekey_path
		Sets the path to the server certificate	file and the private
		key file in PEM	format.	 It also causes	bozohttpd to start SSL

     -z	ciphers
		Sets the list of SSL ciphers (see SSL_CTX_set_cipher_list(3)).

     Note that in bozohttpd versions 20031005 and prior	that supported the -C
     and -M options, they took a single	space-separated	argument that was
     parsed.  since version 20040828, they take	multiple options (2 in the
     case of -C	and 4 in the case of -M.)

     On	FreeBSD, bozohttpd can be enabled as the default web server by adding
     the following options to /etc/rc.conf :

     bozohttpd_enable (bool):	   Set it to "YES" to enable bozohttpd.
				   Default is "NO".
     bozohttpd_flags (str):	   Options to pass to bozohttpd.
				   Default is "-b -t /var/empty	-U nobody /".
				   The last argument, slashdir,	is required.

     As	bozohttpd normally uses	inetd(8) to process incoming TCP connections
     for HTTP requests (but see	the -b option),	bozohttpd has little internal
     networking	knowledge.  (Indeed, you can run it on the command line	with
     little change of functionality.)  A typical inetd.conf(5) entry would be:

     http stream tcp  nowait:600 www /usr/local/bin/bozohttpd httpd /var/www
     http stream tcp6 nowait:600 www /usr/local/bin/bozohttpd httpd /var/www

     This would	serve web pages	from /var/www on both IPv4 and IPv6 ports.
     The :600 changes the requests per minute to 600, up from the inetd(8) de-
     fault of 40.

     Using the FreeBSD inetd(8), you can provide multiple IP-address based
     HTTP servers by having multiple listening ports with different configura-

     This server supports the HTTP/0.9,	HTTP/1.0, and HTTP/1.1 standards.
     Support for these protocols is very minimal and many optional features
     are not supported.

     bozohttpd can be compiled without CGI support (NO_CGIBIN_SUPPORT),	user
     transformations (NO_USER_SUPPORT),	directory index	support
     (NO_DIRINDEX_SUPPORT), daemon mode	support	(NO_DAEMON_MODE), dynamic MIME
     content (NO_DYNAMIC_CONTENT), Lua support (NO_LUA_SUPPORT), and SSL sup-
     port (NO_SSL_SUPPORT) by defining the listed macros when building

     bozohttpd has support for HTTP Basic Authorization.  If a file named
     .htpasswd exists in the directory of the current request, bozohttpd will
     restrict access to	documents in that directory using the RFC 2617 HTTP
     "Basic" authentication scheme.

     Note: This	does not recursively protect any sub-directories.

     The .htpasswd file	contains lines delimited with a	colon containing user
     names and passwords hashed	with crypt(3), for example:


     On	FreeBSD, the openssl-passwd(1) utility may be used to generate hashed

     While the FreeBSD port of bozohttpd has support for HTTP Basic Authoriza-
     tion enabled by default, in the portable distribution it is excluded.
     Compile bozohttpd with "-DDO_HTPASSWD" on the compiler command line to
     enable this support.  It may require linking with the crypt library, us-
     ing "-lcrypt".

     On	FreeBSD, bozohttpd supports blacklistd(8) by default.  The support can
     be	disabled with the "-DNO_BLACKLIST_SUPPORT" compilation option.

     Upon occurrence, bozohttpd	reports	two HTTP status	codes to blacklistd(8)
     as	failures: 401 (``Unauthorized'') and 403 (``Forbidden'') .  Of these,
     401 is the	one received upon authorization	failure	with the HTTP Basic
     Authorization mechanism.  A successful authorization decreases the
     counter kept by blacklistd(8).

     Note that the implementation of the HTTP Basic Authorization mechanism
     uses a redirection; a status code 401 is always initially received.
     Therefore,	a single authorization failure of .htpasswd is reported	as two
     failures to blacklistd(8),	but no failures	are recorded upon successful
     authorization due to the decrease of the failure counter.

     bozohttpd has support for TLSv1.1 and TLSv1.2 protocols that are included
     by	default.  It requires linking with the crypto and ssl library, using
     "-lcrypto -lssl".	To disable SSL SUPPORT compile bozohttpd with
     "-DNO_SSL_SUPPORT"	on the compiler	command	line.

     bozohttpd supports	a very basic form of compression.  bozohttpd will
     serve the requested file postpended with ".gz" if it exists, it is	read-
     able, the client requested	gzip compression, and the client did not make
     a ranged request.

     bozohttpd looks for a couple of special files in directories that allow
     certain features to be provided on	a per-directory	basis.	In addition to
     the .htpasswd used	by HTTP	basic authorization, if	a .bzdirect file is
     found (contents are irrelevant) bozohttpd will allow direct access.  If a
     .bzredirect symbolic link is found, bozohttpd will	perform	a smart	redi-
     rect to the target	of this	symlink.  The target is	assumed	to live	on the
     same server.  If target starts with slash then absolute redirection is
     performed,	otherwise it's handled as relative.  If	a .bzabsredirect sym-
     bolic link	is found, bozohttpd will redirect to the absolute URL pointed
     to	by this	symlink.  This is useful to redirect to	different servers.
     Two forms of redirection are supported - symbolic link without schema
     will use http:// as default i.e. link to will redirect to	Otherwise provided schema will be used i.e. symbolic
     link to will redirect to	the provided URL.  If a
     .bzremap file is found at the root	of a (virtual) server, it is expected
     to	contain	rewrite	mappings for URLs.

     These remappings are performed internally in the server before authenti-
     cation happens and	can be used to hide implementation details, like the
     CGI handler specific suffix for non cgi scripts in	authorized directo-

     The map file consists of lines two	paths separated	by a colon, where the
     left side needs to	exactly	match a	(sub) path of the request and will be
     replaced by the right side.

     The first match always wins.

     A .bzremap	file could look	like this:


     The remap file should be short, access to it is slow and needs to happen
     on	each request.  If a request path needs to include a colon (:) charac-
     ter, it can be escaped with a backslash (\) The right hand	side of	the
     colon is always used verbatim, no escape sequences	are interpreted.

     To	configure set of virtual hosts,	one would use an inetd.conf(5) entry

     http stream tcp  nowait:600 www /usr/local/bin/bozohttpd httpd -v /var/vroot /var/www

     and inside	/var/vroot create a directory (or a symlink to a directory)
     with the same name	as the virtual host, for each virtual host.  Lookups
     for these names are done in a case-insensitive manner, and	may include
     the port number part of the request, allowing for distinct	virtual	hosts
     on	the same name.

     To	use bozohttpd with PHP,	one must use the -C option to specify a	CGI
     handler for a particular file type.  Typically this will be like:

     bozohttpd -C .php /usr/pkg/bin/php-cgi /var/www

     Note that a plain script interpreter can not be used directly as a	cgi-
     handler, as there are no command line options passed from bozohttpd to
     avoid security issues.

     If	no CGI-aware wrapper exists, a simple shell script like	the following
     might do.

     It	would be invoked like:

     bozohttpd -C .pl /www-scripts/bin/run.perl	/var/www
     and the script could look like:

     #!	/bin/sh

     if	[ -r "$SCRIPT_FILENAME"	-a -x "$SCRIPT_FILENAME" ]; then
	     exec /usr/pkg/bin/perl "$SCRIPT_FILENAME"

     exit 1

     inetd.conf(5), inetd(8)

     bozohttpd was first written in perl, based	on another perl	http server
     called "tinyhttpd".  It was then rewritten	from scratch in	perl, and then
     once again	in C.  From "bozohttpd"	version	20060517, it has been inte-
     grated into NetBSD.  The focus has	always been simplicity and security,
     with minimal features and regular code audits.  This manual documents
     bozohttpd version 20201014.

     bozohttpd was written by Matthew R. Green <>.

     The large list of contributors includes:

     -	 Christoph Badura <> provided	Range: header support

     -	 Marc Balmer <> added	Lua support for	dynamic	con-
	 tent creation

     -	 Sean Boudreau <> provided a security fix for virtual

     -	 Julian	Coleman	<> provided an IPv6 bugfix

     -	 Chuck Cranor <> provided	cgi-bin	support	fixes,
	 and more

     -	 Alistair G. Crooks <> cleaned up	many internal inter-
	 faces,	made bozohttpd linkable	as a library and provided the Lua

     -	 DEGROOTE Arnaud <> provided	a fix for daemon mode

     -	 Andrew	Doran <> provided directory indexing support

     -	 Roland	Dowdeswell <> added support for	serving
	 gzipped files and better SSL handling

     -	 Per Ekman <> provided a fix for a minor (non-security)
	 buffer	overflow condition

     -	 Jun-ichiro itojun Hagino, KAME	<> provided initial
	 IPv6 support

     -	 Martin	Husemann <> provided .bzabsredirect and
	 .bzredir support, fixed various redirection issues and	more

     -	 Arto Huusko <> provided	fixes cgi-bin

     -	 Roland	Illig <> provided some off-by-one fixes

     -	 Zak Johnson <> provided cgi-bin enhancements

     -	 Nicolas Jombart <> provided fixes	for HTTP basic autho-
	 rization support

     -	 Antti Kantee <> provided fixes	for HTTP basic autho-
	 rization support

     -	 Thomas	Klausner <> provided many	fixes and enhancements
	 for the man page

     -	 Mateusz Kocielski <> fixed memory leaks,	various	issues
	 with userdir support, information disclosure issues, added support
	 for using CGI handlers	with directory indexing, found several secu-
	 rity issues and provided various other	fixes

     -	 Arnaud	Lacombe	<> provided some clean up	for memory

     -	 Johnny	Lam <> provided man page	fixes

     -	 Dennis	Lindroos <> provided a	cgi-bin	fix

     -	 Julio Merino <>	Added the -P option (pidfile support)
	 and provided some man page fixes

     -	 Luke Mewburn <> provided many various fixes, includ-
	 ing cgi-bin fixes and enhancements, HTTP basic	authorization support
	 and much code clean up

     -	 Rajeev	V. Pillai <> provided several fixes
	 for virtual hosting and directory indexing and	fixes for CGI

     -	 Jeremy	C. Reed	<> provided several clean up fixes, and
	 man page updates

     -	 Scott Reynolds	<> provided various fixes

     -	 Tyler Retzlaff	<> provided SSL support, cgi-bin
	 fixes and much	other random other stuff

     -	 rudolf	<> provided	minor compile fixes and	a CGI content
	 map fix

     -	 Steve Rumble <> provided the -V option

     -	 Thor Lancelot Simon <> enhanced cgi-bin support

     -	 Joerg Sonnenberger <> implemented If-Modified-Since

     -	 ISIHARA Takanori <>	provided a man page fix

     -	 Holger	Weiss <holger@CIS.FU-Berlin.DE>	provided http authorization

     -	 <> provided chroot and change-to-user support, and
	 other various fixes

     -	 Jukka Ruohonen	<> provided support for blacklist(8)

     -	 Jared McNeill <> added support for readme in di-
	 rectory indexing

     -	 S.P.Zeidler <> fixed several SSL	shutdown issues

     -	 Coyote	Point provided various CGI fixes

     There are probably	others I have forgotten	(let me	know if	you care)

     Please send all updates to	bozohttpd to <> for inclusion
     in	future releases.

     bozohttpd does not	handle HTTP/1.1	chunked	input from the client yet.

FreeBSD	13.0		       October 14, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help