.TH thttpd 8 "12 October 1995" .SH NAME thttpd - tiny/turbo/throttling HTTP server .SH SYNOPSIS .B thttpd .RB [ -p .IR port ] .RB [ -d .IR dir ] .RB [ -r | -nor ] .RB [ -u .IR user ] .RB [ -c .IR cgipat ] .RB [ -t .IR throttles ] .RB [ -h .IR host ] .RB [ -l .IR logfile ] .SH DESCRIPTION .PP .I thttpd is a simple, small, fast, and secure HTTP server. It doesn't have a lot of special features, but it suffices for most uses of the web, it's about as fast as the best full-featured servers (Apache, NCSA, Netscape), and it has one extremely useful feature (URL-traffic-based throttling) that no other server currently has. .SH OPTIONS .TP .B -p Specifies an alternate port number to listen on. The default is 80. Relevant config option: DEFAULT_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. Relevant config options: WEBDIR, USE_USER_DIR. .TP .B -r Do a chroot() at initialization time, restricting file access to the program's current directory. If -r is the compiled-in default, then -nor disables it. See below for details. .TP .B -u Specifies what user to switch to after initialization when started as root. The default is "nobody". Relevant config option: DEFAULT_USER. .TP .B -c Specifies a pattern for CGI programs. See below for details. .TP .B -t Specifies a file of throttle settings. See below for details. .TP .B -h Specifies a hostname to bind to, for multihoming. The default is to bind to all hostnames supported on the local machine. See below for details. .TP .B -l Specifies a file for logging. If no file is specified, thttpd logs via syslog(). .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 The program can also be compile-time configured to always do a chroot(), without needing the -r flag. .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 thttpd 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 Relevant config option: ALWAYS_CHROOT. .SH "CGI" .PP thttpd supports the CGI 1.1 spec. .PP In order for a CGI program to be run, its name must match the pattern specified either at compile time or on the command line with the -c flag. This is a simple shell-style filename pattern, with ? and *, or 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. .PP Restricting CGI programs to a single directory lets the site administrator review them for security holes, and is strongly recommended. If there are individual users that you trust, you can enable their directories too. .PP If no CGI pattern is specified, neither here nor at compile time, then CGI programs cannot be run at all. If you want to disable CGI as a security measure, that's how you do it, just comment out the patterns in the config file and don't run with the -c flag. .PP Note: the current working directory when a CGI program gets run is the directory that the CGI program lives in. This isn't in the CGI 1.1 spec, but it's what most other HTTP servers do. .PP Relevant config options: CGI_PATTERN, CGI_TIMELIMIT, CGI_NICE, CGI_PATH, CGIBINDIR. .SH "BASIC AUTHENTICATION" .PP Basic Authentication is available as an option at compile time. If enabled, it uses a password file in a served directory, called .htpasswd by default. 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. .PP Relevant config option: AUTH_FILE .SH "THROTTLING" .PP The throttle file lets you set maximum byte rates on URLs or URL groups. There is no provision for setting a maximum request rate throttle, because throttling a request uses as much cpu as handling it, so there would be no point. .PP The format of the throttle file is very simple. A # starts a comment, and the rest of the line is ignored. Blank lines are ignored. The rest of the lines should consist of a pattern, whitespace, and a number. The pattern is a simple shell-style filename pattern, using ? and *, or multiple such patterns separated by |. .PP The numbers in the file are byte rates, specified in units of bytes per second. For comparison, a v.32b/v.42b modem gives about 1500/2000 B/s depending on compression, a double-B-channel ISDN line about 12800 B/s, and a T1 line is about 150000 B/s. .PP Example: .nf # throttle file for www.acme.com * 100000 # limit total web usage to 2/3 of our T1 *.jpg|*.gif 50000 # limit images to 1/3 of our T1 *.mpg 20000 # and movies to even less jef/* 20000 # jef's pages are too popular .fi .PP Throttling is implemented by checking each incoming URL filename against all of the patterns in the throttle file. The server accumulates statistics on how much bandwidth each pattern has accounted for recently (via a rolling average). If a URL matches a pattern that has been exceeding its specified limit, then the data returned is actually slowed down, with pauses between each block. If that's not possible (e.g. for CGI programs), then the server returns a special code saying 'try again later'. .SH 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. .PP One, make DNS entries for all of the hostnames. They should just be plain old A records, each with a different IP address. Example: .nf www.acme.com IN A 192.100.66.10 www.joe.acme.com IN A 192.100.66.200 www.jane.acme.com IN A 192.100.66.201 .fi .PP Two, use ifconfig(8)'s alias command to tell the machine's network interface 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 (but see http://www.acme.com/software/thttpd/notes.html). .PP Three, run a separate thttpd process for each hostname using the -h flag to specify which one is which. You can also run each of these processes in separate directories, with different throttle files, etc. Example: .nf thttpd -r -d /usr/www -h www.acme.com -c 'cgi-bin/*' & thttpd -r -d /usr/www/joe -u joe -h www.joe.acme.com & thttpd -r -d /usr/www/jane -u jane -h www.jane.acme.com & .fi Note how the company server allows CGI programs, while the others do not. That's a good compromise on the security issue - customers who want to install CGI programs give them to you for review, and if they're ok then you put them in the company directory. .SH SYMLINKS .PP thttpd is very picky about symbolic links. Before delivering any file, it first checks each element in the path to see if it's a symbolic link, and expands them all out to get the final actual filename. Along the way it checks for things like links with ".." that go above the server's directory, and absolute symlinks (ones that start with a /). These are prohibited as security holes, so the server returns an error page for them. This means you can't set up your web directory with a bunch of symlinks pointing to individual users' home web directories. Instead you do it the other way around - the user web directories are real subdirs of the main web directory, and in each user's home dir there's a symlink pointing to their actual web dir. .PP The CGI pattern is also affected - it gets matched against the fully-expanded filename. So, if you have a single CGI directory but then put a symbolic link in it pointing somewhere else, that won't work. The CGI program will be treated as a regular file and returned to the client, instead of getting run. This could be confusing. .SH LOGS .PP thttpd does all of its logging via syslog(3). The facility it uses is configurable. Aside from error messages, there are only a few log entry types of interest, all fairly similar to CERN Common Log Format: .nf Aug 6 15:40:34 acme thttpd[583]: 165.113.207.103 - - "GET /file" 200 357 Aug 6 15:40:43 acme thttpd[583]: 165.113.207.103 - - "HEAD /file" 200 0 Aug 6 15:41:16 acme thttpd[583]: referer http://www.acme.com/ -> /dir Aug 6 15:41:16 acme thttpd[583]: user-agent Mozilla/1.1N .fi The package includes a script for translating these log entries info CERN-compatible files. Note that thttpd does not translate numeric IP addresses into domain names. This is both to save time and as a minor security measure (the numeric address is harder to spoof). .PP Relevant config option: LOG_FACILITY. .PP If you'd rather log directly to a file, you can use the -l command-line flag. But note that error messages still go to syslog. .SH "SEE ALSO" nph-redirect(8), ssi(8), makeweb(1), htpasswd(1), syslogtocern(8), weblog_parse(1), http_get(1) .SH THANKS .PP Many thanks to reviewers and testers: John LoVerso, Jordan Hayes, Chris Torek, Jim Thompson, Barton Schaffer, Geoff Adams, Daniel Kegel, John Hascall. Special thanks to Craig Leres for substantial debugging and development, and for not complaining about my coding style very much. .SH AUTHOR Copyright (C)1995,1998 by Jef Poskanzer . 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.