Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
mini_httpd(8)		    System Manager's Manual		 mini_httpd(8)

       mini_httpd - small HTTP server

       mini_httpd  [-C	configfile] [-p	port] [-d dir] [-dd data_dir] [-c cgi-
       pat] [-u	user] [-h hostname] [-r] [-v] [-l logfile]  [-i	 pidfile]  [-T
       charset]	[-P P3P] [-M maxage] [-S] [-E certfile]	[-Y cipher] [-D] [-V]

       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 to-
       day'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 plat-
       form for	experimenting with new web  server  technology,	 for  instance

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

       -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 op-
	      tion 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	"noch-

       -v     Do virtual hosting.  See below for details.  The config-file op-
	      tion name	for this flag is "vhost".

       -l     Specifies	a log file name.  The default is no logging.  The con-
	      fig-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 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 equiva-
	      lent "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	 spec-
	      ify  a  server  certificate with this flag.  You can make	a cer-
	      tificate	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	 spec-
	      ify  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	neces-
	      sary  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.

       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 pat-
       tern.   You  can	use * to match any string not including	a slash, or **
       to match	any string including slashes, or ? to match any	single charac-
       ter.  You can also use multiple such patterns separated by |.  The pat-
       terns 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 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 mini_httpd-htpasswd(1) is included to help  create  and
       modify .htpasswd	files.

       chroot()	 is  a	system	call  that restricts the program's view	of the
       filesystem to the current directory and directories below it.   It  be-
       comes  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	becom-
       ing 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 pol-
       icy  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 sys-
       tem'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  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,, and	 your  own,  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: IN A IN CNAME IN CNAME
       However,	 this  is  incompatible	 with older HTTP/1.0 browsers.	If you
       want to stay compatible,	there's	a different way	- use  A  records  in-
       stead, each with	a different IP address,	like so: IN A IN A IN A
       This  is	 bad because it	uses extra IP addresses, a somewhat scarce re-
       source.	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
	 ifconfig le0 alias
	 ifconfig le0	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 in-
       tended 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:
       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
	 ln -s
	 ln -s
       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,  us-
       ing  the	 -h  flag  to specify which one	is which.  This	gives you more
       flexibility, since you can run each of these processes in separate  di-
       rectories or with different options.  Example:
	 ( cd /usr/www ; mini_httpd -h )
	 ( cd /usr/www/joe ; mini_httpd	-u joe -h )
	 ( cd /usr/www/jane ; mini_httpd -u jane -h )
       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.

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

       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	refer-
       rer.  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  re-
	      ferrer.  This is typically just image files, sound files,	and so
	      on.  For example:
	      For most sites, that one setting is all you need to  enable  re-
	      ferrer filtering.

	      By  default,  requests with no referrer at all, or a null	refer-
	      rer, or a	referrer with no apparent hostname, are	allowed.  With
	      this variable set, such requests are disallowed.

	      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.

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

       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	   and

       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.

       mini_httpd-htpasswd(1), weblog_parse(1),	http_get(1)

       Copyright  (C)  1999,2000  by  Jef  Poskanzer  <>. All
       rights reserved.

				05 October 1999			 mini_httpd(8)


Want to link to this manual page? Use this URL:

home | help