HTTPD(8)
========

NAME
----
httpd - a minimalistic high-performance web server

SYNOPSIS
--------
*httpd* ['OPTIONS']

DESCRIPTION
-----------
mini-httpd is a minimalistic web server designed for optimal performance, high
security, and as little use of system resources as possible. Unlike most other
web servers, mini-httpd does not require more than one process or system thread
in order to handle an arbitrary number of requests concurrently. The current set
of features includes:

1. HTTP/1.1 compliant "keep-connection" support.

2. Virtual hosting.

3. Recording all successful requests in the common Apache-style log-file format.

4. The ability to run in a chroot(2) sandbox.

5. Dropping all super-user privileges after acquiring the listening socket.

6. mini-httpd is configured entirely through the command line. There is no config file.

mini-httpd is limited to serving *static* pages from the hard disk. There is no
support for CGI scripts or any kind of dynamic content. If you need a more
sophisticated set-up, this software is not for you. If you really, really need
additional features, well, you have the source code. For further details on how
to configure the web server, refer to the section "Setting up mini-httpd"
section below.

OPTIONS
-------
*-h*::
  Show command line syntax and exit.

*-d, --debug*::
  Enable additional debugging messages. Debugging is only available if
  mini-httpd has been compiled with the --with-debug configure option.
  Otherwise, the debug messages are not included in the binary.

*--version*::
  Show mini-httpd's version string and exit.

*-p, --port*='NUMBER'::
  Tell mini-httpd on which port to listen for incoming requests. The default
  port number is 80.

*-r, --change-root*='PATH'::
  When started with super-user privileges, mini-httpd will chroot(2) to the
  directory provided with this option. Please note that once the process's root
  directory has been changed, all other paths are interpreted relative to the
  new root directory! If you specify -r /usr/local/mini-httpd, for example, the
  document root /usr/local/httpd/htdocs has to be given as /htdocs. Keep that in
  mind when specifying the other paths!
  +
  The default chroot-directory is the prefix provided to configure when
  mini-httpd was built. Usually, that is /usr/local/mini-httpd.
  +
  If you want to disable chroot()ing altogether, provide the empty string: -r
  "". This is not recommended, however.

*--document-root*='PATH'::
  This option sets the document root directory. When an access to, say,
  http://example.org/index.html comes in, mini-httpd will try to access the file
  example.org/index.html in this directory. Note that hostnames must be spelled
  in all lower-case in the file system!
  +
  The default location is /htdocs.

*-l, --logfile-directory*='PATH'::
  This option sets the directory mini-httpd uses to create the access-log
  files. In this directory, one file per hostname will be created. The default
  location is /logs.

*-s, --server-string*='STRING'::
  This option sets the version string mini-httpd returns with the Server:
  header in HTTP replies. The default string is “mini-httpd” -- no actual
  version number is revealed. If you want to disable the Server: header
  altogether, specify the empty string: -s "".

*-u, --uid*='NUMBER'::
  This option sets the numeric user id mini-httpd will setuid() to when called
  with super-user privileges. This is necessary because mini-httpd must be
  started as root in order to be able to bind() to port 80. But you don't want
  the server to run as root the whole time! A good choice is usually user id
  “2” (daemon). If this option is unset, mini-httpd will continue to use the
  user id is has been started under.

*-g, --gid*='NUMBER'*::
  This option sets the numeric group id mini-httpd will setgid() to when
  called with super-user privileges. (See --uid for further details.)

*--default-page='PATH'*::
  This option sets the filename mini-httpd accesses when a request for a
  directory is received. The default is index.html. This means, that a request
  for http://example.org/ will result in the file example.org/index.html being
  returned.

*-D, --no-detach*::
  This option tells mini-httpd not to detach from the controlling terminal,
  but to run in the foreground. This is useful mostly for debugging purposes.
  The default is to detach.

*-H, --default-hostname*='HOSTNAME'::
  This option sets default hostname mini-httpd uses when a pre-HTTP/1.1
  request comes in, which does not provide the Host: header. If the default
  hostname is empty or this option is omitted, mini-httpd will reject such
  requests.

SETTING UP MINI-HTTPD
---------------------
Setting up mini-httpd is pretty easy, because the program does have the
least possible set of features. It may look weird at first, especially
if you know other web servers like Apache, but it's really not that
difficult. The following instructions assume you've installed mini-httpd
using the default prefix, /usr/local/mini-httpd. Not that it matters
much, though, because you can set all paths at the command line.

It's important to understand that mini-httpd changes the process's root
directory to /usr/local/mini-httpd once it has initialized its
internals. Thus, all files related to your web service must reside
within this directory (or below). You cannot symlink to some path
outside that hierarchy, or some thing.

First of all, choose an user id you'll run mini-httpd under. A sensible
choice is daemon, but you can as well use nobody or any other user id
you see fit. Find out which numeric user id this user has on your system
by calling the id(1) command:

  $ id daemon
  uid=2(daemon) gid=2(daemon) groups=2(daemon),1(bin)

Now you'll need to create two directories in /usr/local/mini-httpd:
htdocs and logs. The first directory will contain the actual web
documents in one subdirectory per (virtual) host you want to provide.
The second directory will contain the access logs written by mini-httpd.
Consequently, mini-httpd's user must be allowed to read htdocs and to
write to logs. The following commands will ensure that:

  # mkdir htdocs logs
  # chown daemon.daemon htdocs logs

Now create a directory in htdocs, which is called like the hostname,
your web service should be provided under. Make sure you use all
lower-case characters! If your web server is accessed as, say,
example.com and www.example.com, do the following:

  # mkdir htdocs/example.org
  # ln -s htdocs/example.org htdocs/www.example.org
  # chown daemon.daemon htdocs/example.org htdocs/www.example.org

If you're unsure what hostname to use for testing purposes, localhost is
usually a safe bet. :-)

Copy the HTML documents to the htdocs/example.org directory and ensure
that mini-httpd has permission to access them! Finally, start mini-httpd
as root, using the following command line:

  # /usr/local/mini-httpd/bin/httpd --uid 2

That's it. You may now direct your favorite browser to
http://example.org/ and see what happens.

In case you want to try mini-httpd with some port other than 80, add the
--port option to the command line: --port 8080. Furthermore, you might
want to add the --debug switch to turn on the debugging messages in
mini-httpd. That is particularly helpful in case mini-httpd is not
behaving as you're expecting.

Once you have accessed the web site, you'll find the appropriate
access-log file in the logs directory; one file per virtual host.

If you want to add more virtual hosts to mini-httpd, just create the
corresponding directory in htdocs.

AUTHOR
------
Peter Simons <simons@cryp.to>

RESOURCES
---------
Savannah: <http://savannah.nongnu.org/projects/mini-httpd>

Main web site: <http://www.nongnu.org/mini-httpd/>

COPYING
-------
Copyright \(C) 2001-2016 Peter Simons. Free use of this software is granted
under the terms of the GNU General Public License version 3 or later (GPLv3+).
