FastCGI ISAPI 1.5 Beta for WinXP and Win2K3

IIS team today released FastCGI ISAPI 1.5 Beta for WinXP and Win2K3 which has some very nice additions to existing FastCGI ISAPI functionality. Following additions have been made to FastCGI ISAPI 1.0.

1. Few features we added to FastCGI module in IIS 7.5 have been added to FastCGI ISAPI 1.5 as well. These include MonitorChangesTo, StderrMode and Real-time tuning. Read more about these here.

Few customers complained about IIS terminating the FastCGI processes abruptly (on running into IdleTimeout, InstanceMax etc) without giving them a chance to run cleanup code in the FastCGI application. In FastCGI ISAPI 1.5, we have added ability to get a signal from IIS whenever we are about to terminate a child process. To enable this, you need to set SignalBeforeTerminateSeconds property in fcgiext.ini to greater than 0. When this functionality is enabled, IIS will create an inheritable event and pass its handle value to child process as value of _FCGI_SHUTDOWN_EVENT_ environment variable. If FastCGI ISAPI ever encounters a situation (like worker process shutting down, fcgiext.ini changed, file being monitored changed etc) and is required to terminate the child process, it will first signal this event and wait for a maximum of SignalBeforeTerminateSeconds for process to terminate on its own. On detecting event being signaled, child processes can terminate themselves cleanly. If child process are still alive after the wait period, IIS will forcibly terminate them.

Name of the named pipe through which communication with FastCGI process is taking place is communicated as value of _FCGI_X_PIPE_ environment variable.

4. Many customers faced trouble with FastCGI 1.0 because they accidently added some invalid configuration to fcgiext.ini and couldn’t decipher the cryptic error message they got from FastCGI ISAPI. In this release, if we see an invalid property present or invalid value of an enum type property, we exactly tell you what’s wrong in fcgiext.ini and where the error is.

5. FastCGI 1.0 had very strict checking on validity of response headers. We got bunch of reports from customers who complained about this difference of behavior compared to other web servers. In this release, we have removed these checks. If we find an invalid response header, we silently drop it from the response. This behavior matches behavior of other web servers.

6. Customers easily ran into ActivityTimeout especially while running install.php code of popular PHP applications. So we have changed default value of ActivityTimeout from 30 seconds to 70 seconds.

Below are the download links to FastCGI ISAPI 1.5 Beta. If you are using WebPI, FastCGI 1.5 is available under “what’s new” section. You can upgrade from FastCGI ISAPI 1.0 to FastCGI ISAPI 1.5 Beta or do a fresh install today. If you any feedback or trouble using FastCGI ISAPI 1.5, please report it on forums.

X86 –

X64 –


We also worked with Mike from Coast Research who fixed many issues in libfcgi.dll. Also he made changes to libfcgi.dll to make it handle SIGTERM properly using SignalBeforeTerminate functionality we added to FastCGI. Mike kindly released updated libfcgi (called libfcgi2.dll) so that others can now write a FastCGI application with much less pain. You can download libfcgi2.dll from here. Mike has published samples and documentation on how to use libfcgi2.dll on Complete white paper on additions to libfcgi2.dll can be found here.



Improvements to FastCGI in IIS 7.5

Following improvements have been made to FastCGI module in Win7 (and Win2K8 R2).

1.       Monitor changes to a file

  We have added ability to monitor changes to a file for each FastCGI process pool. Module will recycle FastCGI processes for the process pool if a change to the file is detected. Users can specify file path to monitor using system.webServer/fastCgi/application@monitorChangesTo property. Value can be absolute path to the file or path relative to the folder containing FastCGI executable. In case of php, if fullPath property is set to “c:\php\php-cgi.exe”, monitorChangesTo property can be set to “php.ini” or “c:\php\php.ini”. If file to monitor is not found, status code 500 is returned on each request. Default value of this property is blank which means no file monitoring.      

2.       Real-time tuning

In win2k8, maxInstances property could be configured to a constant value greater than 0. This value dictated maximum number of FastCGI processes which can be launched for each application pool which is also equal to maximum number of requests which can be processed simultaneously as one process handle only one request at a time. Default value of this property was 4. Administrators were required to do some testing with different values to find the optimal number of maxInstances for their server. In win7, if you set maxInstances to 0, FastCGI module automatically adjusts this number up or down every few seconds based on the system load and number of requests waiting in the queue.

3.       Tracing

In win7, STDERR stream can be used to send trace messages to FastCGI module which are logged to IIS FREB trace (if enabled). Trace messages are identified by start markers “IIS_TRACE_INFO:”, “IIS_TRACE_WARNING:”, “IIS_TRACE_ERROR:”. Depending on which start marker is used, information/warning/error trace event is generated. End of a trace statement should be marked by “:IIS_TRACE_END”.  You can send as many trace statements as you like for each request. Most application frameworks running as FastCGI provide a way to send text on STDERR stream. In case of php, function error_log() can be used. So error_log(“IIS_TRACE_WARNING: Warning event.:IIS_TRACE_END”); statement in PHP code will make “Warning event” appear in IIS trace logs. Getting your application traces with traces generated by web server can be a very powerful tool for debugging problems. Note that starting from PHP 5.2.7 you can pass a parameter to the error_log() function to specify that the logged message should be always sent to STDERR regardless of error_log setting in php.ini. To do that use message_type parameter set to 4, e.g. error_log(“IIS_TRACE_WARNING: Warning event.:IIS_TRACE_END”, 4);

4.       STDERR stream handling

FastCGI module can now be configured to handle text sent on STDERR stream differently. In IIS7 we used to return status code 500 and send data received on STDERR stream as the response. Now the behavior can be modified by setting system.webServer/fastCgi/application@stderrMode property. Value of this property can be set to one of following values.

ReturnStderrIn500 – We will set status code 500 and send whatever we receive on STDERR as response. This is the default value and gives same behavior as IIS7.
ReturnGeneric500 – Module will set status code 500 but will return a generic 500. This configuration is useful if you want to enable detailed error logging for server but don’t want to return these errors to users.
IgnoreAndReturn200 – Text on STDERR stream is completely ignored and we will send what we receive on STDOUT as response with status code 200. This property is useful if use debug statements for tracking purposes.
TerminateProcess – FastCGI process will get terminated and generic 500 error message will be returned.

Trace statements are removed from STDERR stream before they are subjected to stderrMode logic. Post Win7 Beta, we are looking into making FastCGI work with CpuLimit feature and also dropping invalid response headers instead of failing requests with 500.

Hope this helps.