BOZOHTTPD(8) | System Manager's Manual | BOZOHTTPD(8) |
bozohttpd
—
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] |
bozohttpd
program reads a HTTP
request from the standard input, and sends a reply to the standard output.
Besides ~user translation and virtual hosting support (see below), all file
requests are from slashdir directory. 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, simple and
relatively featureless, hopefully increasing its security.
-b
bozohttpd
detaches from
the current terminal, running in the background and servicing HTTP
requests.-C
suffix cgihandler-C
options may be passed.-c
cgibinbozohttpd
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
-E
-e
bozohttpd
to not clear the environment when
used with either the -t
or
-U
options.-f
-b
flag from detaching
bozohttpd
from the tty and going into the
background. This implies the -b
flag.-G
bozohttpd
version string, print it on
standard output, and exit.-H
-X
.-I
portbozohttpd
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 instead of the value obtained via
getsockname(2).-i
address-i
option is used. This option is only
valid with the -b
option.-L
prefix script-L
options may be passed. A separate Lua
state is created for each prefix. The Lua script can register callbacks
using the httpd.register_handler('<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 environment, the request headers, and the decoded query string plus
any data that was sent as application/x-www-form-urlencoded.-M
suffix type encoding encoding11-M
options may be passed.-n
bozohttpd
from doing IP address to name
resolution of remote hosts. This affects the
REMOTE_HOST
environment variable for CGI programs
and Lua scripts.-P
pidfilebozohttpd
to create a PID file in
pidfile when run in daemon mode with the
-b
option.-p
pubdir-R
readme-S
version-s
-T
type timeout-t
chrootdirbozohttpd
chroot to the specified directory
before answering requests. Every other path should be specified relative
to the new root, if this option is used. Note that the current environment
is normally replaced with an empty environment with this option, unless
the -e
option is also used.-U
usernamebozohttpd
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
-p
option above).-V
-v
virtualroot-X
-x
index-Z
certificate_path privatekey_pathbozohttpd
to start SSL
mode.-z
ciphersNote 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
.)
bozohttpd
uses
inetd(8) by default 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 _httpd /usr/libexec/httpd httpd /var/www http stream tcp6 nowait:600 _httpd /usr/libexec/httpd 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) default of 40.
Using the NetBSD inetd(8), you can provide multiple IP-address based HTTP servers by having multiple listening ports with different configurations.
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 support (NO_SSL_SUPPORT) by defining the listed
macros when building bozohttpd
.
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:
heather:$1$pZWI4tH/$DzDPl63i6VvVRv2lJNV7k1 jeremy:A.xewbx2DpQ8I
On NetBSD, the pwhash(1) utility may be used to generate hashed passwords.
While bozohttpd
distributed with
NetBSD has support for HTTP Basic Authorization
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, using “-lcrypt”.
bozohttpd
supports
blocklistd(8) by default.
The support can be disabled with the “-DNO_BLOCKLIST_SUPPORT”
compilation option.
Upon occurrence, bozohttpd
reports two
HTTP status codes to
blocklistd(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
blocklistd(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 blocklistd(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 readable,
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 redirect 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 symbolic 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 NetBSD.org
will redirect to http://NetBSD.org/ Otherwise provided
schema will be used i.e. symbolic link to ftp://NetBSD.org/
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 authentication happens and can be used to hide implementation details, like the CGI handler specific suffix for non cgi scripts in authorized directories.
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:
/nic/update:/auth-dir/updipv4.pl
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
(:
) character, it can be escaped with a backslash
(\
) The right hand side of the colon is always used
verbatim, no escape sequences are interpreted.
http stream tcp nowait:600 _httpd /usr/libexec/httpd 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:
httpd -C .php /usr/pkg/bin/php-cgi /var/www
Note that a plain script interpreter can not be used directly as a
cgihandler, 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:
httpd -C .pl /www-scripts/bin/run.perl /var/www
#! /bin/sh if [ -r "$SCRIPT_FILENAME" -a -x "$SCRIPT_FILENAME" ]; then exec /usr/pkg/bin/perl "$SCRIPT_FILENAME" fi exit 1
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 integrated into NetBSD.
The focus has always been simplicity and security, with minimal features and
regular code audits. This manual documents bozohttpd
version 20210227.
bozohttpd
was written by Matthew R.
Green
<mrg@eterna.com.au>.
The large list of contributors includes:
bozohttpd
linkable as a library and provided the
Lua binding-P
option (pidfile support) and provided
some man page fixes-V
optionThere are probably others I have forgotten (let me know if you care)
Please send all updates to bozohttpd
to
<mrg@eterna.com.au>
for inclusion in future releases.
bozohttpd
does not handle HTTP/1.1 chunked input from
the client yet.
February 27, 2021 | NetBSD 9.4 |