packages icon



 mini_httpd(8)                                                 mini_httpd(8)
                               05 October 1999



 NAME
      mini_httpd - small HTTP server

 SYNOPSIS
      mini_httpd [-p port] [-c cgipat] [-u user] [-h hostname] [-r] [-v] [-l
      logfile] [-i pidfile] [-T charset] [-S] [-D]

 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
      -p   Specifies an alternate port number to listen on.  The default is
           80.

      -c   Specifies a wildcard pattern for CGI programs, for instance
           "**.cgi" or "cgi-bin/*".  The default is no CGI.




                                    - 1 -           Formatted:  July 3, 2022






 mini_httpd(8)                                                 mini_httpd(8)
                               05 October 1999



      -u   Specifies what user to switch to after initialization when
           started as root.  The default is "nobody".

      -h   Specifies a hostname to bind to, for multihoming.  The default is
           to bind to all hostnames supported on the local machine.

      -r   Do a chroot() at initialization time, restricting file access to
           the program's current directory.  See below for details.

      -v   Do virtual hosting.

      -l   Specifies a log file name.  The default is no logging.

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

      -T   Specifies the character set to use with text MIME types.  The
           default is iso-8859-1.

      -S   If mini_httpd is configured to do SSL/HTTPS, then the -S flag is
           available to enable this feature.

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

 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.





                                    - 2 -           Formatted:  July 3, 2022






 mini_httpd(8)                                                 mini_httpd(8)
                               05 October 1999



 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.

 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



                                    - 3 -           Formatted:  July 3, 2022






 mini_httpd(8)                                                 mini_httpd(8)
                               05 October 1999



        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.




                                    - 4 -           Formatted:  July 3, 2022






 mini_httpd(8)                                                 mini_httpd(8)
                               05 October 1999



 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, SIGHUP, 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.

 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@acme.com>. All rights
      reserved.






















                                    - 5 -           Formatted:  July 3, 2022