NAME¶
mini_httpd - small HTTP server
SYNOPSIS¶
mini_httpd [
-C configfile] [
-p port]
[
-d dir] [
-dd data_dir] [
-c cgipat]
[
-u user] [
-h hostname] [
-r] [
-v]
[
-l logfile] [
-i pidfile] [
-T
charset] [
-P P3P] [
-M maxage] [
-S]
[
-E certfile] [
-Y cipher] [
-D] [
-V]
DESCRIPTION¶
mini_httpd is a small HTTP server. Its performance is not great, but for
low or medium traffic sites it's quite adequate. It implements all the basic
features of an HTTP server, including:
- *
- GET, HEAD, and POST methods.
- *
- CGI.
- *
- Basic authentication.
- *
- Security against ".." filename snooping.
- *
- The common MIME types.
- *
- Trailing-slash redirection.
- *
- index.html, index.htm, index.cgi
- *
- Directory listings.
- *
- Multihoming / virtual hosting.
- *
- Standard logging.
- *
- Custom error pages.
It can also be configured to do SSL/HTTPS.
mini_httpd was written for a couple reasons. One, as an experiment to see just
how slow an old-fashioned forking web server would be with today's operating
systems. The answer is, surprisingly, not that slow - on FreeBSD 3.2,
mini_httpd benchmarks at about 90% the speed of Apache. The other main reason
for writing mini_httpd was to get a simple platform for experimenting with new
web server technology, for instance SSL.
OPTIONS¶
- -C
- Specifies a config-file to read. All options can be set
either by command-line flags or in the config file. See below for
details.
- -p
- Specifies an alternate port number to listen on. The
default is 80. The config-file option name for this flag is
"port".
- -d
- Specifies a directory to chdir() to at startup. This is
merely a convenience - you could just as easily do a cd in the shell
script that invokes the program. The config-file option name for this flag
is "dir".
- -dd
- Specifies a directory to chdir() to after chrooting. If
you're not chrooting, you might as well do a single chdir() with the -d
flag. If you are chrooting, this lets you put the web files in a
subdirectory of the chroot tree, instead of in the top level mixed in with
the chroot files. The config-file option name for this flag is
"data_dir".
- -c
- Specifies a wildcard pattern for CGI programs, for instance
"**.cgi" or "cgi-bin/*". The default is no CGI. The
config-file option name for this flag is "cgipat".
- -u
- Specifies what user to switch to after initialization when
started as root. The default is "nobody". The config-file option
name for this flag is "user".
- -h
- Specifies a hostname to bind to, for multihoming. The
default is to bind to all hostnames supported on the local machine. The
config-file option name for this flag is "host".
- -r
- Do a chroot() at initialization time, restricting file
access to the program's current directory. See below for details. The
config-file option names for this flag are "chroot" and
"nochroot".
- -v
- Do virtual hosting. See below for details. The config-file
option name for this flag is "vhost".
- -l
- Specifies a log file name. The default is no logging. The
config-file option name for this flag is "logfile".
- -i
- Specifies a file to write the process-id to. If no file is
specified, no process-id is written. You can use this file to send signals
to mini_httpd. The config-file option name for this flag is
"pidfile".
- -T
- Specifies the character set to use with text MIME types.
The default is "iso-8859-1". The config-file option name for
this flag is "charset".
- -P
- Specifies a P3P server privacy header to be returned with
all responses. See http://www.w3.org/P3P/ for details. Mini_httpd doesn't
do anything at all with the string except put it in the P3P: response
header. The config-file option name for this flag is "p3p".
- -M
- Specifies the number of seconds to be used in a
"Cache-Control: max-age" header to be returned with all
responses. An equivalent "Expires" header is also generated. The
default is no Cache-Control or Expires headers, which is just fine for
most sites. The config-file option name for this flag is
"maxage".
- -S
- If mini_httpd is configured to do SSL/HTTPS, then the -S
flag is available to enable this feature. The config-file option name for
this flag is "ssl".
- -E
- If mini_httpd is configured to do SSL/HTTPS, then you can
specify a server certificate with this flag. You can make a certificate
with the command "make cert". The default is
"mini_httpd.pem" (in the directory where you start mini_httpd).
The config-file option name for this flag is "certfile".
- -Y
- If mini_httpd is configured to do SSL/HTTPS, then you can
specify a cipher set with this flag. Examples of cipher sets:
"RC4-MD5", "DES-CBC3-SHA", "AES256-SHA". The
default is to let each browser negotiate ciphers separately, and unless
you know what you're doing it's best to let them do so. The config-file
option name for this flag is "cipher".
- -D
- This was originally just a debugging flag, however it's
worth mentioning because one of the things it does is prevent mini_httpd
from making itself a background daemon. Instead it runs in the foreground
like a regular program. This is necessary when you want to run mini_httpd
wrapped in a little shell script that restarts it if it exits. The
config-file option name for this flag is "debug".
- -V
- Shows mini_httpd's version and then exits.
CGI¶
mini_httpd supports the CGI 1.1 spec.
In order for a CGI program to be run, its name must match the pattern you
specify with the -c flag This is a simple shell-style filename pattern. You
can use * to match any string not including a slash, or ** to match any string
including slashes, or ? to match any single character. You can also use
multiple such patterns separated by |. The patterns get checked against the
filename part of the incoming URL. Don't forget to quote any wildcard
characters so that the shell doesn't mess with them.
BASIC AUTHENTICATION¶
Basic Authentication uses a password file called ".htpasswd", in the
directory to be protected. This file is formatted as the familiar
colon-separated username/encrypted-password pair, records delimited by
newlines. The protection does not carry over to subdirectories. The utility
program
htpasswd(1) is included to help create and modify .htpasswd files.
CHROOT¶
chroot() is a system call that restricts the program's view of the filesystem to
the current directory and directories below it. It becomes impossible for
remote users to access any file outside of the initial directory. The
restriction is inherited by child processes, so CGI programs get it too. This
is a very strong security measure, and is recommended. The only downside is
that only root can call chroot(), so this means the program must be started as
root. However, the last thing it does during initialization is to give up root
access by becoming another user, so this is safe.
Note that with some other web servers, such as NCSA httpd, setting up a
directory tree for use with chroot() is complicated, involving creating a
bunch of special directories and copying in various files. With mini_httpd
it's a lot easier, all you have to do is make sure any shells, utilities, and
config files used by your CGI programs and scripts are available. If you have
CGI disabled, or if you make a policy that all CGI programs must be written in
a compiled language such as C and statically linked, then you probably don't
have to do any setup at all.
However, one thing you should do is tell syslogd about the chroot tree, so that
mini_httpd can still generate syslog messages. Check your system's syslodg man
page for how to do this. In FreeBSD you would put something like this in
/etc/rc.conf:
syslogd_flags="-l /usr/local/www/data/dev/log"
Substitute in your own chroot tree's pathname, of course. Don't worry about
creating the log socket, syslogd wants to do that itself. (You may need to
create the dev directory.) In Linux the flag is -a instead of -l, and there
may be other differences.
MULTIHOMING¶
Multihoming means using one machine to serve multiple hostnames. For instance,
if you're an internet provider and you want to let all of your customers have
customized web addresses, you might have www.joe.acme.com, www.jane.acme.com,
and your own www.acme.com, all running on the same physical hardware. This
feature is also known as "virtual hosts". There are three steps to
setting this up.
One, make DNS entries for all of the hostnames. The current way to do this,
allowed by HTTP/1.1, is to use CNAME aliases, like so:
www.acme.com IN A 192.100.66.1
www.joe.acme.com IN CNAME www.acme.com
www.jane.acme.com IN CNAME www.acme.com
However, this is incompatible with older HTTP/1.0 browsers. If you want to stay
compatible, there's a different way - use A records instead, each with a
different IP address, like so:
www.acme.com IN A 192.100.66.1
www.joe.acme.com IN A 192.100.66.200
www.jane.acme.com IN A 192.100.66.201
This is bad because it uses extra IP addresses, a somewhat scarce resource. But
if you want people with older browsers to be able to visit your sites, you
still have to do it this way.
Step two. If you're using the modern CNAME method of multihoming, then you can
skip this step. Otherwise, using the older multiple-IP-address method you must
set up IP aliases or multiple interfaces for the extra addresses. You can use
ifconfig(8)'s alias command to tell the machine to answer to all of the
different IP addresses. Example:
ifconfig le0 www.acme.com
ifconfig le0 www.joe.acme.com alias
ifconfig le0 www.jane.acme.com alias
If your OS's version of ifconfig doesn't have an alias command, you're probably
out of luck.
Third and last, you must set up mini_httpd to handle the multiple hosts. The
easiest way is with the -v flag. This works with either CNAME multihosting or
multiple-IP multihosting. What it does is send each incoming request to a
subdirectory based on the hostname it's intended for. All you have to do in
order to set things up is to create those subdirectories in the directory
where mini_httpd will run. With the example above, you'd do like so:
mkdir www.acme.com www.joe.acme.com www.jane.acme.com
If you're using old-style multiple-IP multihosting, you should also create
symbolic links from the numeric addresses to the names, like so:
ln -s www.acme.com 192.100.66.1
ln -s www.joe.acme.com 192.100.66.200
ln -s www.jane.acme.com 192.100.66.201
This lets the older HTTP/1.0 browsers find the right subdirectory.
There's an optional alternate step three if you're using multiple-IP
multihosting: run a separate mini_httpd process for each hostname, using the
-h flag to specify which one is which. This gives you more flexibility, since
you can run each of these processes in separate directories or with different
options. Example:
( cd /usr/www ; mini_httpd -h www.acme.com )
( cd /usr/www/joe ; mini_httpd -u joe -h www.joe.acme.com )
( cd /usr/www/jane ; mini_httpd -u jane -h www.jane.acme.com )
But remember, this multiple-process method does not work with CNAME multihosting
‐ for that, you must use a single mini_httpd process with the -v flag.
CUSTOM ERRORS¶
mini_httpd lets you define your own custom error pages for the various HTTP
errors. There's a separate file for each error number, all stored in one
special directory. The directory name is "errors", at the top of the
web directory tree. The error files should be named "errNNN.html",
where NNN is the error number. So for example, to make a custom error page for
the authentication failure error, which is number 401, you would put your HTML
into the file "errors/err401.html". If no custom error file is found
for a given error number, then the usual built-in error page is generated.
If you're using the virtual hosts option, you can also have different custom
error pages for each different virtual host. In this case you put another
"errors" directory in the top of that virtual host's web tree.
mini_httpd will look first in the virtual host errors directory, and then in
the server-wide errors directory, and if neither of those has an appropriate
error file then it will generate the built-in error.
NON-LOCAL REFERERS¶
Sometimes another site on the net will embed your image files in their HTML
files, which basically means they're stealing your bandwidth. You can prevent
them from doing this by using non-local referer filtering. With this option,
certain files can only be fetched via a local referer. The files have to be
referenced by a local web page. If a web page on some other site references
the files, that fetch will be blocked. There are three config-file variables
for this feature:
- urlpat
- A wildcard pattern for the URLs that should require a local
referer. This is typically just image files, sound files, and so on. For
example:
urlpat=**.jpg|**.gif|**.au|**.wav
For most sites, that one setting is all you need to enable referer
filtering.
- noemptyreferers
- By default, requests with no referer at all, or a null
referer, or a referer with no apparent hostname, are allowed. With this
variable set, such requests are disallowed.
- localpat
- A wildcard pattern that specifies the local host or hosts.
This is used to determine if the host in the referer is local or not. If
not specified it defaults to the actual local hostname.
SIGNALS¶
mini_httpd will terminate cleanly upon receipt of a number of different signals,
which you can send via the standard Unix
kill(1) command. Any of SIGTERM,
SIGINT, or SIGUSR1 will do the trick. All requests in progress will be
completed. The network socket used to accept new connections gets closed
immediately, which means a fresh mini_httpd can be started up right away. This
is convenient when you're rotating your log files.
In addition, a SIGHUP will attempt to close and re-open the log file. This is a
little tricky to set up correctly, for instance if you are using chroot() then
the log file must be within the chroot tree, but it's definitely doable.
CERTIFICATES¶
If you're going to serve SSL/HTTPS you will need a server certificate. There are
a bunch of companies that will issue one for you; see the lists at
http://www.apache-ssl.org/#Digital_Certificates and
http://www.modssl.org/docs/2.4/ssl_faq.html#ToC23
You can also create one for yourself, using the openssl tool. Step one - create
the key and certificate request:
openssl req -new > cert.csr
Step two ‐ remove the passphrase from the key:
openssl rsa -in privkey.pem -out key.pem
Step three ‐ convert the certificate request into a signed certificate:
openssl x509 -in cert.csr -out cert.pem -req -signkey key.pem -days 365
This creates four files. The ones you want are cert.pem and key.pem. You don't
need cert.csr and privkey.pem, and may remove them.
SEE ALSO¶
htpasswd(1), weblog_parse(1), http_get(1)
AUTHOR¶
Copyright © 1999,2000 by Jef Poskanzer <jef@mail.acme.com>. All
rights reserved.