2 <!--Copyright (c) 1996 Open Market, Inc. -->
3 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
4 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
6 <title>FastCGI Specification</title>
11 <h2>FastCGI Specification</h2>
19 Document Version: 1.0<br>
25 Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge,
27 Tel: 617-621-9500 Fax: 617-621-1703 URL:
28 <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
30 $Id: fcgi-spec.html,v 1.2 2001/05/14 13:00:30 robs Exp $
36 <li><a HREF = "#S1">1. Introduction</a>
37 <li><a HREF = "#S2">2. Initial Process State</a>
39 <li><a HREF = "#S2.1">2.1 Argument list</a>
40 <li><a HREF = "#S2.2">2.2 File descriptors</a>
41 <li><a HREF = "#S2.3">2.3 Environment variables</a>
42 <li><a HREF = "#S2.4">2.4 Other state</a>
44 <li><a HREF = "#S3">3. Protocol Basics</a>
46 <li><a HREF = "#S3.1">3.1 Notation</a>
47 <li><a HREF = "#S3.2">3.2 Accepting Transport Connections</a>
48 <li><a HREF = "#S3.3">3.3 Records</a>
49 <li><a HREF = "#S3.4">3.4 Name-Value Pairs</a>
50 <li><a HREF = "#S3.5">3.5 Closing Transport Connections</a>
52 <li><a HREF = "#S4">4. Management Record Types</a>
54 <li><a HREF = "#S4.1">4.1 <tt>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</tt></a>
55 <li><a HREF = "#S4.2">4.2 <tt>FCGI_UNKNOWN_TYPE</tt></a>
57 <li><a HREF = "#S5">5. Application Record Types</a>
59 <li><a HREF = "#S5.1">5.1 <tt>FCGI_BEGIN_REQUEST</tt></a>
60 <li><a HREF = "#S5.2">5.2 Name-Value Pair Streams: <tt>FCGI_PARAMS</tt>, <tt>FCGI_RESULTS</tt></a>
61 <li><a HREF = "#S5.3">5.3 Byte Streams: <tt>FCGI_STDIN</tt>, <tt>FCGI_DATA</tt>, <tt>FCGI_STDOUT</tt>, <tt>FCGI_STDERR</tt></a>
62 <li><a HREF = "#S5.4">5.4 <tt>FCGI_ABORT_REQUEST</tt></a>
63 <li><a HREF = "#S5.5">5.5 <tt>FCGI_END_REQUEST</tt></a>
65 <li><a HREF = "#S6">6. Roles</a>
67 <li><a HREF = "#S6.1">6.1 Role Protocols</a>
68 <li><a HREF = "#S6.2">6.2 Responder</a>
69 <li><a HREF = "#S6.3">6.3 Authorizer</a>
70 <li><a HREF = "#S6.4">6.4 Filter</a>
72 <li><a HREF = "#S7">7. Errors</a>
73 <li><a HREF = "#S8">8. Types and Constants</a>
74 <li><a HREF = "#S9">9. References</a>
75 <li><a HREF = "#SA">A. Table: Properties of the record types</a>
76 <li><a HREF = "#SB">B. Typical Protocol Message Flow</a>
83 <h3><a name = "S1">1. Introduction</a></h3>
85 FastCGI is an open extension to CGI that provides high performance
86 for all Internet applications without the penalties of Web server
89 This specification has narrow
90 goal: to specify, from an application perspective, the
91 interface between a FastCGI application and a Web server that supports
92 FastCGI. Many Web server features related to FastCGI,
93 e.g. application management facilities, have nothing to do with the
94 application to Web server interface, and are not described here.<p>
96 This specification is for Unix (more precisely, for POSIX systems that support
97 Berkeley Sockets). The bulk of the specification is a simple
98 communications protocol that is independent of byte ordering
99 and will extend to other systems.<p>
101 We'll introduce FastCGI by comparing it with conventional Unix
102 implementations of CGI/1.1.
104 FastCGI is designed to support long-lived application processes,
105 i.e. <i>application servers</i>. That's a major difference
106 compared with conventional Unix implementations of CGI/1.1,
107 which construct an application process, use
108 it respond to one request, and have it exit.<p>
110 The initial state of a FastCGI process is more spartan than the initial
111 state of a CGI/1.1 process, because the FastCGI process doesn't begin life
112 connected to anything. It doesn't have the conventional open files
113 <tt>stdin</tt>, <tt>stdout</tt>, and <tt>stderr</tt>, and it doesn't
114 receive much information through environment variables. The key
115 piece of initial state in a FastCGI process is a listening
116 socket, through which it accepts connections from a Web server.<p>
118 After a FastCGI process accepts a connection on its listening socket,
119 the process executes a simple protocol to receive and send data. The
120 protocol serves two purposes. First, the protocol
121 multiplexes a single transport connection between several independent
122 FastCGI requests. This supports applications that are able to process
123 concurrent requests using event-driven or multi-threaded programming
124 techniques. Second, within each request the protocol provides several
125 independent data streams in each direction. This way, for instance,
126 both <tt>stdout</tt> and <tt>stderr</tt> data pass over a single
127 transport connection from the application to the Web server, rather
128 than requiring separate pipes as with CGI/1.1.<p>
130 A FastCGI application plays one of several well-defined <i>roles</i>.
131 The most familiar is the <i>Responder</i> role, in which the
132 application receives all the information associated with an HTTP
133 request and generates an HTTP response; that's the role CGI/1.1
134 programs play. A second role is <i>Authorizer</i>, in which the
135 application receives all the information associated with an HTTP
136 request and generates an authorized/unauthorized decision.
137 A third role is <i>Filter</i>, in which the
138 application receives all the information associated with an HTTP
139 request, plus an extra stream of data from a file stored on the Web
140 server, and generates a "filtered" version of the data stream as
141 an HTTP response. The framework is extensible so that more FastCGI
142 can be defined later.<p>
144 In the remainder of this specification the terms "FastCGI
145 application," "application process," or "application server" are
146 abbreviated to "application" whenever that won't cause confusion.<p>
150 <h3><a name = "S2">2. Initial Process State</a></h3>
153 <h4><a name = "S2.1">2.1 Argument list</a></h4>
155 By default the Web server creates an argument list containing a single
156 element, the name of the application, taken to be the last component
157 of the executable's path name. The Web server may provide a way
158 to specify a different application name, or a more elaborate argument
161 Note that the file executed by the Web server might be an interpreter
162 file (a text file that starts with the characters <tt>#!</tt>), in
163 which case the application's argument list is constructed as described
164 in the <tt>execve</tt> manpage.<p>
167 <h4><a name = "S2.2">2.2 File descriptors</a></h4>
169 The Web server leaves a single file descriptor,
170 <tt>FCGI_LISTENSOCK_FILENO</tt>, open when the application begins
171 execution. This descriptor refers to a listening socket created by
174 <tt>FCGI_LISTENSOCK_FILENO</tt> equals <tt>STDIN_FILENO</tt>.
175 The standard descriptors
176 <tt>STDOUT_FILENO</tt> and <tt>STDERR_FILENO</tt> are closed when
177 the application begins execution. A reliable method for an application
178 to determine whether it was invoked using CGI or FastCGI is to call
179 <tt>getpeername(FCGI_LISTENSOCK_FILENO)</tt>, which returns
180 -1 with <tt>errno</tt> set to <tt>ENOTCONN</tt> for
181 a FastCGI application.<p>
183 The Web server's choice of reliable transport, Unix stream pipes
184 (<tt>AF_UNIX</tt>) or TCP/IP (<tt>AF_INET</tt>), is implicit in the
185 internal state of the <tt>FCGI_LISTENSOCK_FILENO</tt> socket.<p>
188 <h4><a name = "S2.3">2.3 Environment variables</a></h4>
190 The Web server may use environment variables to pass parameters
191 to the application. This specification defines one such
192 variable, <tt>FCGI_WEB_SERVER_ADDRS</tt>; we expect more to
193 be defined as the specification evolves.
195 The Web server may provide a way to bind other environment
196 variables, such as the <tt>PATH</tt> variable.<p>
199 <h4><a name = "S2.4">2.4 Other state</a></h4>
201 The Web server may provide a way to specify other components of an
202 application's initial process state, such as the priority,
203 user ID, group ID, root directory, and working directory of the
208 <h3><a name = "S3">3. Protocol Basics</a></h3>
211 <h4><a name = "S3.1">3.1 Notation</a></h4>
213 We use C language notation to define protocol message
214 formats. All structure elements are defined in terms
215 of the <tt>unsigned char</tt> type, and are arranged
216 so that an ISO C compiler lays them out in the obvious
217 manner, with no padding. The first byte defined in the
218 structure is transmitted first, the second byte second, etc.<p>
220 We use two conventions to abbreviate our definitions.<p>
222 First, when two adjacent structure components are named identically
223 except for the suffixes "<tt>B1</tt>" and "<tt>B0</tt>," it means that
224 the two components may be viewed as a single number, computed as
225 <tt>B1<<8 + B0</tt>. The name of this single number is the name of
226 the components, minus the suffixes. This convention generalizes in an
227 obvious way to handle numbers represented in more than two bytes.<p>
229 Second, we extend C <tt>struct</tt>s to allow the form
232 unsigned char mumbleLengthB1;
233 unsigned char mumbleLengthB0;
234 ... /* other stuff */
235 unsigned char mumbleData[mumbleLength];
238 meaning a structure of varying length, where the length of
239 a component is determined by the values of the indicated
240 earlier component or components.<p>
243 <h4><a name = "S3.2">3.2 Accepting Transport Connections</a></h4>
245 A FastCGI application calls <tt>accept()</tt> on the socket referred to
246 by file descriptor <tt>FCGI_LISTENSOCK_FILENO</tt> to accept a new
247 transport connection.
249 If the <tt>accept()</tt> succeeds, and the <tt>FCGI_WEB_SERVER_ADDRS</tt>
250 environment variable is bound, the application
251 application immediately performs the following
252 special processing:<p>
255 <li><tt>FCGI_WEB_SERVER_ADDRS</tt>:
257 The value is a list of valid IP addresses for the Web server.<p>
259 If <tt>FCGI_WEB_SERVER_ADDRS</tt>
260 was bound, the application checks the peer
261 IP address of the new connection for membership in the list.
262 If the check fails (including the possibility that the
263 connection didn't use TCP/IP transport), the application
264 responds by closing the connection.<p>
266 <tt>FCGI_WEB_SERVER_ADDRS</tt>
267 is expressed as a comma-separated list of IP
268 addresses. Each IP address is written as four decimal numbers
269 in the range [0..255] separated by decimal points. So one
270 legal binding for this variable is
271 <tt>FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71</tt>.<p>
274 An application may accept several concurrent transport
275 connections, but it need not do so.<p>
278 <h4><a name = "S3.3">3.3 Records</a></h4>
280 Applications execute requests from a Web server using a simple
281 protocol. Details of the protocol depend upon the application's role,
282 but roughly speaking the Web server first sends parameters and other
283 data to the application, then the application sends result data to the
284 Web server, and finally the application sends the Web server an
285 indication that the request is complete.<p>
287 All data that flows over the transport connection is carried in
288 <i>FastCGI records</i>. FastCGI records accomplish two
289 things. First, records multiplex the transport connection between
290 several independent FastCGI requests. This multiplexing supports
291 applications that are able to process concurrent requests using
292 event-driven or multi-threaded programming techniques. Second,
293 records provide several independent data streams in each direction
294 within a single request. This way, for instance, both <tt>stdout</tt>
295 and <tt>stderr</tt> data can pass over a single transport connection
296 from the application to the Web server, rather than requiring separate
301 unsigned char version;
303 unsigned char requestIdB1;
304 unsigned char requestIdB0;
305 unsigned char contentLengthB1;
306 unsigned char contentLengthB0;
307 unsigned char paddingLength;
308 unsigned char reserved;
309 unsigned char contentData[contentLength];
310 unsigned char paddingData[paddingLength];
314 A FastCGI record consists of a fixed-length prefix followed by a
315 variable number of content and padding bytes. A record contains seven
319 <li><tt>version</tt>:
321 Identifies the FastCGI protocol version. This specification
322 documents <tt>FCGI_VERSION_1</tt>.<p>
326 Identifies the FastCGI record type, i.e. the general function
327 that the record performs. Specific record types and their
328 functions are detailed in later sections.<p>
330 <li><tt>requestId</tt>:
332 Identifies the <i>FastCGI request</i> to which the record
335 <li><tt>contentLength</tt>:
337 The number of bytes in the <tt>contentData</tt> component of the
340 <li><tt>paddingLength</tt>:
342 The number of bytes in the <tt>paddingData</tt> component of the
345 <li><tt>contentData</tt>:
347 Between 0 and 65535 bytes of data, interpreted
348 according to the record type.<p>
350 <li><tt>paddingData</tt>:
352 Between 0 and 255 bytes of data, which are ignored.<p>
355 We use a relaxed C <tt>struct</tt> initializer syntax to specify
356 constant FastCGI records. We omit the <tt>version</tt> component,
357 ignore padding, and treat
358 <tt>requestId</tt> as a number. Thus <tt>{FCGI_END_REQUEST, 1,
359 {FCGI_REQUEST_COMPLETE,0}}</tt> is a record with <tt>type ==
360 FCGI_END_REQUEST</tt>, <tt>requestId == 1</tt>, and <tt>contentData ==
361 {FCGI_REQUEST_COMPLETE,0}</tt>.<p>
366 The protocol allows senders to pad the records they send, and requires
367 receivers to interpret the <tt>paddingLength</tt> and skip the
368 <tt>paddingData</tt>. Padding allows senders to keep data aligned
369 for more efficient processing. Experience with the X window
370 system protocols shows the performance benefit of such alignment.<p>
372 We recommend that records be placed on boundaries that are multiples
373 of eight bytes. The fixed-length portion of a <tt>FCGI_Record</tt>
377 <h5>Managing Request IDs</h5>
379 The Web server re-uses FastCGI request IDs; the application keeps
380 track of the current state of each request ID on a given transport
381 connection. A request ID <tt>R</tt> becomes active when the application
382 receives a record <tt>{FCGI_BEGIN_REQUEST, R, ...}</tt> and
383 becomes inactive when the application sends a record
384 <tt>{FCGI_END_REQUEST, R, ...}</tt> to the Web server.<p>
386 While a request ID <tt>R</tt> is inactive, the application ignores
387 records with <tt>requestId == R</tt>, except for <tt>FCGI_BEGIN_REQUEST</tt>
388 records as just described.<p>
390 The Web server attempts to keep FastCGI request IDs small. That way
391 the application can keep track of request ID states using a short
392 array rather than a long array or a hash table. An application
393 also has the option of accepting only one request at a time.
394 In this case the application simply checks incoming <tt>requestId</tt>
395 values against the current request ID.<p>
398 <h5>Types of Record Types</h5>
400 There are two useful ways of classifying FastCGI record types.<p>
402 The first distinction is between <i>management</i> records and
403 <i>application</i> records. A management record contains information
404 that is not specific to any Web server request, such as information
405 about the protocol capabilities of the application.
406 An application record contains information
407 about a particular request, identified by the <tt>requestId</tt>
410 Management records have a <tt>requestId</tt> value of zero,
411 also called the <i>null request ID</i>. Application
412 records have a nonzero <tt>requestId</tt>.<p>
414 The second distinction is between <i>discrete</i> and <i>stream</i>
415 records. A discrete record contains a meaningful unit of data all by
416 itself. A stream record is part of a <i>stream</i>, i.e. a series of
417 zero or more non-empty records (<tt>length != 0</tt>) of the stream
418 type, followed by an empty record (<tt>length == 0</tt>) of the stream
419 type. The <tt>contentData</tt> components of a stream's records, when
420 concatenated, form a byte sequence; this byte sequence is the value of
421 the stream. Therefore the value of a stream is independent of how
422 many records it contains or how its bytes are divided among the
423 non-empty records.<p>
425 These two classifications are independent. Among the
426 record types defined in this version of the FastCGI protocol,
427 all management record types are also discrete record types,
428 and nearly all application record types are stream record types.
429 But three application record types are discrete, and nothing
430 prevents defining a management record type that's a stream
431 in some later version of the protocol.<p>
434 <h4><a name = "S3.4">3.4 Name-Value Pairs</a></h4>
436 In many of their roles, FastCGI applications need to read and write
437 varying numbers of variable-length values. So it is useful to adopt a
438 standard format for encoding a name-value pair.<p>
440 FastCGI transmits a name-value pair as the length of the name,
441 followed by the length of the value, followed by the name,
442 followed by the value. Lengths of 127 bytes and less can be encoded
443 in one byte, while longer lengths are always encoded in four bytes:<p>
447 unsigned char nameLengthB0; /* nameLengthB0 >> 7 == 0 */
448 unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */
449 unsigned char nameData[nameLength];
450 unsigned char valueData[valueLength];
451 } FCGI_NameValuePair11;
454 unsigned char nameLengthB0; /* nameLengthB0 >> 7 == 0 */
455 unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */
456 unsigned char valueLengthB2;
457 unsigned char valueLengthB1;
458 unsigned char valueLengthB0;
459 unsigned char nameData[nameLength];
460 unsigned char valueData[valueLength
461 ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0];
462 } FCGI_NameValuePair14;
465 unsigned char nameLengthB3; /* nameLengthB3 >> 7 == 1 */
466 unsigned char nameLengthB2;
467 unsigned char nameLengthB1;
468 unsigned char nameLengthB0;
469 unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */
470 unsigned char nameData[nameLength
471 ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0];
472 unsigned char valueData[valueLength];
473 } FCGI_NameValuePair41;
476 unsigned char nameLengthB3; /* nameLengthB3 >> 7 == 1 */
477 unsigned char nameLengthB2;
478 unsigned char nameLengthB1;
479 unsigned char nameLengthB0;
480 unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */
481 unsigned char valueLengthB2;
482 unsigned char valueLengthB1;
483 unsigned char valueLengthB0;
484 unsigned char nameData[nameLength
485 ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0];
486 unsigned char valueData[valueLength
487 ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0];
488 } FCGI_NameValuePair44;
491 The high-order bit of the first byte of a length indicates the length's
492 encoding. A high-order zero implies a one-byte encoding, a one a four-byte
495 This name-value pair format allows the sender to transmit binary values
496 without additional encoding, and enables the receiver to allocate the correct
497 amount of storage immediately even for large values.<p>
500 <h4><a name = "S3.5">3.5 Closing Transport Connections</a></h4>
502 The Web server controls the lifetime of transport connections.
503 The Web server can close a connection when no requests are active.
504 Or the Web server can delegate close authority to the application
505 (see <tt>FCGI_BEGIN_REQUEST</tt>).
506 In this case the application closes the connection at the end of
507 a specified request.<p>
509 This flexibility accommodates a variety of application styles.
510 Simple applications will process one request at a time and
511 accept a new transport connection for each request. More
513 will process concurrent requests, over one or multiple transport
514 connections, and will keep transport connections open for long
517 A simple application gets a significant performance boost by
518 closing the transport connection when it has finished writing its
519 response. The Web server needs to control the connection lifetime
520 for long-lived connections.<p>
522 When an application closes a connection or finds that a connection
523 has closed, the application initiates a new connection.<p>
527 <h3><a name = "S4">4. Management Record Types</a></h3>
530 <h4><a name = "S4.1">4.1 <tt>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</tt></a></h4>
532 The Web server can query specific variables within the application.
533 The server will typically perform a query on application startup
534 in order to to automate certain aspects of system configuration.<p>
536 The application receives a query as a record <tt>{FCGI_GET_VALUES, 0,
537 ...}</tt>. The <tt>contentData</tt> portion of a <tt>FCGI_GET_VALUES</tt>
538 record contains a sequence of name-value pairs with empty values.<p>
540 The application responds by sending a record
541 <tt>{FCGI_GET_VALUES_RESULT, 0, ...}</tt> with the values supplied. If the
542 application doesn't understand a variable name that was
543 included in the query, it omits that name from the
546 <tt>FCGI_GET_VALUES</tt> is designed to allow an open-ended
547 set of variables. The initial set provides information to help
548 the server perform application and connection management:<p>
551 <li><tt>FCGI_MAX_CONNS</tt>:
552 The maximum number of concurrent transport connections this
553 application will accept, e.g.
554 <tt>"1"</tt> or <tt>"10"</tt>.<p>
556 <li><tt>FCGI_MAX_REQS</tt>:
557 The maximum number of concurrent requests this application
559 <tt>"1"</tt> or <tt>"50"</tt>.<p>
561 <li><tt>FCGI_MPXS_CONNS</tt>:
562 <tt>"0"</tt> if this application does not multiplex
563 connections (i.e. handle concurrent requests over each
564 connection), <tt>"1"</tt> otherwise.<p>
567 An application may receive a <tt>FCGI_GET_VALUES</tt> record at any
568 time. The application's response should not involve the application
569 proper but only the FastCGI library.<p>
572 <h4><a name = "S4.2">4.2 <tt>FCGI_UNKNOWN_TYPE</tt></a></h4>
574 The set of management record types is likely to grow in future versions
575 of this protocol. To provide for this evolution, the protocol
576 includes the <tt>FCGI_UNKNOWN_TYPE</tt> management record.
577 When an application receives a management record whose type <tt>T</tt>
578 it does not understand, the application responds with
579 <tt>{FCGI_UNKNOWN_TYPE, 0, {T}}</tt>.<p>
581 The <tt>contentData</tt> component of a <tt>FCGI_UNKNOWN_TYPE</tt> record
586 unsigned char reserved[7];
587 } FCGI_UnknownTypeBody;
591 The <tt>type</tt> component is the type of the unrecognized management
596 <h3><a name = "S5">5. Application Record Types</a></h3>
599 <h4><a name = "S5.1">5.1 <tt>FCGI_BEGIN_REQUEST</tt></a></h4>
601 The Web server sends a <tt>FCGI_BEGIN_REQUEST</tt> record
602 to start a request.<p>
604 The <tt>contentData</tt> component of a <tt>FCGI_BEGIN_REQUEST</tt> record
608 unsigned char roleB1;
609 unsigned char roleB0;
611 unsigned char reserved[5];
612 } FCGI_BeginRequestBody;
616 The <tt>role</tt> component sets the role the Web server expects
617 the application to play. The currently-defined roles are:<p>
620 <li><tt>FCGI_RESPONDER</tt>
621 <li><tt>FCGI_AUTHORIZER</tt>
622 <li><tt>FCGI_FILTER</tt>
625 Roles are described in more detail in
626 <a href = "#S6">Section 6</a> below.<p>
628 The <tt>flags</tt> component contains a bit that
629 controls connection shutdown:<p>
632 <li><tt>flags & FCGI_KEEP_CONN</tt>:
633 If zero, the application closes the connection after responding to
634 this request. If not zero, the application does not close
635 the connection after responding to this request; the Web server
636 retains responsibility for the connection.<p>
640 <h4><a name = "S5.2">5.2 Name-Value Pair Stream: <tt>FCGI_PARAMS</tt></a></h4>
642 <tt>FCGI_PARAMS</tt> is a stream record type used in sending
643 name-value pairs from the Web server to the application.
644 The name-value pairs are sent down the stream one after the other,
645 in no specified order.<p>
648 <h4><a name = "S5.3">5.3 Byte Streams: <tt>FCGI_STDIN</tt>, <tt>FCGI_DATA</tt>, <tt>FCGI_STDOUT</tt>, <tt>FCGI_STDERR</tt></a></h4>
650 <tt>FCGI_STDIN</tt> is a stream record type used in sending arbitrary
651 data from the Web server to the application. <tt>FCGI_DATA</tt>
652 is a second stream record type used to send additional
653 data to the application.<p>
655 <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt> are stream record types
656 for sending arbitrary data and error data respectively from the
657 application to the Web server.<p>
660 <h4><a name = "S5.4">5.4 <tt>FCGI_ABORT_REQUEST</tt></a></h4>
662 The Web server sends a <tt>FCGI_ABORT_REQUEST</tt> record to
663 abort a request. After receiving <tt>{FCGI_ABORT_REQUEST, R}</tt>,
664 the application responds as soon as possible with
665 <tt>{FCGI_END_REQUEST, R, {FCGI_REQUEST_COMPLETE, appStatus}}</tt>.
666 This is truly a response from the application, not a low-level
667 acknowledgement from the FastCGI library.<p>
669 A Web server aborts a FastCGI request when an HTTP client closes its
670 transport connection while the FastCGI request is running on behalf of
671 that client. The situation may seem unlikely; most FastCGI
672 requests will have short response times, with the Web server providing
673 output buffering if the client is slow. But the FastCGI application
674 may be delayed communicating with another system, or performing a
677 When a Web server is not multiplexing requests over a transport
678 connection, the Web server can abort a request by closing the request's
679 transport connection. But with multiplexed requests, closing the
680 transport connection has the unfortunate effect of aborting <i>all</i>
681 the requests on the connection.<p>
684 <h4><a name = "S5.5">5.5 <tt>FCGI_END_REQUEST</tt></a></h4>
686 The application sends a <tt>FCGI_END_REQUEST</tt> record
687 to terminate a request, either because the application
688 has processed the request or because the application has rejected
691 The <tt>contentData</tt> component of a <tt>FCGI_END_REQUEST</tt> record
695 unsigned char appStatusB3;
696 unsigned char appStatusB2;
697 unsigned char appStatusB1;
698 unsigned char appStatusB0;
699 unsigned char protocolStatus;
700 unsigned char reserved[3];
701 } FCGI_EndRequestBody;
705 The <tt>appStatus</tt> component is an application-level status code.
706 Each role documents its usage of <tt>appStatus</tt>.<p>
708 The <tt>protocolStatus</tt> component is a protocol-level status code;
709 the possible <tt>protocolStatus</tt> values are:<p>
712 <li><tt>FCGI_REQUEST_COMPLETE</tt>:
713 normal end of request.<p>
715 <li><tt>FCGI_CANT_MPX_CONN</tt>:
716 rejecting a new request. This happens when a Web server sends
717 concurrent requests over one connection to an application that
718 is designed to process one request at a time per
721 <li><tt>FCGI_OVERLOADED</tt>:
722 rejecting a new request. This happens when the application
723 runs out of some resource, e.g. database connections.<p>
725 <li><tt>FCGI_UNKNOWN_ROLE</tt>:
726 rejecting a new request. This happens when the Web server
727 has specified a role that is unknown to the application.<p>
732 <h3><a name = "S6">6. Roles</a></h3>
735 <h4><a name = "S6.1">6.1 Role Protocols</a></h4>
737 Role protocols only include records with application record
738 types. They transfer essentially all data using streams.<p>
740 To make the protocols reliable and to simplify application
741 programming, role protocols are designed to use <i>nearly sequential
742 marshalling</i>. In a protocol with strictly sequential marshalling,
743 the application receives its first input, then its second, etc. until
744 it has received them all. Similarly, the application sends its first
745 output, then its second, etc. until it has sent them all. Inputs are
746 not interleaved with each other, and outputs are not interleaved with
749 The sequential marshalling rule is too restrictive for some
750 FastCGI roles, because CGI programs can write to both <tt>stdout</tt>
751 and <tt>stderr</tt> without timing restrictions. So role
752 protocols that use both <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt>
753 allow these two streams to be interleaved.<p>
755 All role protocols use the <tt>FCGI_STDERR</tt> stream just the way
756 <tt>stderr</tt> is used in conventional applications programming: to
757 report application-level errors in an intelligible way. Use of the
758 <tt>FCGI_STDERR</tt> stream is always optional. If an application has
759 no errors to report, it sends either no <tt>FCGI_STDERR</tt> records or
760 one zero-length <tt>FCGI_STDERR</tt> record.<p>
762 When a role protocol calls for transmitting a stream other than
763 <tt>FCGI_STDERR</tt>, at least one record of the stream type is always
764 transmitted, even if the stream is empty.<p>
766 Again in the interests of reliable protocols and simplified application
767 programming, role protocols are designed to be <i>nearly
768 request-response</i>. In a truly request-response protocol, the
769 application receives all of its input records before sending its first
770 output record. Request-response protocols don't allow pipelining.<p>
772 The request-response rule is too restrictive for some FastCGI roles;
773 after all, CGI programs aren't restricted to read all of
774 <tt>stdin</tt> before starting to write <tt>stdout</tt>. So some role
775 protocols allow that specific possibility. First the application
776 receives all of its inputs except for a final stream input. As the
777 application begins to receive the final stream input, it can
778 begin writing its output.<p>
780 When a role protocol uses <tt>FCGI_PARAMS</tt> to transmit textual
781 values, such as the values that CGI programs obtain from environment
782 variables, the length of the value does not include the terminating
783 null byte, and the value itself does not include a null byte. An
784 application that needs to provide <tt>environ(7)</tt> format
785 name-value pairs must insert an equal sign between the name and value
786 and append a null byte after the value.<p>
788 Role protocols do not support the non-parsed header feature
789 of CGI. FastCGI applications set response status using
790 the <tt>Status</tt> and <tt>Location</tt> CGI headers.<p>
793 <h4><a name = "S6.2">6.2 Responder</a></h4>
795 A Responder FastCGI application has the same purpose as a CGI/1.1 program:
796 It receives all the information associated with an HTTP request and
797 generates an HTTP response.<p>
799 It suffices to explain how each element of CGI/1.1 is emulated by a
803 The Responder application receives CGI/1.1 environment variables from
804 the Web server over <tt>FCGI_PARAMS</tt>.<p>
806 Next the Responder application receives CGI/1.1
807 <tt>stdin</tt> data from
808 the Web server over <tt>FCGI_STDIN</tt>. The application receives
809 at most <tt>CONTENT_LENGTH</tt> bytes from this stream before
810 receiving the end-of-stream indication. (The application
811 receives less than <tt>CONTENT_LENGTH</tt> bytes only if the
812 HTTP client fails to provide them, e.g. because the client
815 The Responder application sends CGI/1.1
816 <tt>stdout</tt> data to the Web
817 server over <tt>FCGI_STDOUT</tt>, and CGI/1.1 <tt>stderr</tt> data
818 over <tt>FCGI_STDERR</tt>. The application sends these
819 concurrently, not one after the other. The application must
820 wait to finish reading <tt>FCGI_PARAMS</tt> before it begins
821 writing <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt>, but
822 it needn't finish reading from <tt>FCGI_STDIN</tt> before it
823 begins writing these two streams.<p>
825 After sending all its <tt>stdout</tt> and <tt>stderr</tt> data,
826 the Responder application sends a <tt>FCGI_END_REQUEST</tt> record.
827 The application sets the <tt>protocolStatus</tt> component to
828 <tt>FCGI_REQUEST_COMPLETE</tt> and the <tt>appStatus</tt> component
829 to the status code that the CGI program would have returned
830 via the <tt>exit</tt> system call.<p>
833 A Responder performing an update, e.g. implementing a <tt>POST</tt>
834 method, should compare the number of bytes received on <tt>FCGI_STDIN</tt>
835 with <tt>CONTENT_LENGTH</tt> and abort the update if the two numbers
839 <h4><a name = "S6.3">6.3 Authorizer</a></h4>
841 An Authorizer FastCGI application receives all the information
842 associated with an HTTP request and generates an
843 authorized/unauthorized decision. In case of an authorized
844 decision the Authorizer can also associate name-value pairs
845 with the HTTP request; when giving an unauthorized
846 decision the Authorizer sends a complete response to the HTTP client.
849 Since CGI/1.1 defines a perfectly good way to represent the information
850 associated with an HTTP request, Authorizers use the same
855 The Authorizer application receives
856 HTTP request information from the Web
857 server on the <tt>FCGI_PARAMS</tt> stream,
858 in the same format as a Responder. The Web server does not
859 send <tt>CONTENT_LENGTH</tt>,
860 <tt>PATH_INFO</tt>, <tt>PATH_TRANSLATED</tt>, and
861 <tt>SCRIPT_NAME</tt> headers.<p>
863 The Authorizer application sends
864 <tt>stdout</tt> and <tt>stderr</tt> data in
865 the same manner as a Responder. The CGI/1.1 response
866 status specifies the disposition of the request. If the
867 application sends status 200 (OK), the Web server allows
868 access. Depending upon its configuration the Web server
869 may proceed with other access checks, including requests to other
872 An Authorizer application's 200 response may include headers
873 whose names are prefixed with <tt>Variable-</tt>. These
874 headers communicate name-value pairs from the
875 application to the Web server. For instance, the response header
877 Variable-AUTH_METHOD: database lookup
879 transmits the value <tt>"database lookup"</tt> with name
880 <tt>AUTH-METHOD</tt>. The server associates such name-value
881 pairs with the HTTP request and includes them in subsequent
882 CGI or FastCGI requests performed in processing the HTTP
883 request. When the application gives a 200 response, the
884 server ignores response headers whose names aren't prefixed
885 with <tt>Variable-</tt> prefix, and ignores any response
888 For Authorizer response status values other than "200" (OK), the
889 Web server denies access and sends
890 the response status, headers, and content
891 back to the HTTP client.<p>
895 <h4><a name = "S6.4">6.4 Filter</a></h4>
897 A Filter FastCGI application receives all the information associated
898 with an HTTP request, plus an extra stream of data from a file stored
899 on the Web server, and generates a "filtered" version of the data
900 stream as an HTTP response.<p>
902 A Filter is similar in functionality to a Responder that takes a data
903 file as a parameter. The difference is that with a Filter, both the
904 data file and the Filter itself can be access controlled using the Web
905 server's access control mechanisms, while a Responder that takes the
906 name of a data file as a parameter must perform its own access control
907 checks on the data file.<p>
909 The steps taken by a Filter are similar to those of a Responder.
910 The server presents the Filter with environment variables first,
911 then standard input (normally form <tt>POST</tt> data), finally
912 the data file input:<p>
915 Like a Responder, the Filter application receives name-value
916 pairs from the Web server over <tt>FCGI_PARAMS</tt>.
917 Filter applications receive two Filter-specific variables:
918 <tt>FCGI_DATA_LAST_MOD</tt> and <tt>FCGI_DATA_LENGTH</tt>.<p>
920 Next the Filter application receives CGI/1.1 <tt>stdin</tt> data from
921 the Web server over <tt>FCGI_STDIN</tt>. The application receives
922 at most <tt>CONTENT_LENGTH</tt> bytes from this stream before
923 receiving the end-of-stream indication. (The application
924 receives less than <tt>CONTENT_LENGTH</tt> bytes only if the
925 HTTP client fails to provide them, e.g. because the client
928 Next the Filter application receives the file data from the
929 Web server over <tt>FCGI_DATA</tt>. This file's last
930 modification time (expressed as an integer number of seconds
931 since the epoch January 1, 1970 UTC) is
932 <tt>FCGI_DATA_LAST_MOD</tt>; the application may consult
933 this variable and respond from a cache without reading
934 the file data. The application
935 reads at most <tt>FCGI_DATA_LENGTH</tt> bytes from this stream
936 before receiving the end-of-stream indication.<p>
938 The Filter application sends CGI/1.1 <tt>stdout</tt> data to the Web
939 server over <tt>FCGI_STDOUT</tt>, and CGI/1.1 <tt>stderr</tt> data
940 over <tt>FCGI_STDERR</tt>. The application sends these
941 concurrently, not one after the other. The application must
942 wait to finish reading <tt>FCGI_STDIN</tt> before it begins
943 writing <tt>FCGI_STDOUT</tt> and <tt>FCGI_STDERR</tt>, but
944 it needn't finish reading from <tt>FCGI_DATA</tt> before it
945 begins writing these two streams.<p>
947 After sending all its <tt>stdout</tt> and <tt>stderr</tt> data,
948 the application sends a <tt>FCGI_END_REQUEST</tt> record.
949 The application sets the <tt>protocolStatus</tt> component to
950 <tt>FCGI_REQUEST_COMPLETE</tt> and the <tt>appStatus</tt> component
951 to the status code that a similar CGI program would have returned
952 via the <tt>exit</tt> system call.<p>
955 A Filter should compare the number of bytes received on <tt>FCGI_STDIN</tt>
956 with <tt>CONTENT_LENGTH</tt> and on <tt>FCGI_DATA</tt>
957 with <tt>FCGI_DATA_LENGTH</tt>. If the numbers don't match
958 and the Filter is a query, the Filter
959 response should provide an indication that data is missing.
960 If the numbers don't match and the Filter is an update, the Filter
961 should abort the update.<p>
965 <h3><a name = "S7">7. Errors</a></h3>
967 A FastCGI application exits with zero status to indicate that it
968 terminated on purpose, e.g. in order to perform a crude form of
969 garbage collection. A FastCGI application that exits with nonzero
970 status is assumed to have crashed. How a Web server or other
971 application manager responds to
972 applications that exit with zero or nonzero status is outside the
973 scope of this specification.<p>
975 A Web server can request that a FastCGI application exit by sending it
976 <tt>SIGTERM</tt>. If the application ignores <tt>SIGTERM</tt> the Web
977 server can resort to <tt>SIGKILL</tt>.<p>
979 FastCGI applications report application-level errors with the
980 <tt>FCGI_STDERR</tt> stream and the <tt>appStatus</tt> component of
981 the <tt>FCGI_END_REQUEST</tt> record. In many cases an error will be
982 reported directly to the user via the <tt>FCGI_STDOUT</tt> stream.<p>
984 On Unix, applications report lower-level errors, including
985 FastCGI protocol errors and syntax errors in FastCGI environment
986 variables, to <tt>syslog</tt>. Depending upon the severity
987 of the error, the application may either continue or
988 exit with nonzero status.<p>
992 <h3><a name = "S8">8. Types and Constants</a></h3>
995 * Listening socket file number
997 #define FCGI_LISTENSOCK_FILENO 0
1000 unsigned char version;
1002 unsigned char requestIdB1;
1003 unsigned char requestIdB0;
1004 unsigned char contentLengthB1;
1005 unsigned char contentLengthB0;
1006 unsigned char paddingLength;
1007 unsigned char reserved;
1011 * Number of bytes in a FCGI_Header. Future versions of the protocol
1012 * will not reduce this number.
1014 #define FCGI_HEADER_LEN 8
1017 * Value for version component of FCGI_Header
1019 #define FCGI_VERSION_1 1
1022 * Values for type component of FCGI_Header
1024 #define FCGI_BEGIN_REQUEST 1
1025 #define FCGI_ABORT_REQUEST 2
1026 #define FCGI_END_REQUEST 3
1027 #define FCGI_PARAMS 4
1028 #define FCGI_STDIN 5
1029 #define FCGI_STDOUT 6
1030 #define FCGI_STDERR 7
1032 #define FCGI_GET_VALUES 9
1033 #define FCGI_GET_VALUES_RESULT 10
1034 #define FCGI_UNKNOWN_TYPE 11
1035 #define FCGI_MAXTYPE (FCGI_UNKNOWN_TYPE)
1038 * Value for requestId component of FCGI_Header
1040 #define FCGI_NULL_REQUEST_ID 0
1043 unsigned char roleB1;
1044 unsigned char roleB0;
1045 unsigned char flags;
1046 unsigned char reserved[5];
1047 } FCGI_BeginRequestBody;
1051 FCGI_BeginRequestBody body;
1052 } FCGI_BeginRequestRecord;
1055 * Mask for flags component of FCGI_BeginRequestBody
1057 #define FCGI_KEEP_CONN 1
1060 * Values for role component of FCGI_BeginRequestBody
1062 #define FCGI_RESPONDER 1
1063 #define FCGI_AUTHORIZER 2
1064 #define FCGI_FILTER 3
1067 unsigned char appStatusB3;
1068 unsigned char appStatusB2;
1069 unsigned char appStatusB1;
1070 unsigned char appStatusB0;
1071 unsigned char protocolStatus;
1072 unsigned char reserved[3];
1073 } FCGI_EndRequestBody;
1077 FCGI_EndRequestBody body;
1078 } FCGI_EndRequestRecord;
1081 * Values for protocolStatus component of FCGI_EndRequestBody
1083 #define FCGI_REQUEST_COMPLETE 0
1084 #define FCGI_CANT_MPX_CONN 1
1085 #define FCGI_OVERLOADED 2
1086 #define FCGI_UNKNOWN_ROLE 3
1089 * Variable names for FCGI_GET_VALUES / FCGI_GET_VALUES_RESULT records
1091 #define FCGI_MAX_CONNS "FCGI_MAX_CONNS"
1092 #define FCGI_MAX_REQS "FCGI_MAX_REQS"
1093 #define FCGI_MPXS_CONNS "FCGI_MPXS_CONNS"
1097 unsigned char reserved[7];
1098 } FCGI_UnknownTypeBody;
1102 FCGI_UnknownTypeBody body;
1103 } FCGI_UnknownTypeRecord;
1109 <h3><a name = "S9">9. References</a></h3>
1112 National Center for Supercomputer Applications,
1113 <a href = "http://hoohoo.ncsa.uiuc.edu/cgi/">The Common Gateway Interface</a>,
1117 <a href = "http://ds.internic.net/internet-drafts/draft-robinson-www-interface-01.txt">The WWW Common Gateway Interface Version 1.1</a>, Internet-Draft, 15 February 1996.<p>
1121 <h3><a name = "SA">A. Table: Properties of the record types</a></h3>
1123 The following chart lists all of the record types and
1124 indicates these properties of each:<p>
1127 <li><tt>WS->App</tt>:
1128 records of this type can only be sent by the Web server to the
1129 application. Records of other types can only be sent by the
1130 application to the Web server.<p>
1131 <li><tt>management</tt>:
1132 records of this type contain information that is not specific
1133 to a Web server request, and use the null request ID. Records
1134 of other types contain request-specific information, and cannot
1135 use the null request ID.<p>
1136 <li><tt>stream</tt>:
1137 records of this type form a stream, terminated by a
1138 record with empty <tt>contentData</tt>. Records of other types
1139 are discrete; each carries a meaningful unit of data.<p>
1143 WS->App management stream
1146 FCGI_GET_VALUES_RESULT x
1149 FCGI_BEGIN_REQUEST x
1150 FCGI_ABORT_REQUEST x
1164 <h3><a name = "SB">B. Typical Protocol Message Flow</a></h3>
1166 Additional notational conventions for the examples:
1169 <li>The <tt>contentData</tt> of stream records (<tt>FCGI_PARAMS</tt>,
1170 <tt>FCGI_STDIN</tt>, <tt>FCGI_STDOUT</tt>, and <tt>FCGI_STDERR</tt>)
1171 is represented as a character string. A string ending in
1172 <tt>" ... "</tt> is too long to display, so only a prefix is shown.
1174 <li>Messages sent to the Web server are indented
1175 with respect to messages received from the Web server.
1177 <li>Messages are shown in the time sequence experienced
1181 1. A simple request with no data on <tt>stdin</tt>, and a successful response:
1183 {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}}
1184 {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}
1185 {FCGI_PARAMS, 1, ""}
1188 {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<html>\n<head> ... "}
1189 {FCGI_STDOUT, 1, ""}
1190 {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
1193 2. Similar to example 1, but this time with data on <tt>stdin</tt>.
1194 The Web server chooses to send the
1195 parameters using more <tt>FCGI_PARAMS</tt> records than before:
1197 {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}}
1198 {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SER"}
1199 {FCGI_PARAMS, 1, "VER_ADDR199.170.183.42 ... "}
1200 {FCGI_PARAMS, 1, ""}
1201 {FCGI_STDIN, 1, "quantity=100&item=3047936"}
1204 {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<html>\n<head> ... "}
1205 {FCGI_STDOUT, 1, ""}
1206 {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
1209 3. Similar to example 1, but this time the application detects an error.
1210 The application logs a message to
1211 <tt>stderr</tt>, returns a page to the client, and returns
1212 non-zero exit status to the Web server. The application
1213 chooses to send the page using more <tt>FCGI_STDOUT</tt> records:
1215 {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}}
1216 {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}
1217 {FCGI_PARAMS, 1, ""}
1220 {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<ht"}
1221 {FCGI_STDERR, 1, "config error: missing SI_UID\n"}
1222 {FCGI_STDOUT, 1, "ml>\n<head> ... "}
1223 {FCGI_STDOUT, 1, ""}
1224 {FCGI_STDERR, 1, ""}
1225 {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}}
1228 4. Two instances of example 1, multiplexed onto a single connection.
1229 The first request is more difficult than the second, so the
1230 application finishes the requests out of order:
1232 {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
1233 {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}
1234 {FCGI_PARAMS, 1, ""}
1235 {FCGI_BEGIN_REQUEST, 2, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
1236 {FCGI_PARAMS, 2, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "}
1239 {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n"}
1241 {FCGI_PARAMS, 2, ""}
1244 {FCGI_STDOUT, 2, "Content-type: text/html\r\n\r\n<html>\n<head> ... "}
1245 {FCGI_STDOUT, 2, ""}
1246 {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}}
1247 {FCGI_STDOUT, 1, "<html>\n<head> ... "}
1248 {FCGI_STDOUT, 1, ""}
1249 {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
1255 © 1995, 1996 Open Market, Inc. / mbrown@openmarket.com