BSD DevCenter
oreilly.comSafari Books Online.Conferences.


Lightweight Web Serving with thttpd
Pages: 1, 2, 3

Running CGI Scripts

The easiest way to run CGI scripts from within the just-installed server is to disable the chroot feature (by removing the thttpd_flags line from /etc/rc.conf). However, considering all the security advantages the feature brings, this is a bad idea. You can still run CGIs inside the chroot jail, although it is a bit more complicated.

Create a simple CGI application for testing. Shell scripting is used in order to make explanations easier; you can use any appropriate language you prefer.

# mkdir /home/www/cgi-bin
# cat >/home/www/cgi-bin/

echo "Content-type: text/html"
echo "Hello, world!"
# chmod +x /home/www/cgi-bin/

With this in place, add the following form code to the web page you created before, /home/www/index.html:

<form name="hello" method="post" action="/cgi-bin/">
  <input type="submit" value="Run it!" />

If you try to access the page and click on the button, thttpd will spit out an error. What happened? The script could not find the shell interpreter, /bin/sh, specified on the first line. (Being chrooted, thttpd considers all paths relative to /home/www/.) To solve this, copy the file, as well as any other required stuff, inside the jail. (It would be a lot easier with a static build of sh.) A simple way to do this is:

# cd /home/www
# mkdir bin
# cp /bin/sh bin
# ldd bin/sh
        -ledit.2 => /lib/
        -ltermcap.0 => /lib/
        -lc.12 => /lib/
# mkdir lib
# cp /lib/ lib
# cp /lib/ lib
# cp /lib/ lib
# mkdir libexec
# cp /libexec/ld.elf_so libexec
# chown -R root:wheel bin lib libexec

Depending on the applications you need inside the chroot, things will get more complicated: you may need to create device files, a user database, pipes, and so on. As an exercise, try to make Perl work.

After putting everything into the correct place, try clicking on the button again and all should be fine: you should receive the "Hello, world!" message in response.

Virtual Hosts

thttpd supports virtual hosts. Setting them up is extremely easy. The first thing you need to do is make all the domain names you want to serve point to the machine running thttpd. This basically means setting up extra CNAMEs for the main host's name, but that is a DNS-specific task. Refer to your name server's documentation for more information, or ask your DNS administrator to do it for you.

Having the domain names adjusted accordingly, the next step is to enable support for virtual hosts. Add the vhost option to the configuration file (on a line of its own):

# echo vhost >>/usr/pkg/etc/thttpd.conf

After adding this option (and restarting the server), the behavior of the documents directory (/home/www/) will change completely: it will no longer hold HTML pages nor any other file. Instead, it will have a set of subdirectories, each one associated to one of the virtual hosts served. The name of each directory is the name of the virtual host's name or IP address. For example, supposing you want to serve web pages for the domains and, your documents directory could contain:

# ls -lF /home/www/
total 4
drwxr-xr-x  2 root  www  512 Sep  4 22:48
drwxr-xr-x  2 root  www  512 Sep  4 22:48

Yes, it is that simple!

Running Alongside Other Servers

The beginning of the article mentioned that another use of thttpd is to serve static content alongside powerful web servers. The easiest way to do that is to start thttpd on a different port than the other servers, which requires adding an extra line to the configuration file:

# echo port=8080 >>/usr/pkg/etc/thttpd.conf

I assume that if you have done this, it is because you have a full-featured web server in the same machine as thttpd. Therefore, you need to modify the web pages it serves to point to the static content now served under http://localhost:8080/.


This article has shown how to install and configure the lightweight thttpd web server on a step-by-step basis. This application has several other features; if you want to learn more, spend some time reading the thttpd manual or the accompanying thttpd notes, which deal with several design decisions--an interesting read, certainly.

Of course, there are many more simple HTTP servers available on the internet. If this one does not fit your needs, there probably is another one that does.

Julio M. Merino Vidal studies computer science at the FIB faculty in Barcelona, Spain.

Return to the BSD DevCenter.

Sponsored by: