You are here: Chapter 7: Configuration and Administration > System Administration > System Administration Features > FastCGI

FastCGI

FastCGI is a technology that can boost the performance of FootPrints, and is available for use with the application. FastCGI is available on all supported platforms. The technology can be compared to an automobile. The default FootPrints installation uses CGI which is akin to starting up a car and pressing the accelerator every time a page is viewed. FastCGI leaves the car running, so that the initial step of starting the car can be avoided on each page view. Below are the steps an administrator must complete before enabling the acceleration technology.

In following the steps below, c:\FootprintsServiceCore or /usr/local/footprintsservicecore refers to the "base install location" (i.e. "where FootPrints is installed") of FootPrints. By default, this would be c:\FootprintsServiceCore on a Windows server and /usr/local/footprintsservicecore on a Unix or Linux server. When performing the steps below, please adjust the path accordingly for the actual "base install location" of FootPrints in your environment.

Switching from PerlEx to FastCGI

To change from the PerlEx engine to the FastCGI engine:

  1. Select Administration | System from the FootPrints Toolbar, then select PerlEx/FastCGI from the Features section of the System Administration page.  The PerlEx/FastCGI page is displayed.
  2. In the PerlEx section of the page, click the Disabled radio button.
  3. Enter the System Administration password in the space provided and click the Save button.

FastCGI

Windows Server 2003 and 2003 R2 with IIS 6 (32-bit and 64-bit)

FootPrints FastCGI on this platform requires the IIS FastCGI extension, and a URL rewriting mechanism (we recommend Ionic's ISAPI Rewrite Filter [IIRF]). These instructions are for a system that currently does not have any other FastCGI applications installed . If there are other FastCGI applications running on this machine, please contact BMC Support for further assistance.

Install and Configure Fast CGI, and Enable in IIS

  1. Install FastCGI for IIS 6.0 by using the Web Platform Installer (WPI) at this address: http://www.iis.net/download/fastcgi.
  2. Configure FastCGI by editing the fcgiext.ini file in the "<Windows Root>\system32\inetsrv" directory. Remove the entire contents of this file, and add the following to the end:

[Types]

fcgi=FootPrints FastCGI

[FootPrints FastCGI]

ExePath="c:\FootprintsServiceCore\bin\Perl\bin\perl.exe"

Arguments="c:\FootprintsServiceCore\cgi\CentralDispatch.fcgi"

QueueLength=500

InstanceMaxRequests=5000

MaxInstances=5

StderrMode=IgnoreAndReturn200

  1. Enable the FastCGI extension in IIS.
  2. Open up the IIS manager (Start -> Run -> inetmgr.exe), and right-click the 'MRcgi' virtual directory item. Open the 'Properties' window from this menu.
  3. Click on the 'Virtual Directory' tab, and then click the 'Configuration' button.
  4. Click the 'Add' button on the 'Mappings' tab to add a new extension mapping.
  5. Set the executable field to:

<Windows Root>\system32\inetsrv\fcgiext.dll

  1. Set the extension field to:

.fcgi

  1. Press the OK button.

Install the URL Rewriting Mechanism (IIRF)

The following instructions describe how to install the URL rewriting mechanism, Ionic's ISAPI Rewrite Filter (IIRF), that will rewrite URLs, for example:

http://localhost/MRcgi/MRentrancePage.pl?PROJECTID=3

to

http://localhost/MRcgi/CentralDispatch.fcgi?dispatch_script=MRentrancePage.pl&PROJECTID=3

  1. Go to http://iirf.codeplex.com/releases and download the correct version of the "Iirf".msi file for your server (x64 or x86).
  2. Install IIRF by following the steps on Iconic's installation wizard.

Configure IIRF

    1. Right-click the 'IIRF.dll' file and click 'Properties'.
    2. Under the 'Security' tab, verify that the IIS web group has read and execute privileges on the file (by default the group is called IIS_WPG).
    3. Once the permissions have been verified, start up the IIS manager: Start -> Run, enter inetmgr.exe and then click the OK button. Right-click the website that is running FootPrints (by default it will be 'Default Web Site') and click 'Properties'.
    4. Click the 'ISAPI Filters' tab, and click the 'Add' button. For 'Filter Name', enter 'IIRF' or some other uniquely identifiable name. For 'Executable', click the Browse button and choose the 'IIRF.dll' file in the IIRF bin directory.
    5. Copy the IIRF.template file from the 'etc' directory into the cgi directory. Rename this file IIRF.ini. Edit the file and change the line that says RewriteEngine OFF to RewriteEngine ON. If you have previously done this, and have made changes to this file, make sure that the changes are propagated to the new copy.
    6. Restart the web server (Start -> Run -> iisreset.exe), and then visit this URL: http://localhost/iirfStatus. The server name ('localhost' in this example) should be switched with the name of the server running FootPrints. If IIRF is working properly, you will see a status screen describing the IIRF instance that is currently running.
    7. On the 'System Administration' page in FootPrints, click the 'FastCGI' page. Verify that FastCGI is active (it will be stated in the FastCGI section).
  • To Disable FastCGI

    To disable FastCGI, edit the 'IIRF.ini' file located in the 'cgi' directory of FootPrints, and change the line that says 'RewriteEngine ON' to 'RewriteEngine OFF'.

    Windows Server 2008 and 2008 R2 with IIS 7.x (32-bit and 64-bit)

    FootPrints FastCGI on this platform requires the IIS FastCGI extension (which should be enabled already), and URL Rewrite 2.0 from Microsoft. These instructions are for a system that currently does not have any other FastCGI applications installed. If there are other FastCGI applications running on this machine, please contact BMC Support for further assistance.

    NOTE FOR WINDOWS SERVER 2008 SP1 and SP2 (does not apply to Windows Server 2008 R2)

    A default installation of Windows Server 2008 SP1 and SP2 requires a hotfix from Microsoft in order for FastCGI to run properly. The hotfix from Microsoft is available through the following Microsoft KB article:

    http://support.microsoft.com/?kbid=980363

    In addition, a package must be installed on the Windows Server 2008 host to enable the "FastCGI Settings" IIS option. The package can be installed from this URL:

    http://www.iis.net/download/AdministrationPack

    After applying the hotfix and the Administration Pack, run the MRconfigFastCGI.pl script, as indicated in step 2 below.

    The FastCGI Settings, as identified in Step 5 below, will be available after installing the Administration Pack, but there is no option for the 'Standard Error Mode' setting. After executing the MRconfigFastCGI.pl script, the Windows Administrator can check the C:\Windows\System32\inetsrv\config\applicationHost.config file for the proper configuration of FastCGI. The correct configuration in this file is as follows:

    <fastCgi>

    <application fullPath="c:\FootprintsServiceCore\bin\Perl\bin\perl.exe" arguments="c:\FootprintsServiceCore\cgi\CentralDispatch.fcgi" stderrMode="IgnoreAndReturn200" maxInstances="5" idleTimeout="300" activityTimeout="70" requestTimeout="90" instanceMaxRequests="3000" protocol="NamedPipe" flushNamedPipe="false" />

    </fastCgi>

    1. Install URL Rewrite 2.0 by using the Web Platform Installer (WPI) at this address: http://www.iis.net/download/URLRewrite.
    2. A script is available to automatically enable FastCGI for FootPrints on this platform configuration. To execute the script, open a shell (Run -> ‘cmd.exe’) and navigate to the ‘cgi’ directory inside the FootPrints application directory. Execute the following command, and adjust the paths to match the FootPrints installation on this machine. 

    c:\FootprintsServiceCore\bin\Perl\bin\Perl.exe MRConfigFastCGI.pl

    1. The script will present you with a menu of options. Select ‘Enable FastCGI’. If this script successfully executes, skip to step 7 and verify that FastCGI is active. If the script failed to run properly, or if you would like to manually enable FastCGI, continue on to step 4.
    2. Add the FastCGI module mapping for IIS.
    3. Go to 'Start -> Run -> inetmgr.exe', and click on the 'MRcgi' virtual directory in the tree in the left pane.
    4. In the right pane, double-click the 'Handler Mappings' icon. Right-click in the mapping list and select 'Add module mapping'.
    5. For the 'Request Path' field enter:

    *.fcgi

    1. In the 'Module' dropdown select 'FastCgiModule'. For the 'Executable' field, enter the following value and be sure to update the paths to match the actual FootPrints installation on this machine:

    c:\FootprintsServiceCore\bin\Perl\bin\perl.exe|c:\FootprintsServiceCore\cgi\CentralDispatch.fcgi

    1. For the 'Name' field enter:

    FootPrints FastCGI Handler

    1. When you complete the above dialog, you will be presented with another dialog asking if a FastCGI application should be created for this mapping. Answer ‘Yes’ to this dialog.
    2. Configure the FastCGI application:
    3. In the left pane of the IIS administration window, click on the item representing the entire computer or host (it will normally be at the top level of the tree under ‘Start Page’).
    4. In the right pane, double-click the ‘FastCGI Settings’ icon.
    5. Double-click the row on this page that has ‘CentralDispatch.fcgi’ listed in the Arguments column (the path to CentralDispatch.fcgi will also be present in the same column).
    6. Set the ‘Standard Error Mode’ setting to IgnoreAndReturn200.
    7. Set the ‘Activity Timeout’ to 70.
    8. Set ‘Instance MaxRequests’ to 3000.
    9. Set ‘Max Instances’ to 5.
    10. All of the other settings can be left at their default values.
    11. Configure URL Rewrite for FastCGI.
    12. Go to Start -> Run -> inetmgr.exe, and click on the 'MRcgi' virtual directory in the tree in the left pane.
    13. In the right pane, double-click the 'URL Rewrite' icon. Right-click in the 'Inbound Rule List' (the top section) and select 'Add Rule'.
    14. Select to create a blank rule. You must give the rule a name.
    15. 'Requested URL' should be set to 'Matches the Pattern', and 'Using' should be set to 'Regular Expressions'. The 'Pattern' field should be set to:

    /?(\w+\.pl)(?!ex)

    1. Make sure the 'Ignore Case' checkbox is checked.
    2. Inside the 'Conditions' section, make sure that the 'Logical grouping' field is set to 'Match All', and click the 'Add' button. The 'Condition Input' is set to:

    {R:1}

    1. 'Check if input string' should be set to 'Matches the Pattern'.
    2. The 'Pattern' field should be set to the following (this is all one string without spaces or breaks):

    ^(?:MRenablePerlEx\.pl|MRABregdetails\.pl|MRABreghome\.pl|MRABregsearch_page\.pl|MRcheckBack\.pl|MRdirectEdit2\.pl|MRdirectSearch\.pl|MRentrancePage\.pl|MRhomepage\.pl|MRlogin\.pl|MRlogsAlert\.pl|MRquickHelp\.pl|MRregister_command\.pl|MRsearch_page\.pl|MRspellCheck\.pl|MRTicketPage\.pl|MRAjaxLoadDashboardComponent\.pl)$

    1. In the 'Action' section, set the 'Action Type' to 'Rewrite' and the 'Rewrite URL' to:

    /MRcgi/CentralDispatch.fcgi?dispatch_script={R:1}

    1. Make sure the 'Append query string' checkbox is checked, and that the 'Log rewritten URL' checkbox is unchecked.
    2. Make sure that the 'Stop processing of subsequent rules' checkbox is checked.
    3. Click the 'Apply' link on the right under 'Actions'.
    4. Visit the 'System Administration' page in FootPrints, and click on the 'PerlEx' or the 'FastCGI' page. Verify that FastCGI is active (it will be stated in the FastCGI section).

    To disable FastCGI, click on the rewrite rule in the 'Inbound Rule List' and select 'Disable Rule' from the actions menu on the right.

    Unix/Linux with Apache 2 (32-bit or 64-bit)

    FootPrints FastCGI on a Unix/Linux with Apache 2 (32-bit or 64-bit) platform requires installing and activating the mod_fcgid and mod_rewrite Apache modules before performing the procedure below. These instructions are for a system that does not have any existing FastCGI applications running. If FastCGI applications are running on the same machine as the one on which you are installing FootPrints, contact BMC Support for further assistance.

    1. Make sure that the following are installed:
    2. Apache Development package (httpd-devel)
    3. Apache Portable Runtime (apr)
    4. Apache Portable Runtime Development package (apr-devel)
    5. Apache Portable Runtime Utilities package (apr-util)
    6. GNU Build toolchain (make, ld, ar, gcc, etc.)
    7. Download the most recent mod_fcgid source from the Apache Foundation (http://httpd.apache.org/download.cgi#mod_fcgid)
    8. Unpack tarball and change directory to the unpack directory.
    9. Run:

    ./configure.apxs

    1. Run:

    make

    1. Run:

    make install

    1. The `make install` inserts a line into the httpd.conf file to load the newly built module:

    LoadModule fcgid_module modules/mod_fcgid.so

    1. Run:

    mkdir /var/run/fcgidsock

    chown apache:root /var/run/fcgidsock

    chmod 700 /var/run/fcgidsock

    1. Edit the FootPrints Apache configuration file and add the following information to the end of the file. You cannot cut and paste these instructions. You must change the path of the LoadModule directive and the path of the FootPrints application directory (<Directory "/usr/local/footprintsservicecore/cgi">) in the instructions to match your system:

    <Directory "/usr/local/footprintsservicecore/cgi">

    RewriteEngine on

    RewriteCond $1 ^(?:MRenablePerlEx\.pl|MRABregdetails\.pl|MRABreghome\.pl|MRABregsearchpage\.pl|MRcheckBack\.pl|MRdirectEdit2\.pl|MRdirectSearch\.pl|MRentrancePage\.pl|MRhomepage\.pl|MRlogin\.pl|MRlogsAlert\.pl|MRquickHelp\.pl|MRregister_command\.pl|MRsearch_page\.pl|MRspellCheck\.pl|MRTicketPage\.pl|MRAjaxLoadDashboardComponent\.pl) [NC]

    RewriteRule /?(\w+\.pl)(?!ex) /MRcgi/CentralDispatch.fcgi?dispatch_script=$1&%{QUERY_STRING} [L,NC]

    </Directory>

    LoadModule fcgid_module modules/mod_fcgid.so

    FcgidIPCDir /var/run/fcgidsock

    FcgidProcessTableFile /var/run/fcgidsock/fcgidsock_shm

    FcgidBusyScanInterval 30

    FcgidIdleScanInterval 120

    FcgidMaxRequestInMem 262144

    FcgidMaxRequestLen 262144

    FcgidMaxRequestsPerProcess 1000

    FcgidOutputBufferSize 524288

    AddHandler fcgid-script fcgi

    1. Restart the Apache web server.
    2. In FootPrints, select Administration | System from the toolbar, then select Perlex/FastCGI from the Administration page.
    3. In the FastCGI Setup section of the administration page, verify that FastCGI is active.

    To disable FastCGI, set the 'RewriteEngine on' line in the configuration file to 'RewriteEngine off'.

    By default, the communications sockets reside in the Apache logs/fcgidsock directory, which is accessible only by root and not by child Apache processes. In this default configuration, a FastCGI process can never create the communications socket, resulting in a "Service Unavailable" message. In order for the default configuration to work, you can add an execute bit for the "other" group (permissions change from 700 to 701) on the/var/log/httpd directory. However, this creates two other problems:

    1. Adding this execute bit allows all other users the ability to change directory into /var/log/httpd.
    2. If the Apache program is updated via OS means (yum update httpd), there is a very good chance that the update could alter the file system permissions changes that allow FastCGI to function.

    When configuring the mod_fcgid module in Apache, there are directives which allow the communications sockets to be placed in an alternate directory. The communications socket directive should be pointed at a directory in /var/run (numerous other applications use this same directory structure to store their PID and socket files).