diff options
Diffstat (limited to 'mini_httpd.8')
| -rw-r--r-- | mini_httpd.8 | 455 |
1 files changed, 455 insertions, 0 deletions
diff --git a/mini_httpd.8 b/mini_httpd.8 new file mode 100644 index 0000000..8c4695e --- /dev/null +++ b/mini_httpd.8 @@ -0,0 +1,455 @@ +.TH mini_httpd 8 "05 October 1999" +.SH NAME +mini_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_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: +.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. +.PP +It can also be configured to do SSL/HTTPS. +.PP +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. +.SH OPTIONS +.TP +.B -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. +.TP +.B -p +Specifies an alternate port number to listen on. +The default is 80. +The config-file option name for this flag is "port". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -v +Do virtual hosting. +See below for details. +The config-file option name for this flag is "vhost". +.TP +.B -l +Specifies a log file name. +The default is no logging. +The config-file option name for this flag is "logfile". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -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". +.TP +.B -V +Shows mini_httpd's version and then exits. +.SH "CGI" +.PP +mini_httpd supports the CGI 1.1 spec. +.PP +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. +.SH "BASIC AUTHENTICATION" +.PP +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. +.SH "CHROOT" +.PP +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. +.PP +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. +.PP +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: +.nf + syslogd_flags="-l /usr/local/www/data/dev/log" +.fi +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. +.SH "MULTIHOMING" +.PP +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. +.PP +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: +.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 +.fi +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: +.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 +.fi +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. +.PP +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: +.nf + ifconfig le0 www.acme.com + ifconfig le0 www.joe.acme.com alias + ifconfig le0 www.jane.acme.com alias +.fi +If your OS's version of ifconfig doesn't have an alias command, you're +probably out of luck. +.PP +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: +.nf + mkdir www.acme.com www.joe.acme.com www.jane.acme.com +.fi +If you're using old-style multiple-IP multihosting, you should also create +symbolic 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 +.fi +This lets the older HTTP/1.0 browsers find the right subdirectory. +.PP +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: +.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 ) +.fi +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. +.SH "CUSTOM ERRORS" +.PP +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. +.PP +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. +.SH "NON-LOCAL REFERERS" +.PP +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: +.TP +.B 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: +.nf + urlpat=**.jpg|**.gif|**.au|**.wav +.fi +For most sites, that one setting is all you need to enable referer filtering. +.TP +.B 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. +.TP +.B 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. +.SH SIGNALS +.PP +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. +.PP +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. +.SH CERTIFICATES +.PP +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 +.PP +You can also create one for yourself, using the openssl tool. +Step one - create the key and certificate request: +.nf + openssl req -new > cert.csr +.fi +Step two - remove the passphrase from the key: +.nf + openssl rsa -in privkey.pem -out key.pem +.fi +Step three - convert the certificate request into a signed certificate: +.nf + openssl x509 -in cert.csr -out cert.pem -req -signkey key.pem -days 365 +.fi +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. +.SH "SEE ALSO" +htpasswd(1), weblog_parse(1), http_get(1) +.SH AUTHOR +Copyright © 1999,2000 by Jef Poskanzer <jef@mail.acme.com>. All rights reserved. +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. |