doc/fastcgi-whitepaper/fastcgi.htm

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