.TH mini_httpd 8 "05 October 1999".SH NAMEmini_httpd - small HTTP server.SH SYNOPSIS.B mini_httpd.RB [ -C.IR configfile ].RB [ -p.IR port ].RB [ -d.IR dir ].RB [ -dd.IR data_dir ].RB [ -c.IR cgipat ].RB [ -u.IR user ].RB [ -h.IR hostname ].RB [ -r ].RB [ -v ].RB [ -l.IR logfile ].RB [ -i.IR pidfile ].RB [ -T.IR charset ].RB [ -P.IR P3P ].RB [ -M.IR maxage ].RB [ -S ].RB [ -E.IR certfile ].RB [ -Y.IR cipher ].RB [ -D ].RB [ -V ].SH DESCRIPTION.PP.I mini_httpdis a small HTTP server.Its performance is not great, but for low or medium traffic sites it'squite adequate.It implements all the basic features of an HTTP server, including:.TP 3*GET, HEAD, and POST methods..TP 3*CGI..TP 3*Basic authentication..TP 3*Security against ".." filename snooping..TP 3*The common MIME types..TP 3*Trailing-slash redirection..TP 3*index.html, index.htm, index.cgi.TP 3*Directory listings..TP 3*Multihoming / virtual hosting..TP 3*Standard logging..TP 3*Custom error pages..PPIt can also be configured to do SSL/HTTPS..PPmini_httpd was written for a couple reasons.One, as an experiment to see just how slow an old-fashioned forkingweb server would be with today's operating systems.The answer is, surprisingly, not that slow - on FreeBSD 3.2, mini_httpdbenchmarks at about 90% the speed of Apache.The other main reason for writing mini_httpd was to get a simpleplatform for experimenting with new web server technology, for instance SSL..SH OPTIONS.TP.B -CSpecifies a config-file to read.All options can be set either by command-line flags or in the config file.See below for details..TP.B -pSpecifies an alternate port number to listen on.The default is 80.The config-file option name for this flag is "port"..TP.B -dSpecifies a directory to chdir() to at startup.This is merely a convenience - you could just as easily do a cd in theshell script that invokes the program.The config-file option name for this flag is "dir"..TP.B -ddSpecifies a directory to chdir() to after chrooting.If you're not chrooting, you might as well do a single chdir() withthe -d flag.If you are chrooting, this lets you put the web files in a subdirectoryof the chroot tree, instead of in the top level mixed in with thechroot files.The config-file option name for this flag is "data_dir"..TP.B -cSpecifies 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"..TP.B -uSpecifies 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"..TP.B -hSpecifies 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"..TP.B -rDo a chroot() at initialization time, restricting file accessto the program's current directory.See below for details.The config-file option names for this flag are "chroot" and "nochroot"..TP.B -vDo virtual hosting.See below for details.The config-file option name for this flag is "vhost"..TP.B -lSpecifies a log file name.The default is no logging.The config-file option name for this flag is "logfile"..TP.B -iSpecifies 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"..TP.B -TSpecifies 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"..TP.B -PSpecifies 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 theP3P: response header.The config-file option name for this flag is "p3p"..TP.B -MSpecifies 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"..TP.B -SIf mini_httpd is configured to do SSL/HTTPS, then the -S flag is availableto enable this feature.The config-file option name for this flag is "ssl"..TP.B -EIf mini_httpd is configured to do SSL/HTTPS, then you can specify aserver 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"..TP.B -YIf mini_httpd is configured to do SSL/HTTPS, then you can specify acipher 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, andunless you know what you're doing it's best to let them do so.The config-file option name for this flag is "cipher"..TP.B -DThis was originally just a debugging flag, however it's worth mentioningbecause one of the things it does is prevent mini_httpd from making itselfa 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 shellscript that restarts it if it exits.The config-file option name for this flag is "debug"..TP.B -VShows mini_httpd's version and then exits..SH "CGI".PPmini_httpd supports the CGI 1.1 spec..PPIn order for a CGI program to be run, its name must match the patternyou specify with the -c flagThis 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 filenamepart of the incoming URL.Don't forget to quote any wildcard characters so that the shell doesn'tmess with them..SH "BASIC AUTHENTICATION".PPBasic Authentication uses a password file called ".htpasswd", inthe directory to be protected.This file is formatted as the familiar colon-separatedusername/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 andmodify .htpasswd files..SH "CHROOT".PPchroot() is a system call that restricts the program's viewof the filesystem to the current directory and directoriesbelow it.It becomes impossible for remote users to access any fileoutside 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 meansthe program must be started as root.However, the last thing it does during initialization is togive up root access by becoming another user, so this is safe..PPNote that with some other web servers, such as NCSA httpd, settingup a directory tree for use with chroot() is complicated, involvingcreating 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 sureany shells, utilities, and config files used by your CGI programs andscripts are available.If you have CGI disabled, or if you make a policy that all CGI programsmust be written in a compiled language such as C and statically linked,then you probably don't have to do any setup at all..PPHowever, 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:.nf    syslogd_flags="-l /usr/local/www/data/dev/log".fiSubstitute 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..SH "MULTIHOMING".PPMultihoming means using one machine to serve multiple hostnames.For instance, if you're an internet provider and you want to letall of your customers have customized web addresses, you mighthave 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..PPOne, 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:.nf  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.fiHowever, this is incompatible with older HTTP/1.0 browsers.If you want to stay compatible, there's a different way - use A recordsinstead, each with a different IP address, like so:.nf  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.fiThis 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 yoursites, you still have to do it this way..PPStep two.If you're using the modern CNAME method of multihoming, then you canskip this step.Otherwise, using the older multiple-IP-address method youmust 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 toall of the different IP addresses.Example:.nf  ifconfig le0 www.acme.com  ifconfig le0 www.joe.acme.com alias  ifconfig le0 www.jane.acme.com alias.fiIf your OS's version of ifconfig doesn't have an alias command, you'reprobably out of luck..PPThird 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 thehostname it's intended for.All you have to do in order to set things up is to create those subdirectoriesin the directory where mini_httpd will run.With the example above, you'd do like so:.nf  mkdir www.acme.com www.joe.acme.com www.jane.acme.com.fiIf you're using old-style multiple-IP multihosting, you should also createsymbolic links from the numeric addresses to the names, like so:.nf  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.fiThis lets the older HTTP/1.0 browsers find the right subdirectory..PPThere's an optional alternate step three if you're using multiple-IPmultihosting: run a separate mini_httpd process for each hostname, usingthe -h flag to specify which one is which.This gives you more flexibility, since you can run each of these processesin separate directories or with different options.Example:.nf  ( 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 ).fiBut remember, this multiple-process method does not work with CNAMEmultihosting - for that, you must use a single mini_httpd process withthe -v flag..SH "CUSTOM ERRORS".PPmini_httpd lets you define your own custom error pages for the variousHTTP errors.There's a separate file for each error number, all stored in onespecial 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 failureerror, 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 theusual built-in error page is generated..PPIf you're using the virtual hosts option, you can also have differentcustom error pages for each different virtual host.In this case you put another "errors" directory in the top of thatvirtual host's web tree.mini_httpd will look first in the virtual host errors directory, andthen in the server-wide errors directory, and if neither of thosehas an appropriate error file then it will generate the built-in error..SH "NON-LOCAL REFERERS".PPSometimes another site on the net will embed your image files in theirHTML 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 willbe blocked.There are three config-file variables for this feature:.TP.B urlpatA wildcard pattern for the URLs that should require a local referer.This is typically just image files, sound files, and so on.For example:.nf  urlpat=**.jpg|**.gif|**.au|**.wav.fiFor most sites, that one setting is all you need to enable referer filtering..TP.B noemptyreferersBy default, requests with no referer at all, or a null referer, or areferer with no apparent hostname, are allowed.With this variable set, such requests are disallowed..TP.B localpatA 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..SH SIGNALS.PPmini_httpd will terminate cleanly upon receipt of a number of differentsignals, 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 getsclosed immediately, which means a fresh mini_httpd can be started upright away.This is convenient when you're rotating your log files..PPIn 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 usingchroot() then the log file must be within the chroot tree, but it'sdefinitely doable..SH CERTIFICATES.PPIf 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 thelists at http://www.apache-ssl.org/#Digital_Certificates andhttp://www.modssl.org/docs/2.4/ssl_faq.html#ToC23.PPYou can also create one for yourself, using the openssl tool.Step one - create the key and certificate request:.nf    openssl req -new > cert.csr.fiStep two - remove the passphrase from the key:.nf    openssl rsa -in privkey.pem -out key.pem.fiStep three - convert the certificate request into a signed certificate:.nf    openssl x509 -in cert.csr -out cert.pem -req -signkey key.pem -days 365.fiThis 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..SH "SEE ALSO"htpasswd(1), weblog_parse(1), http_get(1).SH AUTHORCopyright