Man Linux: Main Page and Category List

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

                                05 October 1999                  mini_httpd(8)