Ubuntu Manpage: mini_httpd - small HTTP server

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 max_age] [-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.

       mini_httpd can be automatically started in two ways.  The included systemd service is used to control the
       server in systemd environments. This is inherently more secure as the  service  makes  use  of  hardening
       features.  The included init.d script starts the server in non-systemd environments still using classical
       SysV style init.

       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 "UTF-8". 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 "max_age".

-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 REFERRERS

       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 referrer
       filtering.  With this option, certain files can only be fetched via a local referrer.  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  referrer.   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 referrer filtering.

       noemptyreferrers
              By  default,  requests with no referrer at all, or a null referrer, or a referrer 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 referrer 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.

AUTHOR

       Copyright © 1999,2000 by Jef Poskanzer <jef@mail.acme.com>. All rights reserved.

                                                 05 October 1999                                   mini_httpd(8)