7.4. thttpd

The thttpd server, from Jef Poskanzer (http://www.acme.com/software/thttpd/), is a throttling, simple web server with a small footprint. The first "t" in thttpd stands for "tiny," "turbo," or "throttling," depending on whom you ask. It is a very simple, carefully programmed HTTP server that provides basic services and can execute CGI programs. It does not have a plug-in API like Apache. There is a commercial version (Premium thttpd) that incorporates FastCGI support. To the extent that most programming of dynamic content can be done through CGI, most dynamic content can be done with thttpd. However, PHP and some Perl programs running as CGI programs may perform poorly. In high security situations, its limited feature set and its built-in ability to do complex throttling on web traffic are invaluable. Some sites even use a combination of Apache and thttpd to distribute their dynamic and static content, respectively. For example, the interactive web pages that require executing complex Perl or PHP or Java will be served by the Apache server, but the images and other static content is served via thttpd. This has the advantage of speeding up the access to images and other static content, but also gives the ability to throttle bandwidth usage in the event of a sudden burst of heavy traffic.

The thttpd server is often the right answer if your needs are characterized by serving static web pages and running straightforward CGI programs. It can also be the right answer if you want to limit your bandwidth using well-formulated throttling rules. Finally, it is very useful for its small footprint, both on disk and in RAM. If you're resource-constrained (e.g., an embedded environment), then thttpd is probably a better fit than Apache. If, however, you need SSL, thttpd is probably the wrong choice. While there are ways to make it work, they are poorly documented and not directly supported by the web server software itself.

7.4.1. Installing thttpd

thttpd is easily built and installed from ports on both OpenBSD and FreeBSD from ports/www/thttpd.

On FreeBSD the port will install a /usr/local/etc/rc.d/thttpd.sh startup script that is responsible for starting thttpd. This script actually launches a wrapper named thttpd_wrapper, which restarts the thttpd daemon should it die for some reason, and sends a mail message to root. Note that this could be a mail bomb waiting to happen. If you should accidentally misconfigure your thttpd.conf file, you could find the wrapper program sending mail to root every 10 seconds until you have it fixed.

The OpenBSD version of the port installs nothing more than a /usr/local/sbin/thttpd binary. You have to create your own process for launching thttpd at boot time. Fortunately, the thttpd.sh script and the thttpd_wrapper script can be found in the source tree where you built the port (ports/www/thttpd/w-thttpd-2.25b/thttpd-2.25b/scripts/ at the time of this writing). You can easily install them manually.

Note that if you already have Apache installed and active, thttpd will probably fail to run. Apache comes before thttpd alphabetically, so apache2.sh will execute before thttpd.sh at boot time. It will bind to port 80 and thttpd will quit because it cannot acquire the already bound port. Either configure Apache so it does not listen on port 80, or disable it if you are not using it.

7.4.2. Configuring thttpd

Unlike Apache, thttpd does not come with a default configuration file, and the ports maintainer has not chosen to offer one. Example 7-12 shows a basic thttpd.conf file that tries to emulate a similar layout to that provided by a default Apache installation.

Example 7-12. Sample thttpd.conf file

dir=/usr/local/www/data cgipat=/cgi-bin/* logfile=/var/log/httpd-access.log pidfile=/var/run/httpd.pid index_names=index.html index.htm

No fully fleshed-out examples of thttpd.conf files ship with thttpd, but you can find a few on the Internet. However, there really are very few options to specify. The normal options that you need are so few in number, in fact, that you can often specify a working configuration right from the command line.

Just because you can specify a configuration on the command line does not mean you should. We are merely trying to illustrate the simplicity of thttpd configuration. After all, configuration files can be version controlled. The command-line interface exists, however, to be used for quick-and-dirty testing.

The configuration in Example 7-12 is really the minimum set of options that you need to set to make a functional web site. CGI programs necessarily must live under dir. Because of thttpd's design, however, there is no danger that the source of a script will be sent instead of the script.

There is also a convenient program called makeweb that is distributed with thttpd. When invoked, it will create a directory named /usr/local/www/user and create a symbolic link from /home/user/public_html to /usr/local/www/user. This allows the Apache style per-user URLs (provided by mod_userdir) to work, and it provides the familiar public_html directory for users.

7.4.3. Resisting Denial of Service

The throttling parameters in thttpd are completely different from those in Apache. With thttpd, each bandwidth allocation is given a minimum (implied as zero if not specified) and a maximum. The server tracks moving averages for all URLs that it processes, and it matches them against the throttling parameters. If the given URL is exceeding its bandwidth allocation, thttpd imposes a delay between transmitting blocks of data for the connections that are requesting that URL. It also guarantees a minimum bandwidth allocation to make sure that requests actually complete.

The thttpd server does not implement a means of limiting the total number of concurrent connections to the server like Apache's MaxClients directive. However, this kind of limit can be enforced by the operating system. To impose a limit on it, limit the total available file handles for the process. Each network connection requires a file handle, so limiting the total number of open file handles an easy way to limit the number of concurrent connections. Add a line to the thttpd.sh script like ulimit -n 80, to limit the thttpd daemon to 80 open file handles. Each daemon probably has at least two file handles open at any given instant: the web page it's reading off the disk and the network port it is connected to. It may open other files briefly as a side-effect of normal execution (e.g., /dev/null or /etc/malloc.conf). If you're going to limit httpd this way, you should probably start with a number about twice as large as the total number of daemons you want, and then tune according to your observations.

OpenBSD limits the number of available file handles to 128 by default for root and daemon processes through a setting in /etc/login.conf. FreeBSD has the same capability of limiting file descriptors in /etc/login.conf, but does not impose any limits by default.