The Common Gateway Interface is nearly as old as the web server itself. NCSA added the CGI 1.0 specification to version 1.0 of the granddaddy of all web servers, httpd. CGI 1.1, the current specification, was added to the 1.2 release. Every popular web server package developed since then has incorporated CGI as a way—usually the way—for web-borne visitors to access server-based executables.

CGI works well with small or infrequently used programs in which their sole function is to respond to one-time requests, such as processing simple information from HTML forms. There's no sense in clogging up your memory or process table with small applications invoked only a few times an hour.

The opposite is true, however, for complex or frequently used programs. Your web server can slow to a crawl if your site depends on a script with a long initialization process; in particular, one that involves connecting to a database or reading and structuring information from large text files. Speed issues are even more critical for small sites with servers that also process mail, FTP or DNS requests.

CGI applications must be launched anew with each invocation, a limitation that leads to two problems. First, the hardware and operating system have to deal with the overhead of creating a process for every CGI request. Second, CGI scripts can't handle persistent variables or data structures; they must be rebuilt with each invocation.

Open Market's FastCGI interface is one way to overcome CGI's limitations. FastCGI applications are invoked via URLs just like their CGI counterparts. The difference is that they're persistent; they function like servers within a server. FastCGI offers benefits in three areas:

FastCGI is not the first—nor, I'm sure, will it be the last—approach to move beyond CGI. Most web servers have APIs that allow developers to write new functions right into the server. Doug MacEachern's mod_perl module allows the Perl runtime library to be compiled directly into Apache, giving hackers the ability to write server modules entirely in Perl.

I prefer FastCGI to its alternatives for four reasons:

My server platform is a fairly standard Linux box: a 120MHz Pentium with 64MB RAM running the 2.0.27 kernel. If you already get decent performance from your hardware, you won't have any trouble with FastCGI.

As to software, I use Apache and Perl; the material below is unabashedly biased in their favor. If you want to do your coding in C/C++, tcl, Java or Python, or if you want to use different server software, I suggest you visit http://fastcgi.idle.com/ for further information. On the other hand, most of the coding hints I'll be providing are applicable to any language.

To use Perl and Apache, you'll need to do some recompiling. Apache needs to be rebuilt with the FastCGI module. You'll also have to compile a Perl module. A few months ago you would have needed to rebuild Perl—I'll provide instructions in case you need or want to do so—but now can probably get by on your current Perl build. Even if you're not an accomplished C programmer, however, the compilation process is fairly painless. Here's what you'll need:

Once you've gathered the necessary source code, you'll be ready to spend some quality make time. Compilation is done in two segments: Perl and Apache. Either can be done first, but within each segment the steps have to be completed in a certain order.

Unless you know you need to recompile the Perl binary, you can skip down to the “Compiling FCGI.pm” section. If, however, you do need to recompile Perl, it's helpful to know a few things.

To begin the Perl compilation process, unpack and build sfio; the README will tell how. You'll also have to update your $PATH to include one of the newly created subdirectories; this is somewhat unusual, but required.

Second, build, test and install Perl. It can take awhile to work through Larry Wall's Configure script, but there are a few items for which you should not choose the default answer:

I've never had trouble re-compiling Perl in this way, but the fastcgi-developers mailing list archive (available from http://www.findmail.com/list/fastcgi-developers/) has plenty of messages from people who have. A fairly complete set of directions for recompiling Perl with sfio can be found at http://fastcgi.idle.com/fcgi2.0b2.1/doc/fcgi-perl.htm.

Regardless of whether you had to recompile Perl, you'll need to unpack, build, test and install FCGI.pm according to the instructions provided with the source code. You can be fairly sure you're on the right track if FCGI.pm passes make test.

Before dealing with the Apache distribution, unpack the mod_fastcgi source code. Read the INSTALL file, which details the two ways to configure, compile, and install Apache. The first, the Apache Autoconf-style Interface (APACI), is new to version 1.3. The second is the tried-and-true manual configuration we all know and love. Then unpack Apache's source code and configure it for the FastCGI interface:

Apache gets all of its runtime directives from three files found in $apache/conf: access.conf, httpd.conf and srm.conf. Following the suggestion given by Ben and Peter Laurie in Apache: the Definitive Guide, I put all directives in httpd.conf and don't use the other two files. If you use all three files, the configuration changes will occur in srm.conf.

Before doing any configuration, you'll need to read the documentation included with the mod_fastcgi source code. The docs/mod_fastcgi.html document is somewhat dated, but still very useful for getting you started. No author is listed, but I'd gladly buy him or her a beer for putting together a truly excellent resource, and thereby making my job much simpler.

Let me also say that you should have more than a passing familiarity with httpd.conf before altering it. Take a good look at the documentation that comes with the source code or buy yourself a copy of the Lauries' book.

The FastCGI configuration directives (see sidebar “Configuring Apache for FastCGI”) allow you to accomplish two essential tasks.

First, define the local pathway to the FastCGI applications using the AppClass directive and/or the remote connection host and port number via ExternalAppClass. AppClass is responsible for starting and managing processes that run locally.

Second, associate your FastCGI applications with the proper handler or MIME type so that dealings with these files are handled by mod_fastcgi. Associate the handler “fastcgi-script” with a file or files based on location (SetHandler) or file extension (AddHandler). Alternately, you can associate the MIME type

application/x-httpd-fcgi

with a file or files based on location (ForceType) or file extension (AddType).

Note that your FastCGI applications cannot go into the normal CGI directory specified by ScriptAlias. Apache's way of assigning priorities leads it to attempt to handle any and all files in the CGI directory with the standard CGI module, which won't work with FastCGI applications.

In many ways, writing FastCGI scripts is not very different from traditional CGI programming. You must specify a Content-type (typically, “text/html”) if you're providing content. You can use Location and Status to specify redirects or other HTTP messages. Also, you have normal access to the %ENV hash.

From within scripts, STDIN and STDOUT can be accessed, but only in standard ways. The FastCGI library manipulates those data streams quite heavily; you can print without trouble, but more advanced operations will fail. You can't, for example, send a reference to a typeglob (a symbol table entry) of STDOUT (\*STDOUT) to a forked process. In fact, FastCGI is fairly scornful of forking, and I haven't heard any reports at all from someone trying to run it on a thread-enabled version of Perl 5.005.

The main difference, structurally speaking, between CGI and FastCGI scripts is that the main body of code is placed within a while loop, one which hopefully never ends. The basic structure of a FastCGI script is pretty much the same regardless of its task:

Although FastCGI will force few substantive changes in your code, it will likely change your perspective on what makes a good script. Some of the lessons I've learned while developing FastCGI applications are:

Webmasters of commercial sites hate to admit it, but getting advertisements on-line is an increasingly unavoidable fact of the job. If you have multiple sponsors in a rotation, or if your sponsors each have multiple ads, there's no way to hardcode the ad into a page stored on disk. Of course, this is true for any information likely to be presented on a rotating basis: news, current specials or random links.

The rotate.fcg script shown in Listing 1 provides a bare-bones approach to meeting that need. It provides a persistent array of ad information that can be inserted wherever you choose on any disk-based document. It also allows the ad array to be updated without having to re-start the script (although this technique won't work if you're running multiple instances of the script).

Based on the Apache configuration shown in the Apache sidebar, the URL to invoke the script is http://www.yoursite.com/fastcgi-bin/rotate.fcg?page.html, where “page.html” is the name of a document into which you'd like to insert an ad. page.html can contain one or more instances of an HTML comment that serves as a placeholder for the ad:

<!-- Ad Here -->

Using an HTML comment in this capacity means that the document will display correctly, even if you have no ad to put there yet.

The script's opening section scopes and initializes all variables to be used for the life of the process. Three things are worthy of note in this section. First, since we initialize @ads outside the loop, it will stay persistent for the life of the script. Second, we need to initialize the %ENV array ourselves, lest we find it empty later on down the line. Third, we set $| to a non-zero number, because we want to flush STDOUT every time the script is invoked.

Right before the script enters the main loop, it initializes the array of ads by calling the initialize routine. This routine reads a text file of the sort shown in Listing 2. The data for each sponsor are temporarily put into the %sponsor hash, formatted into HTML and pushed into the @ads array. If the text file can't be opened, the routine returns an empty array, allowing the script to run anyway.

The main action takes place in the loop labeled REQUEST. The while command is the only place the script interacts explicitly with FCGI.pm. It's also the only substantive difference between a FastCGI script and a traditional one. Regardless of the language you use for FastCGI programming, a loop like this one will be the structure in which you frame the script's main process.

Once in the loop, the first task is to allow the webmaster to re-initialize the ad array on the fly. In the example script, this is accomplished by placing a request to http://www.yoursite.com/fastcgi-bin/rotate.pl?reload. To provide a little security, the script allows re-initialization only from the web server. If you're running multiple instances of a script, you'll have to accomplish this by some other means: restarting Apache with kill -USR1, reloading the data file if its timestamp has changed, etc.

If you used a script like this to run current news headlines, it would be easy to post new updates to your site several times each day by adding them to the text file and re-initializing the array.

The loop's second task is to make sure that the requested file can be opened. If it can't, the script calls a routine (not included in my example) that would send off a “File Not Found” message. By providing its own error message, the script can recover gracefully from a bad request without having to die off. If it is available, the requested document is assigned to the @doc array.

Next, an ad is pulled off the front of the @ads array, assigned to $ad, then pushed to the back of the array. The script retains a copy of the ad, even though it's been put back in the array.

Fourth, the script cycles through the document looking for any instances of <!-- Ad Here -->. When it finds one, it substitutes the $ad for it. If the text file containing the ads is empty or unopenable, or if the requested page has no place for an ad, no substitutions are made.

Finally, the script prints the appropriate HTTP header, sends off the document and heads back to the front of the loop to wait for the next request.

My example script doesn't tackle many of the tasks at which FastCGI excels: persistent database connections, format translation (e.g., SGML to HTML) or providing common HTML page headers and footers. At the site I manage, I use FastCGI to do all these things and more.

I've found that a FastCGI application can perform its duties, including multiple SQL queries, and deliver a page on the fly only slightly slower than the server can deliver static documents. On a 10Mbps LAN connection the speed difference is perceptible, but just barely, and only if I'm looking for it. Over a 128Kbps or slower connection, I notice no difference.

I still use CGI to perform simple, infrequently needed tasks. A CGI script doesn't hog system resources for very long. For complex, frequently invoked tasks, FastCGI provides a great combination of flexibility and speed.

The two listings referred to in this article are available by anonymous download in the file ftp.linuxjournal.com/pub/lj/listings/issue55/2607.tgz.