#ToC Index Next Previous

Apache Server Survival Guide asgxc.htm

Previous Page TOC Next Page

_________________________________________________________________

* FastCGI Features
* Performance Enhancement
* FastCGI API
* What a FastCGI Application Looks Like
+ FastCGI and C
+ FastCGI with Perl and Tcl
* Installing and Configuring FastCGI
+ Incorporating FastCGI Functionality into Apache
+ cgi-fcgi
* Building the FastCGI Developer's Kit
* Making Perl Fly
+ Perl FastCGI Programs
* The mod_fastcgi Module
+ The AppClass Directive
+ Example
* Summary
_________________________________________________________________

FastCGI

FastCGI is a high-performance replacement to the CGI standard. It

provides a significant improvement in performance over the existing
CGI interface. In its current implementation, FastCGI provides many
desirable enhancements that make it a very attract ive and competitive
alternative to proprietary technologies for developing Web-based
applications. Under many circumstances, it will be a better choice to
implement FastCGI than to develop a custom server module using
Apache's proprietary server Applicati on Programmer's Interface (API).
______________________________________________________________

NOTE: FastCGI is available from http://www.fastcgi.com. (See Figure

C.1.) The site is the official resource to all FastCGI information.
It has complete documentation and whitepapers on FastCGI. Also n
ice is a mailing list-a threaded archive that is available through
the Web.
______________________________________________________________

Figure C.1. The FastCGI home page.

FastCGI is a proposed open standard; this means that it is not

currently widely accepted, but it has received a warm welcome by many
significant people on the Internet who are responsible for setting the
standards. More than likely, this welcome will t urn into acceptance
on both free and commercial Web server offerings, which will help it
in becoming "blessed" from a standard point of view.

FastCGI is appealing not only because of its performance enhancements

but because the effort required to migrate existing code is very
small. As a bonus, software developed under this proposed standard has
a high degree of portability. These portabilit y issues help a great
deal toward setting it as a viable candidate to become a standard,
especially on installations that have committed extensive resources to
CGI development.

FastCGI is not a development environment in terms of having to learn

yet another programming language. In a very simplistic description,
FastCGI it is a CGI program that uses additional libraries, so it does
require that you learn an API. The basic API is tiny, though; one call
is all you need to migrate many of your current programs.

FastCGI Features

The main features of FastCGI are as follows:

* A huge increase in performance. FastCGI programs continue to live
between requests, making their responsiveness faster and reducing
delays due to forking and program initialization.
* Programming language-independent implementation. Like CGI, you can
develop your FastCGI application with a variety of languages.
Currently there are programming libraries for Perl, C/C++, Tcl,
and Java. Porting existing code to FastCGI is easy, allowi ng you
to easily migrate your existing code base without having to redo
what you have done.
* FastCGI processes are isolated from the Web server core. Much like
CGI, FastCGI applications offer greater security and reliability
than developing a similar functionality as a module using a server
API.
* Server technology separation. There are FastCGI modules for
various servers, including Apache, NCSA, and the Open Market
Secure WebServer. For any other server that supports CGIs, the
cgi-fcgi program, included in the FastCGI distribution, implements
the FastCGI environment.
* Distributed computing support. FastCGI applications can execute on
a different host from the Web server. This allows you to offload
FastCGI execution to other application servers, permitting your
Web server to handle an increased load. FastCGI program s can run
on any host that can be reached over TCP/IP.
* The concept of roles. Traditional CGI programs fall into the
responder role; they respond to some action initiated by a browser
and send back some HTML. FastCGI programs can also perform other
roles, such as a filter or as part of some authenti cation scheme.
This allows for providing extra functionality that would usually
be relegated to a server module. The currently available FastCGI
module for Apache does not include support for roles other than
responder, but this may change in the future.

Performance Enhancement

The increase in performance alone would be a good enough reason to

migrate CGIs to FastCGI, especially on loaded servers. This increase
in performance is achieved primarily because FastCGI processes are
persistent. Forking under UNIX is very expensive, and FastCGI
addresses this issue by reusing processes. This saves on the
initialization time and can also provide enhancements when data
calculated by one call to the program can be reused in another
transaction.

Unlike CGIs, which are forked every time there's a request for the
functionality, FastCGI processes are reused. After a request is
fulfilled, the process remains, waiting for additional requests.

Programs that rely on an interpreter such as Perl or Tcl can gain a

great deal from this technology because the command interpreter will
compile the program once, not once per call. The time required to do
all this pre-run initialization is eliminated. On the program side,
this can yield to enhancements such as establishing a connection with
a database or some other process because the connection only needs to
happen once. Add to this the load to launch the interpreter program,
and the savings are sign ificant.

What sort of performance gains can you obtain? According to

information posted on the FastCGI Web site, Open Market's tests show
the following:

Request Client, Server, and Application Processing Time

Static File 21ms + 0.19ms/KB
FastCGI 22ms + 0.28ms/KB
CGI 59ms + 0.37ms/KB

Add to this the cumulative time that it takes for an application to

establish a TCP/IP connection to, say, a database. Under CGI, a
process will have to initialize each time it is run. FastCGI can yield
a performance increase of four times the speed of the same program
used as CGI. In load terms, this could mean that your server could
potentially handle four times your current CGI load. However, the
level of enhancement will depend on the source of the bottleneck. If
your database server is the current source of the problem, FastCGI
cannot do much about that except reduce the number of connections that
the database server will need to perform, perhaps giving it more time
to process data instead.

FastCGI API

The FastCGI API has a handful of calls:

* FCGI_Accept is used to implement the server connectivity and
control the running of the FastCGI program.
* FCGI_Finish gives you control after the FastCGI program has
executed, but before running the next request.
* FCGI_SetExitStatus is used to set the exit status of the request.
Most CGI programs don't return meaningful exit status, so this
call is seldom used.
* FCGI_StartFileterData enables you to implement a special type of
FastCGI application, called a filter. Currently the Apache
implementation of the FastCGI module doesn't support roles, of
which the filter type is a member, but this likely will c hange in
the near future. Filters allow you to implement programs that will
convert one data format to another on-the-fly (for example, TIFF
to GIF).

Data is read and written through the standard input, output, and error
streams. FastCGI also provides macros that map files and streams to
native calls supported by your operating system.

Like CGI, you can create FastCGI applications in almost any language.
However, you are currently limited to the ports of the library.
Currently available are Perl, C/C++, Tcl, Java, and very soon Python,
which should be available by the time you read t his. Also in the
works is a multithreaded C/C++ library that has not been released, but
 should be available as part of the 1.6 release. The multithreaded
library allows a single application process to handle concurrent
requests, which will allow you to im plement things like HTTP-based
chat applications.

Even though FastCGI is not universal, most developers should find

themselves at home in one of the programming languages previously
mentioned. As soon as FastCGI gains more acceptance, there will be
additional libraries implemented. Developers are enco uraged to port
the FastCGI libraries to their programming language of choice,
ensuring that the openness of the extension is more widely supported.
The success of FastCGI will depend on getting many vendors and
programmers to support it. Given its current feature set, it should
have no trouble reaching this goal.

The design of FastCGI also wins big on the learning curve because
unlike server APIs, you are still programming a CGI, so you can
leverage what you already know. The only issues that you will need to
address have to do with reorganizing your applicatio n so that the
initialization code, which is done once, is kept separate from the
application body. FastCGI applications are long-lived; they are kept
alive between transactions. This also means that memory needs to be
managed because unlike CGIs, which ha ve a short life span, FastCGI
processes may execute for undetermined amounts of time.

Data sent to a FastCGI application by the server is accessed through

special streams that provide complete binary compatibility with the
CGI standard. This also allows a FastCGI program to run as a regular
CGI program. A FastCGI program can determine, at runtime, if it is
being run as CGI or as FastCGI and behave accordingly.

This translates into an environment that allows you to migrate FastCGI

programs down, should you ever need to. This provides server
independence because the same binary can be run on two servers-say
Apache and Netscape-under the same operatin g system without even
needing to be rebuilt or require programming modifications, even if
the server couldn't support FastCGI. This feature alone is very
interesting from a legacy and recycling standpoint. Also, all servers
support FastCGI. The FastCGI De veloper's Kit comes with a program
called cgi-fcgi that allows you to run FastCGI responder applications.
The cgi-fcgi program allows any Web server that supports CGI to run
FastCGI.

FastCGI applications communicate with Apache using a single

full-duplex connection. Through this connection, the server transmits
the environment variables and stdin to the FastCGI application; stdout
and stderr streams from the application are sent ba ck to the server.

What a FastCGI Application Looks Like

A modified version of my HelloWorld.c looks like this:

#include "fcgi_stdio.h"

#include <stdio.h>

int main (void)

{
 int timesVisited = 0;

while(FCGI_Accept() >=0)

printf ("Content-type: text/html\r\n\r\n");

printf("<HTML>");

printf("<HEAD><TITLE>Hello World!</TITLE></HEAD>");

printf("<BODY><H1>Hello, this is a FastCGI program!</H1>");

printf("<BIG><P>I can tell that you are visiting from %s.</P>");

printf("<p>This page has been accessed: %d times</P></BIG></BODY>", getenv("RE

MOTE_HOST"), ++timesVisited);

printf("</HTML>");

This version makes use of the fact that the application is persistent
and will maintain a count of the times the program is run (until the
program dies).

As you can see from this example, FastCGI applications follow this
sequence:
1. Initialization. Persistent connections or data that should be
available from request to request are initialized in this section.
Initialization is done only once. The initial environment for
FastCGI applications is set through the AppClass directive, which
is added by the FastCGI module.
2. The Response Loop. This loop is started by the FCGI_Accept()
routine, implemented in the FastCGI library. A call to this
routine blocks program execution until the program receives a
client request. When it receives one, the routine unblocks, sets
up an environment for the program, and runs one loop through the
body. This routine is also responsible for determining the context
under which the program is running (FastCGI or CGI) and sets the
environment accordingly.
3. Body. This portion of the program gets executed by each request.
This is the meat of your program. Each request will have its own
environment variables, just as in a regular CGI.
4. End of Response. A subsequent call to FCGI_Accept informs the
server that the program has completed a request and is ready for
another. FCGI_Accept once more blocks execution until the next
request.

This process is repeated until the FastCGI application is killed by

the System administrator or the Web server. If the process were to
die, the FastCGI module or cgi-fcgi program in the Web server is
responsible for making a FastCGI process available t o handle the
request. This means that if it dies, the server will fork another
process to replace the original.
 FastCGI and C

FastCGI implements two libraries: fcgi_stdio and fcgiapp. Both of

these libraries are provided for building C applications utilizing the
FastCGI toolkit.

The fcgi_stdio library implements stdio-compatible functionality and

can be used for developing or porting existing C CGI applications.
This library provides full binary compatibility between FastCGI and
CGI programs.

fcgiapp provides additional functionality to FastCGI applications at

the expense of losing the CGI compatibility. There's also an increase
in the knowledge required to develop the application.

FastCGI with Perl and Tcl

You can run Perl- and Tcl-interpreted programs under FastCGI. In order
to run them, you'll have to compile a specially modified version of
the interpreter that has been modified to work with FastCGI. You will
not, however, need to maintain both a regul ar and a special version
of the interpreter. The special version will work as expected when
used under a normal context. Future versions of Perl and Tcl will
incorporate changes that will make it possible to use unmodified
versions of the program with Fas tCGI.

Patches for both Perl and Tcl are available. Some prebuilt binaries
are also available at http://www.fastcgi.com.

Installing and Configuring FastCGI

To build and run FastCGI applications, you'll need to have two

different pieces of software: the FastCGI module for Apache and the
FastCGI Developer's Kit.

Both the toolkit and the Apache module are included in the CD-ROM that
accompanies this book; however, you should make sure that they are
still current. At the time of this writing, the Apache module was
still based on a beta version of 1.1. The latest and greatest versions
of the module and developer's kit are available at the FastCGI Web
sites: http://www.fastcgi.com/servers and
http://www.fastcgi.com/applibs, respectively. The version of the
toolkit included on the CD-ROM is 1.5.

Incorporating FastCGI Functionality into Apache

To add the FastCGI module to Apache is simple. Copy

apache-fastcgi/src/mod_fastcgi.c to the Apache source directory
(/usr/local/etc/httpd/src). Then you need to add an entry for the
module in Apache's src/Configuration file. Add the following line at t
he end of the Module listings:

Module fastcgi_module mod_fastcgi.o

You'll need to run Apache's configuration program, src/Configure, and

rebuild the Apache by issuing a make command while focused on the
Apache src directory.
 While Apache builds, you can add the following configuration
directives to your servers conf/srm.conf configuration file:

AddType application/x-httpd-fcgi .fcgi

Alias /fcgi-bin/ /usr/local/etc/httpd/fcgi-bin

# AppClass

Create the fcgi-bin directory, while in /usr/local/etc/httpd:

% mkdir fcgi-bin

As you may be able to guess by now, FastCGI applications should be run

from a directory other than the cgi-bin directory.

After Apache builds, issue the following commands:

% cd /usr/local/etc/httpd

% mv httpd httpd.prev

% mv src/httpd .

% strip httpd

% kill -HUP 'cat /usr/local/etc/httpd/logs/httpd.pid`

This will restart the server and force rereading of the new
configuration directives you just added. Watch for any error messages.
If you get an error, more than likely one of the directives you added
is incorrect.

If the restart of the server proceeded without problems,

congratulations-your sever is now ready to run FastCGI programs.

cgi-fcgi

An alternative way of implementing FastCGI on Apache, or any other

server, is to use the cgi-fcgi program. cgi-fcgi is a standard CGI
program that uses TCP/IP sockets to communicate with FastCGI
applications. cgi-fcgi takes the pathname or host/port na me as a
parameter and connects to the FastCGI application listening on that
TCP port. cgi-fcgi then forwards the environment variables and stdin
to the FastCGI application and returns to the server the stdout and
stderr streams. When the FastCGI applicati on ends the connection,
cgi-fcgi flushes and exits.

Although this is not as efficient as a module imbedded into the server

because the cgi-fcgi program gets forked with every request, it is
much better than not having it. For example, if your Perl FastCGI
program takes 1 second to compile and 2 seconds to connect to a
database, you'll still have significant savings over forking Perl and
recompiling the program with each request. cgi-fcgi is a tiny program
when compared to Perl and many other programs.

Building the FastCGI Developer's Kit

To build the developer's kit, you'll need to configure it. The folks
 at Open Market have provided a nice script that automates the
configuration process to run it. Just type ./configure while focused
inside the fcgi-devel-kit directory. After a few mom ents you should
be able to type make and have the libraries built. You will need this
kit to build FastCGI-savvy interpreters or C programs.

After you build the kit, you may be interested in installing the
library libfcgi/libfcgi.a to some place useful such as /usr/local/lib.
Remember to do a ranlib on the library after you move it to refresh
it. While you're at it, you may want to copy the include directory to
/usr/local/include/fcgi. That way it will be easier for you to
reference it while building your own programs.

After the kit is built, you may want to try your luck at building the
sample HelloWorld.c program listed earlier. Note that you may need to
change the location of the fcgi_stdio.h header file to reflect its new
location.

To build the FastCGI program, issue the following commands:

cc -o Hello.fcgi -lfcgi HelloWorld.c

Put the resulting Hello.fcgi on your fcgi-bin directory. Before you

can access it, you'll need to add an AppClass entry into your
srm.conf:

AppClass /usr/local/etc/httpd/fcgi-bin/Hello.fcgi

and restart the server with

% kill -HUP `cat /usr/local/etc/httpd/logs/httpd.pid`

The AppClass directive takes care of starting and maintaining the

FastCGI application. At this point you should be able to access it by
pointing your browser to http://localhost/fcgi-bin/Hello.fcgi.

You should get a similar result to those displayed in Figure C.2.

Figure C.2. The FastCGI version of Hello World!. Notice that it keeps
state. My version is fancier than the HelloWorld listing.

Making Perl Fly

You will notice an even bigger improvement on Perl CGIs. This is

because FastCGI will keep the Perl program running; the interpreter
won't have to fork, exec, compile, and execute for each request. A
good thing.

Before you can incorporate FastCGI into your Perl programs, you have
to build a special version of Perl. The FastCGI Developer's Kit
contains the patches you'll need to build a version of Perl that
supports FastCGI. After you build this version, there' s no need to
keep your old Perl around. A FastCGI-savvy Perl binary will work just
fine with regular Perl scripts.

Future versions of Perl may have support for FastCGI right out of the
box. Currently there's an active discussion on the perl5-porters
mailing list regarding the issues that need to change in Perl's
implementation to support FastCGI as a true Perl modu le-that is,
 requiring no recompiling. The Tcl7.5 FastCGI module, when it makes its
debut, won't require a rebuilt of Tcl. The new Python module also
doesn't need a rebuild.

At the time of this writing, the patches available for FastCGI were
for version 5.002 of Perl. By the time you read this, they will be
updated to the current Perl version, 5.003.

The patch process is simple; you just replace a few files in the
standard Perl distribution with files provided in the kit. Here's the
process:
1. 1. Put the unarchived Perl and fcgi-devel-kit on a directory side
by side and issue the following commands:
% cd perl5.002
% mv perl.c perl.c.dist
% mv proto.h proto.h.dist
% mv Configure Configure.dist
% cp -r ../fcgi-devel-kit/perl-5/perl5.002/*
% cp -r ../fcgi-devel-kit/perl-5/common/*
2. 2. Set the environment variable FCGIDIR to the absolute path of
the fcgi-devel-kit. In my case, the distribution was in the
/tmp/fcgiPerl directory. This variable will tell the configuration
program where to find things:
setenv FCGIDIR /tmp/fcgiPerl/fcgi-devel-kit
3. 3. If you don't use gcc, set the environment variable CC to the
name of your compiler:
setenv CC cc
4. 4. If you want to install the Perl distribution somewhere other
than /usr/local/bin, define the environment variable PERL_PREFIX.
I kept the default setting.
5. 5. Execute the fcgi-configure script:
% ./fcgi-configure
The fcgi-configure script is a wrapper that automatically sets
some of the configure variables without requiring user input. If
this fails, you'll have to run the Configure command in the Perl
directory. You may want to take a look at the documentatio n that
came with the FastCGI Developer's Kit for any tips to solve the
problem.
6. 6. Do a make to build the software:
% make

If it all goes smoothly, you can finish the installation with a make
install, which will install Perl to the location specified. That's it
for the install! Make sure your scripts reference the correct version
of Perl.

Perl FastCGI Programs

The modified version of my HelloWorld.c looks like this:

#!/usr/local/bin/perl

use strict;

use FCGI;

my($timesVisited) = 0;

while(FCGI::accept() >=0){
 print "Content-type: text/plain\n\n";

print <<STOP;

<HTML>

<HEAD>

<TITLE>Hello World!</TITLE>

</HEAD>

<BODY>

<H1>Hello, this is a FastCGI program!</H1>

<P>I can tell that you are visiting from $ENV{REMOTE_HOST}</P>

<P>This page has been accessed: ++$timesVisited</P>

</BODY>

</HTML>

STOP

As you can see, this is pretty much the same organization as the C
program. The one gotcha with Perl is that if the initial environment
to a FastCGI Perl application is empty when the first call to
FCGI::accept returns, the environment will still be em pty. The
easiest workaround is to add an environment with the AppClass
-initial-env directive. See the section entitled, "The AppClass
Directive," for more detailed information.

The mod_fastcgi Module

The FastCGI module provides Apache compatibility to FastCGI

applications. This module is not part of the standard Apache release,
so you'll have obtain a copy from http://www.fastcgi.com. A copy of
the latest version at the time this was written, Augus t 1996, is
included on the CD-ROM.

This module processes any file with a MIME-type

application/x-httpd-fcgi. Because the ScriptAlias directive may have
higher priority over AddType, FastCGI applications should not reside
on the cgi-bin directory; if they do, they may be processed by the
mod_cgi module regardless of the extension given. This means that the
application/x-httpd-fcgi MIME type is given to files that do not
reside in the ScriptAlias directory and that have a name using the
extension defined by the AddType application/ x-httpd-cfgi directive.
Typically this will be .fcgi. The reason for this is that Apache
assigns priority to the directives based on the order of compilation
in the modules.

The AppClass Directive

 Syntax: AppClass executablePath [-processes p] [-listen-queue-Depth q]
[-restart-delay secs] [-priority N] [-initial-env key=value]
Default: AppClass executablePath [-processes 1] [-listen-queue-Depth
5] [-restart-delay 5] [-priority sameAsHTTP]
Context: srm.conf
Module: mod_fastcgi

The AppClass directive, provided by mod_fastcgi, is responsible for

starting up one or more FastCGI application processes using the
executable specified by executablePath.

When a request for the file specified by executablePath is received,

the request is handled by the mod_fastcgi module, which connects the
request to the appropriate process belonging to the proper AppClass.

In addition to starting the process, the server will ensure that a

process for handling a particular AppClass will be available. Should a
process exit because of an error or some other condition, the server
will launch another process capable of handli ng the requests.

AppClass has several other options:

processes: Specifies the number of FastCGI processes that the server

will spawn. Default value for this setting is 1.
listen-queue-depth: Sets the depth of the listen queue that is shared
by the processes. The listen queue stores additional requests that may
be received while the FastCGI application is processing another.
Requests will queue until they reach the limit imposed by list
en-queue-depth. Additional requests beyond the size of the queue are
responded with an error to the client. Default value is 5.
restart-delay: Specifies the number of seconds the server will wait
before restarting a dead FastCGI process. The server won't restart a
process more often than the time specified by this flag. The default
value is 5 seconds.
priority: This flag specifies the execution priority of the FastCGI
process. The default priority is inherited from the parent httpd
server process.
initial-env: This flag allows you to specify the initial environment
sent to a FastCGI program when the program initializes. You can
specify multiple initial-env flags, one per key=value pair. If not
specified, the initial environment is empty. It would be very useful
to provide the FastCGI application with information during its
initialization phase.

Example

If you wanted to start the HelloWorld.fcgi program, you would need to

type this:

AppClass /usr/local/etc/httpd/fcgi-bin/HelloWorld.fcgi -processes 2

For a Perl program, to circumvent the environment problem, you would

have to do this:

AppClass /usr/local/etc/httpd/fcgi-bin/HelloWorld.fcgi -processes 2 -initial- e

nv: DB_PATH_NAME=/proj/accts/db2

Summary
Although FastCGI is not the sole alternative for high performance CGI
alternatives, the features and price cannot be beat. It's especially
interesting that existing code can be ported easily without a real
learning curve. This alone makes it very attra ctive for programmers
who have a backlog and don't have much time to spend experimenting
with new tools, yet need to implement a high-performance CGI solution.
FastCGI is a great choice-the learning-and-setup curve is hours, not
days like other environments.

Previous Page Page Top TOC Next Page