fix validation, organization, and links
[catagits/fcgi2.git] / doc / fastcgi-whitepaper / fastcgi.htm
CommitLineData
6791223e 1<HTML>
2
3
4
5<HEAD>
6
7
8
9<TITLE>FastCGI</TITLE>
10
11
12
13<META NAME="GENERATOR" CONTENT="Internet Assistant for Microsoft Word 2.0z">
14
0198fd3c 15</HEAD>
16
17<!--Copyright (c) 1996 Open Market, Inc. -->
18<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
19<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
6791223e 20<!-- $Id: fastcgi.htm,v 1.2 2001/05/14 13:00:32 robs Exp $ -->
21
22<BODY>
23
24
25
26<P>
27
28Open Market, Inc.
29
30<P>
31
32<CENTER><FONT SIZE=4 COLOR=#FFFFFF FACE="Impact">Technical White
33
34Paper<BR>
35
36</FONT></CENTER>
37
38<H1>FastCGI:<BR>
39
40A High-Performance Web Server Interface</H1>
41
42
43
44<P>
45
46April 1996<!--Please send comments to:-->
47
48<HR>
49
50<!-- payne@openmarket.com-->
51
52<H2>1. Introduction</H2>
53
54
55
56<P>
57
58The surge in the use of the Web by business has created
59
60a tremendous need for server extension applications that create
61
62dynamic content. These are the applications that will allow businesses
63
64to deliver products, services, and messages whose shape and content
65
66are in part determined by the interaction with, and knowledge
67
68of, the customers to which they are delivered.
69
70<P>
71
72This important movement away from static Web content
73
74is pushing the limits and exposing the weaknesses of the environment
75
76in which these applications are currently bound: CGI (Common Gateway
77
78Interface). Most importantly it does not offer the performance
79
80these applications require. A new communication infrastructure
81
82is needed to connect Web servers with these new applications.
83
84This is what led Open Market to develop FastCGI.
85
86<P>
87
88FastCGI is a fast, open, and secure Web server interface
89
90that solves the performance problems inherent in CGI, without
91
92introducing the overhead and complexity of proprietary APIs (Application
93
94Programming Interfaces).
95
96<P>
97
98This paper assumes that the reader has basic familiarity
99
100with Web technology and developing Web applications.
101
102<H3>Common Gateway Interface</H3>
103
104
105
106<P>
107
108The de facto standard interface for Web server applications
109
110is CGI, which was first implemented in the NCSA server. CGI has
111
112many benefits:
113
114<UL>
115
116<LI><B>Simplicity. </B><FONT>It is
117
118easy to understand.</FONT>
119
120<LI><B>Language independence.</B>
121
122CGI applications can be written in nearly any language.
123
124<LI><B>Process isolation.</B>
125
126Since applications run in separate processes, buggy applications
127
128cannot crash the Web server or access the server's private internal
129
130state.
131
132<LI><B>Open standard.</B> Some
133
134form of CGI has been implemented on every Web server.
135
136<LI><B>Architecture independence.</B>
137
138CGI is not tied to any particular server architecture (single
139
140threaded, multi-threaded, etc.).
141
142</UL>
143
144
145
146<P>
147
148CGI also has some significant drawbacks. The leading
149
150problem is performance: Since a new process is created for each
151
152request and thrown away when the request is done, efficiency is
153
154poor.
155
156<P>
157
158CGI also has limited functionality: It only supports
159
160a simple &quot;responder&quot; role, where the application generates
161
162the response that is returned to the client. CGI programs can't
163
164link into other stages of Web server request processing, such
165
166as authorization and logging.
167
168<H3>Server APIs</H3>
169
170
171
172<P>
173
174In response to the performance problems for CGI,
175
176several vendors have developed APIs for their servers. The two
177
178most notable are NSAPI from Netscape and ISAPI from Microsoft.
179
180 The freely available Apache server also has an API.
181
182<P>
183
184Applications linked into the server API may be significantly
185
186faster than CGI programs. The CGI startup/initialization problem
187
188is improved, because the application runs in the server process
189
190and is persistent across requests. Web server APIs also offer
191
192more functionality than CGI: you can write extensions that perform
193
194access control, get access to the server's log file, and link
195
196in to other stages in the server's request processing.
197
198<P>
199
200However, APIs sacrifice all of CGI's benefits. Vendor
201
202APIs have the following problems:
203
204<UL>
205
206<LI><B>Complexity.</B> Vendor
207
208APIs introduce a steep learning curve, with increased implementation
209
210and maintenance costs.
211
212<LI><B>Language dependence.</B>
213
214 Applications have to be written in a language supported by the
215
216vendor API (usually C/C++). Perl, the most popular language for
217
218CGI programs, can't be used with any existing vendor API.
219
220<LI><B>No process isolation. </B><FONT>Since
221
222the applications run in the server's address space, buggy applications
223
224can corrupt the core server (or each other). A malicious or buggy
225
226application can compromise server security, and bugs in the core
227
228server can corrupt applications.</FONT>
229
230<LI><B>Proprietary.</B> Coding
231
232your application to a particular API locks you into a particular
233
234vendor's server.
235
236<LI><B>Tie-in to server architecture.</B>
237
238 API applications have to share the same architecture as the server:
239
240 If the Web server is multi-threaded, the application has to be
241
242thread-safe. If the Web server has single-threaded processes,
243
244multi-threaded applications don't gain any performance advantage.
245
246 Also, when the vendor changes the server's architecture, the
247
248API will usually have to change, and applications will have to
249
250be adapted or rewritten.
251
252</UL>
253
254
255
256<H3>FastCGI</H3>
257
258
259
260<P>
261
262The FastCGI interface combines the best aspects of
263
264CGI and vendor APIs. Like CGI, FastCGI applications run in separate,
265
266isolated processes. FastCGI's advantages include:
267
268<UL>
269
270<LI><B>Performance.</B> FastCGI
271
272processes are persistent-they are reused to handle multiple requests.
273
274 This solves the CGI performance problem of creating new processes
275
276for each request.
277
278<LI><B>Simplicity, with easy migration from CGI.</B>
279
280 The FastCGI application library (described on page 9) simplifies
281
282the migration of existing CGI applications. Applications built
283
284with the application library can also run as CGI programs, for
285
286backward compatibility with old Web servers.
287
288<LI><B>Language independence.</B>
289
290Like CGI, FastCGI applications can be written in any language,
291
292not just languages supported by the vendor API.
293
294<LI><B>Process isolation.</B>
295
296A buggy FastCGI application cannot crash or corrupt the core server
297
298or other applications. A malicious FastCGI application cannot
299
300steal any secrets (such as session keys for encryption) from the
301
302Web server.
303
304<LI><B>Non-proprietary.</B>
305
306FastCGI is supported in all of Open Market's server products,
307
308and support is under development for other Web servers, including
309
310the freely available Apache and NCSA servers, as well as commercial
311
312servers from Microsoft and Netscape.
313
314<LI><B>Architecture independence.</B>
315
316 The FastCGI interface is not tied to a particular server architecture.
317
318 Any Web server can implement the FastCGI interface. Also, FastCGI
319
320does not impose any architecture on the application: applications
321
322can be single or multi-threaded, regardless of the threading architecture
323
324of the Web server.
325
326<LI><B>Support for distributed computing.</B>
327
328 FastCGI provides the ability to run applications remotely, which
329
330is useful for distributing load and managing external Web sites.
331
332</UL>
333
334
335
336<P>
337
338The following sections describe the FastCGI interface,
339
340protocol, application library, and support in Open Market's WebServer
341
342products.
343
344<H2>2. FastCGI Interface</H2>
345
346
347
348<P>
349
350The functionality provided by the FastCGI interface
351
352is very similar to that provided by CGI. To best understand the
353
354FastCGI protocol, we review the CGI interface here. Basic CGI
355
356request processing proceeds as follows:
357
358<OL>
359
360<LI>For each request, the server creates a new process
361
362and the process initializes itself.
363
364<LI>The Web server passes the request information
365
366(such as remote host, username, HTTP headers, etc.) to the CGI
367
368program in environment variables.
369
370<LI>The Web server sends any client input (such as
371
372user-entered field values from an HTML form) to the CGI program's
373
374standard input.
375
376<LI>The CGI program writes any output to be returned
377
378to the client on standard output. Error information written to
379
380standard error is logged by the Web server.
381
382<LI>When the CGI process exits, the request is complete.
383
384</OL>
385
386
387
388<P>
389
390FastCGI is conceptually very similar to CGI, with
391
392two major differences:
393
394<UL>
395
396<LI>FastCGI processes are persistent: after finishing
397
398a request, they wait for a new request instead of exiting.
399
400<LI>Instead of using operating system environment
401
402variables and pipes, the FastCGI protocol multiplexes the environment
403
404information, standard input, output and error over a single full-duplex
405
406connection. This allows FastCGI programs to run on remote machines,
407
408using TCP connections between the Web server and the FastCGI application.
409
410</UL>
411
412
413
414<P>
415
416Request processing in a single-threaded FastCGI application
417
418proceeds as follows:
419
420<OL>
421
422<LI>The Web server creates FastCGI application processes
423
424to handle requests. The processes may be created at startup,
425
426or created on demand.
427
428<LI>The FastCGI program initializes itself, and waits
429
430for a new connection from the Web server.
431
432<LI>When a client request comes in, the Web server
433
434opens a connection to the FastCGI process. The server sends the
435
436CGI environment variable information and standard input over the
437
438connection.
439
440<LI>The FastCGI process sends the standard output
441
442and error information back to the server over the same connection.
443
444<LI>When the FastCGI process closes the connection,
445
446the request is complete. The FastCGI process then waits for another
447
448connection from the Web server.
449
450</OL>
451
452
453
454<P>
455
456FastCGI applications can run locally (on the same
457
458machine as the Web server) or remotely. For local applications,
459
460the server uses a full-duplex pipe to connect to the FastCGI application
461
462process. For remote applications, the server uses a TCP connection.
463
464<P>
465
466FastCGI applications can be single-threaded or multi-threaded.
467
468 For single threaded applications, the Web server maintains a
469
470pool of processes (if the application is running locally) to
471
472handle client requests. The size of the pool is user configurable.
473
474 Multi-threaded FastCGI applications may accept multiple connections
475
476from the Web server and handle them simultaneously in a single
477
478process. (For example, Java's built-in multi-threading, garbage
479
480collection, synchronization primitives, and platform independence
481
482make it a natural implementation language for multi-threaded FastCGI
483
484applications.)
485
486<H3>Remote FastCGI</H3>
487
488
489
490<P>
491
492FastCGI's ability to run applications remotely (over
493
494a TCP connection) provides some major benefits. These benefits
495
496are described in this section, along with some of the security
497
498issues that affect remote FastCGI applications.
499
500<H4>FastCGI with Firewalls</H4>
501
502
503
504<P>
505
506Applications that run on organizational (external) Web servers
507
508and depend on internal databases can be a challenge to administer.
509
510Figure 1 shows a typical organization, with an external Web server,
511
512a firewall restricting access to the internal network, and internal
513
514databases and applications.
515
516<P>
517
518<CENTER><IMG SRC="img00001.gif"><A NAME="_Ref352505891">Figure
519
5201</A></CENTER>
521
522<P>
523
524With CGI and vendor APIs, the application has to run on the Web
525
526server machine. This means the server administrator has to replicate
527
528the necessary database information onto the system hosting the
529
530Web server (which may be difficult to do in an automated way without
531
532compromising firewall security). Or, the administrator may build
533
534a &quot;bridge&quot; that allows access through the Web server
535
536to internal databases and applications (which is effectively re-inventing
537
538remote FastCGI).
539
540<P>
541
542With remote FastCGI, the applications can run on the internal
543
544network, simplifying the administrator's job. When used with
545
546appropriate firewall configuration and auditing, this approach
547
548provides a secure, high-performance, scalable way to bring internal
549
550applications and data to the external network.
551
552<H4>Load Distribution</H4>
553
554
555
556<P>
557
558For resource-intensive CGI and API applications, the Web server
559
560machine quickly becomes the bottleneck for overall throughput.
561
562The usual way to solve this performance problem is to buy a bigger,
563
564faster Web server machine, or to partition the Web site across
565
566several Web servers.
567
568<P>
569
570With remote FastCGI, the resource-intensive applications can be
571
572moved off the Web server machine, giving the server administrator
573
574additional flexibility in configuring the Web server. The administrator
575
576can configure FastCGI applications &quot;behind the scenes&quot;
577
578without having to change any content links or the external view
579
580of the Web site. The administrator can use several smaller, inexpensive
581
582server machines for applications, and can tailor each machine
583
584to the application it is hosting.
585
586<H4>Security Issues with Remote FastCGI</H4>
587
588
589
590<P>
591
592The two security issues with remote FastCGI connections are authentication
593
594and privacy. FastCGI applications should only accept connections
595
596from Web servers that they trust (the application library includes
597
598support for IP address validation). Future versions of the protocol
599
600will include support for applications authenticating Web servers,
601
602as well as support for running remote connections over secure
603
604transport protocols such as SSL or PCT.<!--This pargraph needs to be made stronger, going into the issues in a little more detail.-->
605
606
607
608<H3>The FastCGI Protocol</H3>
609
610
611
612<P>
613
614This section offers a brief introduction to the protocol
615
616used on the connection between the Web server and FastCGI application.
617
618 Most application developers will use the FastCGI application
619
620library and won't have to worry about the protocol details. However,
621
622specialized applications are free to implement the FastCGI protocol
623
624directly.
625
626<P>
627
628FastCGI uses a simple packet record format on the
629
630connection between the application and the Web server. The same
631
632record format is used in both directions and is outlined in Figure 2.
633
634<P>
635
636<CENTER><IMG SRC="img00002.gif"><A NAME="_Ref352404075">Figure
637
6382</A></CENTER>
639
640<P>
641
642The protocol version field specifies the version
643
644of the FastCGI protocol that is in use. The type field specifies
645
646the type of the record (described in the following section).
647
648The request ID identifies this record to a particular request,
649
650allowing multiple requests to be multiplexed over a single connection.
651
652 The data length field specifies the number of data bytes that
653
654follow.
655
656<P>
657
658The different FastCGI packet types are:
659
660<TABLE>
661
662
663
664<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_PARAMS</FONT></TT>
665
666</TD><TD WIDTH=228>Used for sending name/value pairs (CGI environment variables) from the Web server to the application.
667
668</TD></TR>
669
670
671
672<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_STDIN</FONT></TT>
673
674</TD><TD WIDTH=228>Used for sending the standard input from the Web server to the application.
675
676</TD></TR>
677
678
679
680<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_DATA</FONT></TT>
681
682</TD><TD WIDTH=228>Used for sending filter data to the application (for more information, see the filter role described on page 7.)
683
684</TD></TR>
685
686
687
688<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_STDOUT</FONT></TT>
689
690</TD><TD WIDTH=228>Used to send standard output from the application to the Web server.
691
692</TD></TR>
693
694
695
696<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_STDERR</FONT></TT>
697
698</TD><TD WIDTH=228>Used to send standard error information from the application to the Web server.
699
700</TD></TR>
701
702
703
704<TR><TD WIDTH=186><TT><FONT FACE="Courier">FCGI_END_REQUEST</FONT></TT>
705
706</TD><TD WIDTH=228>Ends the request (can be sent by either the server or the application).
707
708</TD></TR>
709
710
711
712</TABLE>
713
714
715
716<P>
717
718
719
720<P>
721
722For complete protocol details, see the <I>FastCGI Protocol Specification</I>,
723
724available from the Web site listed at the end of this paper.
725
726<H2>3. Application Roles</H2>
727
728
729
730<P>
731
732A major problem with CGI is its limited functionality:
733
734 CGI programs can only provide simple responses to requests.
735
736FastCGI provides expanded functionality with support for three
737
738different application &quot;roles&quot;:
739
740<UL>
741
742<LI><B>Responder.</B> This is
743
744the basic FastCGI role, and corresponds to the simple functionality
745
746offered by CGI today.
747
748<LI><B>Filter.</B> The FastCGI
749
750application filters the requested Web server file before sending
751
752it to the client.
753
754<LI><B>Authorizer.</B> The FastCGI
755
756program performs an access control decision for the request (such
757
758as performing a username/password database lookup).
759
760</UL>
761
762
763
764<P>
765
766Other roles will be defined in the future. For instance,
767
768a &quot;logger&quot; role would be useful, where the FastCGI program
769
770would receive the server's log entries for real-time processing
771
772and analysis.
773
774<P>
775
776The roles are described in more detail in the following
777
778sections.
779
780<H3>Responder Role</H3>
781
782
783
784<P>
785
786FastCGI's Responder role is identical to the functionality
787
788provided by CGI today. When a request comes into the server,
789
790the FastCGI program generates the response that's returned to
791
792the client (typically an HTML page).
793
794<H3><A NAME="_Ref352404524">Filter Role</A></H3>
795
796
797
798<P>
799
800The Filter role allows a FastCGI application to process
801
802a requested file before it is returned to the client.
803
804<P>
805
806Let's assume that the Web server is configured so
807
808that all files with the .<TT><FONT FACE="Courier">sgml
809
810</FONT></TT>extension are processed by a SGML-to-HTML
811
812FastCGI filter application, and the user accesses the following
813
814URL:
815
816<P>
817
818 <TT><FONT FACE="Courier">/document.sgml</FONT></TT>
819
820<P>
821
822After the Web server makes an access control decision
823
824and maps this URL to a content file, it invokes the FastCGI filter
825
826application with this file available as input. The FastCGI program's
827
828HTML output is sent back to the client, just as in the responder
829
830role. The process is outlined in Figure 3.
831
832<P>
833
834<CENTER><IMG SRC="img00003.gif"><A NAME="_Ref352560526">Figure
835
8363</A></CENTER>
837
838<P>
839
840Filter applications can significantly improve performance
841
842by caching filter results (the server provides the modification
843
844time in the request information so that applications can flush
845
846the cache when the server file has been modified).
847
848<P>
849
850The Filter role is useful for:
851
852<UL>
853
854<LI>On-the-fly format conversions
855
856<LI>Dynamic documents (such as documents with embedded
857
858SQL queries, or dynamic advertisement insertion)
859
860<LI>Applying a standard template: headers, footers,
861
862and backgrounds
863
864</UL>
865
866
867
868<H3>Authorizer Role</H3>
869
870
871
872<P>
873
874The Authorizer role allows a FastCGI application
875
876to make an access control decision for a request. The FastCGI
877
878application is invoked with all of the request information, just
879
880as in the Responder role. If the authorizer application generates
881
882a &quot;200 OK&quot; HTTP result, the Web server assumes that
883
884access is allowed and proceeds with the request. (The Web server
885
886may process other access checks, including other FastCGI authorizers,
887
888before access is ultimately allowed.) If the application generates
889
890any other response, that response is returned to the client and
891
892the request is ended. The response can be any valid HTTP response,
893
894including &quot;Access Denied&quot; or &quot;Redirect&quot;.
895
896<P>
897
898The Authorizer role is useful for:
899
900<UL>
901
902<LI>Access control based on username and password,
903
904where the user information is looked up in an external database.
905
906<LI>Complex access policies, such as time-of-day
907
908based access.
909
910<LI>Smart-card challenge/response authentication.
911
912<LI>Dynamic redirects, where the user is sent to
913
914different pages based on the request profile.
915
916</UL>
917
918
919
920<H2><A NAME="_Ref352251764">4. FastCGI Application Library</A></H2>
921
922
923
924<P>
925
926Open Market has developed a FastCGI application library
927
928that implements the FastCGI protocol (hiding the protocol details
929
930from the developer). This library makes implementing FastCGI programs
931
932as easy as writing CGI applications.
933
934<P>
935
936The application library provides a replacement for
937
938the C language standard I/O (stdio) routines, such as <TT><FONT FACE="Courier">printf()</FONT></TT>
939
940and <TT><FONT FACE="Courier">gets()</FONT></TT>.
941
942 The library converts references to standard input, standard output,
943
944and standard error to the FastCGI protocol. References to other
945
946files &quot;fall through&quot; to the underlying operating system
947
948standard I/O routines.
949
950<P>
951
952This approach has several benefits:
953
954<UL>
955
956<LI>Developers don't have to learn a new API to develop
957
958FastCGI applications.
959
960<LI>Existing CGI programs can be migrated with minimal
961
962source changes (CGI migration is described in more detail in the
963
964following section).
965
966<LI>FastCGI interpreters for Perl, Tcl, and other
967
968interpreted languages can be built without modifying the interpreter
969
970source code.
971
972</UL>
973
974
975
976<P>
977
978Here's a simple FastCGI application:<P>
979<PRE>
980 #include &lt;fcgi_stdio.h&gt;
981
982 void main(void)
983 {
984 int count = 0;
985 while(FCGI_Accept() &gt;= 0) {
986 printf("Content-type: text/html\r\n");
987 printf("\r\n");
988 printf("Hello world!&lt;br&gt;\r\n");
989 printf("Request number %d.", count++);
990 }
991 exit(0);
992 }
993</PRE>
994This application returns a &quot;Hello world&quot;
995
996HTML response to the client. It also keeps a counter of the number
997
998of times it has been accessed, displaying the value of the counter
999
1000at each request.
1001
1002<P>
1003
1004The <TT>fcgi_stdio.h</TT>
1005
1006header file provides the FastCGI replacement routines for the
1007
1008C standard I/O library. The <TT>FCGI_Accept()</TT>
1009
1010routine accepts a new request from the Web server.
1011
1012<H3>Migrating Existing CGI Programs</H3>
1013
1014
1015
1016<P>
1017
1018The application library was designed to make migration
1019
1020of existing CGI programs as simple as possible. Many applications
1021
1022can be converted by adding a loop around the main request processing
1023
1024code and recompiling with the FastCGI application library. FastCGI
1025
1026applications have the following structure, with an initialization
1027
1028section and a request processing loop:<p>
1029
1030
1031<I>Initialize application;<BR>
1032
1033</I><TT>while(FCGI_Accept() &gt;= 0) {</TT><BR>
1034
1035 <I>Process request</I>;<BR>
1036
1037<TT>}</TT>
1038
1039<P>
1040
1041To ease migration to FastCGI, executables built with
1042
1043the application library can run as either CGI or FastCGI programs,
1044
1045depending on how they are invoked. The library detects the execution
1046
1047environment and automatically selects FastCGI or regular I/O routines,
1048
1049as appropriate.
1050
1051<P>
1052
1053After migration, developers can clean up their FastCGI
1054
1055applications for best performance:
1056
1057<UL>
1058
1059<LI>Fix any resource leaks. Many CGI programs do
1060
1061not attempt to manage memory or close files, because they assume
1062
1063the world is going to be cleaned up when they exit. (If you don't
1064
1065want to clean up your program, you can just have your process
1066
1067assume that it is leaking memory and exit after processing some
1068
1069fixed number of requests.) Purify from Pure Software is one of
1070
1071a number of excellent tools for finding leaks and other memory
1072
1073use problems.
1074
1075<LI>Fix any problems with retained application state.
1076
1077 The application must ensure that any state that it creates in
1078
1079processing one request has no unintended effects on later requests.
1080
1081
1082
1083<LI>Collapse functionality. A common practice with
1084
1085CGI applications is to implement many small programs, with one
1086
1087function per program. CGI encourages this, because smaller programs
1088
1089load faster. With FastCGI, it's better to have related functionality
1090
1091in a single executable, so there are fewer processes to manage
1092
1093and applications can take advantage of sharing cached information
1094
1095across functions.
1096
1097</UL>
1098
1099
1100
1101<P>
1102
1103Applications written in Perl, Tcl, and other scripting
1104
1105languages can be migrated by using a language interpreter built
1106
1107with the application library. FastCGI-integrated Tcl and Perl
1108
1109interpreters for popular Unix platforms are available from Open
1110
1111Market. The interpreters are backward-compatible: They can run
1112
1113standard Tcl and Perl applications.
1114
1115<H2>5. FastCGI in the Open Market WebServer</H2>
1116
1117
1118
1119<P>
1120
1121This section describes the FastCGI support in the
1122
1123following Open Market server products:
1124
1125<UL>
1126
1127<LI>Open Market WebServer V2.0
1128
1129<LI>Open Market Secure WebServer V2.0
1130
1131<LI>Open Market Secure WebServer (Global) V2.0
1132
1133</UL>
1134
1135
1136
1137<P>
1138
1139For more information about FastCGI support, see
1140
1141the <I>Open Market WebServer Installation and Configuration Guide</I>.
1142
1143<H3>Server Configuration</H3>
1144
1145
1146
1147<P>
1148
1149FastCGI applications are configured with the server's
1150
1151configuration file. Configuration has two parts.
1152
1153<P>
1154
1155First, the server administrator defines an <I>application
1156
1157class</I>. For local applications, the application class specifies
1158
1159the details of running the FastCGI application, such as:
1160
1161<UL>
1162
1163<LI>The pathname of the application executable.
1164
1165<LI>Any arguments and environment variables to pass
1166
1167to the process at startup.
1168
1169<LI>The number of processes to run.
1170
1171</UL>
1172
1173
1174
1175<P>
1176
1177For remote applications, the class configuration
1178
1179information includes the host and TCP port to connect to. The
1180
1181Web server assumes that the FastCGI application has been started
1182
1183on the remote host. If a request comes in and the server can't
1184
1185connect to the FastCGI TCP port, the server logs an error and
1186
1187returns an error page to the client.
1188
1189<P>
1190
1191The second configuration step is mapping the application
1192
1193class to a role:
1194
1195<UL>
1196
1197<LI>For responder roles, the administrator configures
1198
1199some part of the URL space to be handled by the FastCGI application.
1200
1201 For example, all URLs beginning with <FONT FACE="Courier">/rollcall/</FONT>
1202
1203might be handled by the employee database application.
1204
1205<LI>For filter roles, the administrator configures
1206
1207a file extension to be handled by a filter application. For example,
1208
1209all files with the <FONT FACE="Courier">.sql</FONT>
1210
1211extension could be handled by a SQL query lookup filter.
1212
1213<LI>For authorizer roles, the administrator configures
1214
1215an authorizer application in the same manner as other access methods
1216
1217(hostname, username/password, etc.) A request must pass <I>all
1218
1219</I>access control checks (possibly including multiple FastCGI
1220
1221authorizers) before access is allowed.
1222
1223</UL>
1224
1225
1226
1227<H3>Basic FastCGI</H3>
1228
1229
1230
1231<P>
1232
1233To simplify migration for existing CGI programs,
1234
1235the WebServer provides a simple way to install new FastCGI programs
1236
1237without having to reconfigure the server. However, this approach
1238
1239doesn't offer all of the performance benefits of FastCGI application
1240
1241classes.
1242
1243<P>
1244
1245The WebServer treats any file with the extension
1246
1247<FONT FACE="Courier">.fcg</FONT> as
1248
1249a FastCGI application. When a request corresponds to such a file,
1250
1251the WebServer creates a new FastCGI process to handle the request,
1252
1253and shuts down the process when the request is complete (just
1254
1255as in CGI). In this mode of operation performance is comparable
1256
1257to CGI. Future versions of the WebServer will improve performance
1258
1259by automatically caching processes and re-using them for subsequent
1260
1261requests.
1262
1263<H3>Session Affinity</H3>
1264
1265
1266
1267<P>
1268
1269FastCGI programs can improve performance by caching
1270
1271information in the application process. For applications that
1272
1273require frequent but expensive operations such as validating a
1274
1275username/password in an external database for each request, this
1276
1277technique can significantly improve performance.
1278
1279<P>
1280
1281To improve the effectiveness of this technique, the
1282
1283WebServer implements <I>session affinity</I>. When session affinity
1284
1285is enabled, the WebServer arranges for all requests in a user
1286
1287session to be handled by the same FastCGI application process.
1288
1289 What constitutes a &quot;session&quot; is configurable. The
1290
1291default configuration uses the WebServer's built-in session tracking
1292
1293facility to identify user sessions. However, the server administrator
1294
1295can use any part of the request information for the session affinity
1296
1297mapping: the URL path, the client's hostname, the username, etc.<!--Talk about applications that need to hold onto resources for the user (such as open connections to the database).-->
1298
1299
1300
1301<H2>6. FastCGI Performance Analysis</H2>
1302
1303
1304
1305<P>
1306
1307How fast is FastCGI? The answer depends on the application.
1308
1309 This section contains some real FastCGI performance measurements,
1310
1311as well as guidelines for estimating the FastCGI speedup.
1312
1313<H3>FastCGI vs CGI</H3>
1314
1315
1316
1317<P>
1318
1319We measured the relative performance of CGI, FastCGI,
1320
1321and static files on the Open Market WebServer, using a simple
1322
1323application that generates a fixed number of output bytes. The
1324
1325following table shows the measured request processing time for
1326
1327different request types on a typical platform. The times are
1328
1329measured from the client perspective and include client, server,
1330
1331and application processing time.
1332
1333<TABLE BORDERCOLOR=#000000 BORDER=2>
1334
1335
1336
1337<TR><TD WIDTH=72><CENTER><FONT SIZE=2 FACE="Arial Narrow">Static file</FONT></CENTER>
1338
1339</TD><TD WIDTH=180><CENTER><FONT SIZE=2 FACE="Arial Narrow">21ms + 0.19ms per Kbyte</FONT></CENTER>
1340
1341</TD></TR>
1342
1343
1344
1345<TR><TD WIDTH=72><CENTER><FONT SIZE=2 FACE="Arial Narrow">FastCGI</FONT></CENTER>
1346
1347</TD><TD WIDTH=180><CENTER><FONT SIZE=2 FACE="Arial Narrow">22ms + 0.28ms per Kbyte</FONT></CENTER>
1348
1349</TD></TR>
1350
1351
1352
1353<TR><TD WIDTH=72><CENTER><FONT SIZE=2 FACE="Arial Narrow">CGI</FONT></CENTER>
1354
1355</TD><TD WIDTH=180><CENTER><FONT SIZE=2 FACE="Arial Narrow">59ms + 0.37ms per Kbyte</FONT></CENTER>
1356
1357</TD></TR>
1358
1359
1360
1361</TABLE>
1362
1363
1364
1365<P>
1366
1367FastCGI performance is comparable to serving static files, and
1368
1369significantly better than CGI (clearly showing the high overhead
1370
1371for process creation). Real applications have an additional time
1372
1373component: process initialization, which should be added to overall
1374
1375request processing time.
1376
1377<P>
1378
1379Let's use this data to estimate the speedup from migrating a typical
1380
1381database CGI application to FastCGI. Assume the application takes
1382
138350ms to initialize the database connection and generates 5K of
1384
1385output data. Request performance can be computed as follows:
1386
1387<TABLE>
1388
1389
1390
1391<TR><TD WIDTH=108>CGI </TD><TD WIDTH=331>59ms + 50ms + (0.37ms)(5) = 111ms
1392
1393</TD></TR>
1394
1395
1396
1397<TR><TD WIDTH=108>FastCGI</TD><TD WIDTH=331>22ms + (0.28ms)(5) = 23ms
1398
1399</TD></TR>
1400
1401
1402
1403</TABLE>
1404
1405
1406
1407<P>
1408
1409In this example, FastCGI has a 5x performance advantage over CGI,
1410
1411mostly due to savings from not having to create and initialize
1412
1413new processes for each request.<!--Need to talk about FastCGI vs proprietary APIs.-->
1414
1415
1416
1417<H2>7. Conclusions</H2>
1418
1419
1420
1421<P>
1422
1423Today's Web business applications need a platform
1424
1425that's fast, open, maintainable, straightforward, stable, and
1426
1427secure. FastCGI's design meets these requirements, and provides
1428
1429for a logical extension from proven and widely deployed CGI technology.
1430
1431 This allows developers to take advantage of FastCGI's benefits
1432
1433without losing their existing investment in CGI applications.<!--Need to talk about NT.-->
1434
1435<!--Need to give &quot;more punch&quot; to this conclusion: include info about uses for FastCGI (accessing legacy data in databases, access control, distributed applications, apps that have to run in multiple OS environments. -->
1436
1437<H2>8. For More Information</H2>
1438
1439
1440
1441<P>
1442
1443For more information about Open Market and our products,
1444
1445visit our Web site at:<FONT FACE="Courier">http://www.openmarket.com/</FONT>
1446
1447<P>
1448
1449For more information about the FastCGI protocol and
1450
1451the developer's kit, and the latest information about FastCGI
1452
1453standardization and support in other Web servers, visit the FastCGI
1454
1455project page at:<FONT FACE="Courier">http://www.openmarket.com/fastcgi/</FONT>
1456
1457</BODY>
1458
1459
1460
1461</HTML>
0198fd3c 1462