Provided by: mini-httpd_1.30-2build1_amd64 bug

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

SEE ALSO

       htpasswd(1), weblog_parse(1), http_get(1)

AUTHOR

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

                                         05 October 1999                            mini_httpd(8)