Environment Variable <environmentVariable>

Article
03/21/2022

The <environmentVariable> element of the <environmentVariables> element adds a unique name/value pair of an environment variable that Internet Information Services (IIS) 7 will pass to a FastCGI process when it is launched.

Each FastCGI application that is installed on IIS 7 may allow or require environment variables to configure how the FastCGI application works. For example, one FastCGI application may require an environment variable that specifies where the application's configuration file is located, whereas another FastCGI application may require an environment variable that specifies the number of requests after which it will need to be recycled.

Compatibility

Version	Notes
IIS 10.0	The `<environmentVariable>` element was not modified in IIS 10.0.
IIS 8.5	The `<environmentVariable>` element was not modified in IIS 8.5.
IIS 8.0	The `<environmentVariable>` element was not modified in IIS 8.0.
IIS 7.5	The `<environmentVariable>` element was not modified in IIS 7.5.
IIS 7.0	The `<environmentVariable>` element of the `<environmentVariables>` element was introduced in IIS 7.0.
IIS 6.0	N/A

Setup

To use the FastCGI environment, you must first install the CGI role service. The installation process registers the Common Gateway Interface (CGI) role service in both the <globalModules> and <modules> elements. You do not need to perform any other steps to install the FastCGI environment.

Windows Server 2012 or Windows Server 2012 R2

On the taskbar, click Server Manager.
In Server Manager, click the Manage menu, and then click Add Roles and Features.
In the Add Roles and Features wizard, click Next. Select the installation type and click Next. Select the destination server and click Next.
On the Server Roles page, expand Web Server (IIS), expand Web Server, expand Application Development, and then select CGI. Click Next.
On the Select Features page, click Next.
On the Confirm installation selections page, click Install.
On the Results page, click Close.

Windows 8 or Windows 8.1

On the Start screen, move the pointer all the way to the lower left corner, right-click the Start button, and then click Control Panel.
In Control Panel, click Programs and Features, and then click Turn Windows features on or off.
Expand Internet Information Services, expand World Wide Web Services, expand Application Development Features, and then select CGI.
Click OK.
Click Close.

Windows Server 2008 or Windows Server 2008 R2

On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
On the Select Role Services page of the Add Role Services Wizard, select CGI, and then click Next.
On the Confirm Installation Selections page, click Install.
On the Results page, click Close.

Windows Vista or Windows 7

On the taskbar, click Start, and then click Control Panel.
In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
Expand Internet Information Services, then select CGI, and then click OK.

How To

Note for IIS 7.0 users: Some of the steps in this section may require that you install the Microsoft Administration Pack for IIS 7.0, which includes a user interface for FastCGI settings. To install the Microsoft Administration Pack for IIS 7.0, see the following URL:

https://www.iis.net/expand/AdministrationPack

How to create a global FastCGI handler mapping for PHP

Note

Before the following procedure will work, you must have already installed binaries that will execute the file path or file name extension that you specify. This example uses a PHP implementation available from www.php.net.

Open Internet Information Services (IIS) Manager:
- If you are using Windows Server 2012 or Windows Server 2012 R2:
  - On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows 8 or Windows 8.1:
  - Hold down the Windows key, press the letter X, and then click Control Panel.
  - Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
- If you are using Windows Server 2008 or Windows Server 2008 R2:
  - On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows Vista or Windows 7:
  - On the taskbar, click Start, and then click Control Panel.
  - Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
In the Connections pane, click the server name for which you want to configure FastCGI handler mappings.
In the Home pane, double-click Handler Mappings.
In the Actions pane, click Add Module Mapping.
Enter the following information:
- Enter the file name extension in the Request path text box. For example, "*.php".
- Click FastCgiModule in the Module drop-down list.
- Enter the path to the scripting engine in the Executable box. For example, "C:\PHP\php-cgi.exe".
- Enter a unique name for the handler mapping in the Name box. For example, "PHP-FastCGI".
- Click Request Restrictions.
- Select Invoke handler only if request is mapped to.
- Click to select the File or Folder option.
- Click OK.

Click OK.
If you are prompted to create a FastCGI application in the Add Module Mapping dialog box, click Yes.

Note

This will automatically create a FastCGI application for the handler mapping that you just created. If you choose No, you can manually create a FastCGI application later.

How to create a FastCGI application for PHP

Note

Adding a FastCGI application does not automatically add a handler mapping. To do so, you would need to follow the steps in the How to create a global FastCGI handler mapping for PHP section of this article.

Open Internet Information Services (IIS) Manager:
- If you are using Windows Server 2012 or Windows Server 2012 R2:
  - On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows 8 or Windows 8.1:
  - Hold down the Windows key, press the letter X, and then click Control Panel.
  - Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
- If you are using Windows Server 2008 or Windows Server 2008 R2:
  - On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows Vista or Windows 7:
  - On the taskbar, click Start, and then click Control Panel.
  - Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
In the Connections pane, click the server name for which you want to configure FastCGI settings.
In the Home pane, double-click FastCGI Settings.
In the Actions pane, click Add Application...
In the Add FastCGI Application dialog box, enter the following information:
- Enter the path to the scripting engine in the Full Path box. For example, "C:\PHP\php-cgi.exe".
- Enter the maximum number of requests for the FastCGI application.
  
  Note
  
  For PHP, this number must be lesser or equal to the maximum number of requests for PHP environment, which is configured by using the PHP_FCGI_MAX_REQUESTS environment variable.
Click the ellipsis (...) next to EnvironmentVariables to open the environment variables collection editor.
In the EnvironmentVariables Collection Editor dialog box, click Add.
Enter the following information, and then click OK:
- Enter "PHP_FCGI_MAX_REQUESTS" for the Name.
- Enter "10000" for the Value.
Click OK to close the Add FastCGI Application dialog box.

How add a FastCGI environment variable for PHP

Note

Open Internet Information Services (IIS) Manager:
- If you are using Windows Server 2012 or Windows Server 2012 R2:
  - On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows 8 or Windows 8.1:
  - Hold down the Windows key, press the letter X, and then click Control Panel.
  - Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
- If you are using Windows Server 2008 or Windows Server 2008 R2:
  - On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows Vista or Windows 7:
  - On the taskbar, click Start, and then click Control Panel.
  - Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
In the Connections pane, click the server name for which you want to configure FastCGI settings.
In the Home pane, double-click FastCGI Settings.
Highlight the PHP application in the FastCGI Settings pane, then click Edit... in the Actions pane.
In the Edit FastCGI Application dialog box, click the ellipsis (...) next to EnvironmentVariables to open the environment variables collection editor.
In the EnvironmentVariables Collection Editor dialog box, click Add.
Enter the following information, and then click OK:
- Enter "PHP_FCGI_MAX_REQUESTS" for the Name.
- Enter "10000" for the Value.
Click OK to close the Add FastCGI Application dialog box.

Configuration

Attributes

Attribute	Description
`name`	Optional string attribute. Specifies the name of the environment variable to pass to the FastCGI process.
`Value`	Optional string attribute. Specifies the value of the environment variable to pass to the FastCGI process.

Child Elements

None.

Configuration Sample

The following configuration sample adds a FastCGI application for PHP, sets the instanceMaxRequests attribute to "10000," and sets the PHP_FCGI_MAX_REQUESTS environment variable to "10000."

<fastCgi>
   <application fullPath="C:\PHP\php-cgi.exe"
         arguments=""
         maxInstances="4"
         idleTimeout="300"
         activityTimeout="30"
         requestTimeout="90"
         instanceMaxRequests="10000"
         protocol="NamedPipe"
         flushNamedPipe="false">
      <environmentVariables>
         <environmentVariable
            name="PHP_FCGI_MAX_REQUESTS"
            value="10000" />
      </environmentVariables>
   </application>
</fastCgi>

Note

For PHP, the value of the PHP_FCGI_MAX_REQUESTS environment variable must be a number that is lesser or equal to the value specified by the instanceMaxRequests attribute of the FastCGI <application> element.

The following configuration sample adds a global FastCGI handler mapping for PHP files to IIS and specifies the full path to a FastCGI executable file.

<configuration>
   <location path="" overrideMode="Allow">
      <system.webServer>
         <handlers>
            <add name="PHP-FastCGI"
                path="*.php"
                verb="GET,HEAD,POST"
                modules="FastCgiModule"
                scriptProcessor="C:\PHP\php-cgi.exe"
                resourceType="Either"
                requireAccess="Script" />
         </handlers>
      </system.webServer>
   </location>
</configuration>

Note

FastCGI settings can be configured per-site through the use of specially formatted FastCGI application and by handler mappings, which are distinguished by matching the fullPath and arguments attributes for an <application> element with the corresponding scriptProcessor attribute in the <handlers> mapping for the FastCGI process. To create these mappings, the settings in the fullPath and arguments attributes for an <application> element must be added to the scriptProcessor attribute in the <handlers> mapping for the FastCGI process and separated by the pipe "|" character. This combination serves as a unique key for each FastCGI application. For example, the following configuration excerpt shows two example <fastCgi>/<application> elements and their corresponding <handlers> mappings for two site-specific PHP handlers:

<fastCgi>
   <application fullPath="C:\PHP\php-cgi.exe"
      arguments="-d open_basedir=C:\Websites\Website1" />
   <application fullPath="C:\PHP\php-cgi.exe"
      arguments="-d open_basedir=C:\Websites\Website2" />
</fastCgi>

<system.webServer>
   <handlers accessPolicy="Read, Script"> 
      <add name="PHP via FastCGI 1"
         path="*.php"
         verb="*"
         modules="FastCgiModule"
         scriptProcessor="C:\PHP\php-cgi.exe|-d open_basedir=C:\Websites\Website1"
         resourceType="Unspecified"
         requireAccess="Script" />
      <add name="PHP via FastCGI 2"
         path="*.php"
         verb="*"
         modules="FastCgiModule"
         scriptProcessor="C:\PHP\php-cgi.exe|-d open_basedir=C:\Websites\Website2"
         resourceType="Unspecified"
         requireAccess="Script" />
</handlers>
</system.webServer>

Sample Code

The following code samples add a FastCGI application for PHP, set the instanceMaxRequests attribute to "10000," and set the PHP_FCGI_MAX_REQUESTS environment variable to "10000." Each sample also adds a global FastCGI handler mapping for PHP files to IIS and specifies the full path to a FastCGI executable file.

AppCmd.exe

appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='C:\PHP\php-cgi.exe',arguments='',maxInstances='4',idleTimeout='300',activityTimeout='30',requestTimeout='90',instanceMaxRequests='10000',protocol='NamedPipe',flushNamedPipe='False']" /commit:apphost

appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='C:\PHP\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']" /commit:apphost

appcmd.exe set config -section:system.webServer/handlers /+"[name='PHP-FastCGI',path='*.php',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='C:\PHP\php-cgi.exe',resourceType='Either',requireAccess='Script']" /commit:apphost

Note

You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();

         ConfigurationSection fastCgiSection = config.GetSection("system.webServer/fastCgi");
         ConfigurationElementCollection fastCgiCollection = fastCgiSection.GetCollection();
         ConfigurationElement applicationElement = fastCgiCollection.CreateElement("application");
         applicationElement["fullPath"] = @"C:\PHP\php-cgi.exe";
         applicationElement["arguments"] = @"";
         applicationElement["maxInstances"] = 4;
         applicationElement["idleTimeout"] = 300;
         applicationElement["activityTimeout"] = 30;
         applicationElement["requestTimeout"] = 90;
         applicationElement["instanceMaxRequests"] = 10000;
         applicationElement["protocol"] = @"NamedPipe";
         applicationElement["flushNamedPipe"] = false;

         ConfigurationElementCollection environmentVariablesCollection = applicationElement.GetCollection("environmentVariables");
         ConfigurationElement environmentVariableElement = environmentVariablesCollection.CreateElement("environmentVariable");
         environmentVariableElement["name"] = @"PHP_FCGI_MAX_REQUESTS";
         environmentVariableElement["value"] = @"10000";
         environmentVariablesCollection.Add(environmentVariableElement);
         fastCgiCollection.Add(applicationElement);

         ConfigurationSection handlersSection = config.GetSection("system.webServer/handlers");
         ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();
         ConfigurationElement addElement = handlersCollection.CreateElement("add");
         addElement["name"] = @"PHP-FastCGI";
         addElement["path"] = @"*.php";
         addElement["verb"] = @"GET,HEAD,POST";
         addElement["modules"] = @"FastCgiModule";
         addElement["scriptProcessor"] = @"C:\PHP\php-cgi.exe";
         addElement["resourceType"] = @"Either";
         addElement["requireAccess"] = @"Script";
         handlersCollection.AddAt(0, addElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample

   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration

      Dim fastCgiSection As ConfigurationSection = config.GetSection("system.webServer/fastCgi")
      Dim fastCgiCollection As ConfigurationElementCollection = fastCgiSection.GetCollection
      Dim applicationElement As ConfigurationElement = fastCgiCollection.CreateElement("application")
      applicationElement("fullPath") = "C:\PHP\php-cgi.exe"
      applicationElement("arguments") = ""
      applicationElement("maxInstances") = 4
      applicationElement("idleTimeout") = 300
      applicationElement("activityTimeout") = 30
      applicationElement("requestTimeout") = 90
      applicationElement("instanceMaxRequests") = 10000
      applicationElement("protocol") = "NamedPipe"
      applicationElement("flushNamedPipe") = False

      Dim environmentVariablesCollection As ConfigurationElementCollection = applicationElement.GetCollection("environmentVariables")
      Dim environmentVariableElement As ConfigurationElement = environmentVariablesCollection.CreateElement("environmentVariable")
      environmentVariableElement("name") = "PHP_FCGI_MAX_REQUESTS"
      environmentVariableElement("value") = "10000"
      environmentVariablesCollection.Add(environmentVariableElement)
      fastCgiCollection.Add(applicationElement)

      Dim handlersSection As ConfigurationSection = config.GetSection("system.webServer/handlers")
      Dim handlersCollection As ConfigurationElementCollection = handlersSection.GetCollection
      Dim addElement As ConfigurationElement = handlersCollection.CreateElement("add")
      addElement("name") = "PHP-FastCGI"
      addElement("path") = "*.php"
      addElement("verb") = "GET,HEAD,POST"
      addElement("modules") = "FastCgiModule"
      addElement("scriptProcessor") = "C:\PHP\php-cgi.exe"
      addElement("resourceType") = "Either"
      addElement("requireAccess") = "Script"
      handlersCollection.AddAt(0, addElement)

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var fastCgiSection = adminManager.GetAdminSection("system.webServer/fastCgi", "MACHINE/WEBROOT/APPHOST");
var fastCgiCollection = fastCgiSection.Collection;
var applicationElement = fastCgiCollection.CreateNewElement("application");
applicationElement.Properties.Item("fullPath").Value = "C:\\PHP\\php-cgi.exe";
applicationElement.Properties.Item("arguments").Value = "";
applicationElement.Properties.Item("maxInstances").Value = 4;
applicationElement.Properties.Item("idleTimeout").Value = 300;
applicationElement.Properties.Item("activityTimeout").Value = 30;
applicationElement.Properties.Item("requestTimeout").Value = 90;
applicationElement.Properties.Item("instanceMaxRequests").Value = 10000;
applicationElement.Properties.Item("protocol").Value = "NamedPipe";
applicationElement.Properties.Item("queueLength").Value = 1000;
applicationElement.Properties.Item("flushNamedPipe").Value = false;
applicationElement.Properties.Item("rapidFailsPerMinute").Value = 10;

var environmentVariablesCollection = applicationElement.ChildElements.Item("environmentVariables").Collection;
var environmentVariableElement = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement.Properties.Item("name").Value = "PHP_FCGI_MAX_REQUESTS";
environmentVariableElement.Properties.Item("value").Value = "10000";
environmentVariablesCollection.AddElement(environmentVariableElement);
fastCgiCollection.AddElement(applicationElement);

var handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST");
var handlersCollection = handlersSection.Collection;
var addElement = handlersCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "PHP-FastCGI";
addElement.Properties.Item("path").Value = "*.php";
addElement.Properties.Item("verb").Value = "GET,HEAD,POST";
addElement.Properties.Item("modules").Value = "FastCgiModule";
addElement.Properties.Item("scriptProcessor").Value = "C:\\PHP\\php-cgi.exe";
addElement.Properties.Item("resourceType").Value = "Either";
addElement.Properties.Item("requireAccess").Value = "Script";
handlersCollection.AddElement(addElement, 0);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set fastCgiSection = adminManager.GetAdminSection("system.webServer/fastCgi", "MACHINE/WEBROOT/APPHOST")
Set fastCgiCollection = fastCgiSection.Collection
Set applicationElement = fastCgiCollection.CreateNewElement("application")
applicationElement.Properties.Item("fullPath").Value = "C:\PHP\php-cgi.exe"
applicationElement.Properties.Item("arguments").Value = ""
applicationElement.Properties.Item("maxInstances").Value = 4
applicationElement.Properties.Item("idleTimeout").Value = 300
applicationElement.Properties.Item("activityTimeout").Value = 30
applicationElement.Properties.Item("requestTimeout").Value = 90
applicationElement.Properties.Item("instanceMaxRequests").Value = 10000
applicationElement.Properties.Item("protocol").Value = "NamedPipe"
applicationElement.Properties.Item("queueLength").Value = 1000
applicationElement.Properties.Item("flushNamedPipe").Value = false
applicationElement.Properties.Item("rapidFailsPerMinute").Value = 10

Set environmentVariablesCollection = applicationElement.ChildElements.Item("environmentVariables").Collection
Set environmentVariableElement = environmentVariablesCollection.CreateNewElement("environmentVariable")
environmentVariableElement.Properties.Item("name").Value = "PHP_FCGI_MAX_REQUESTS"
environmentVariableElement.Properties.Item("value").Value = "10000"
environmentVariablesCollection.AddElement(environmentVariableElement)
Call fastCgiCollection.AddElement(applicationElement)

Set handlersSection = adminManager.GetAdminSection("system.webServer/handlers", "MACHINE/WEBROOT/APPHOST")
Set handlersCollection = handlersSection.Collection
Set addElement = handlersCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "PHP-FastCGI"
addElement.Properties.Item("path").Value = "*.php"
addElement.Properties.Item("verb").Value = "GET,HEAD,POST"
addElement.Properties.Item("modules").Value = "FastCgiModule"
addElement.Properties.Item("scriptProcessor").Value = "C:\PHP\php-cgi.exe"
addElement.Properties.Item("resourceType").Value = "Either"
addElement.Properties.Item("requireAccess").Value = "Script"
Call handlersCollection.AddElement(addElement, 0)

adminManager.CommitChanges()

Share via

Environment Variable <environmentVariable>

Compatibility

Setup

Windows Server 2012 or Windows Server 2012 R2

Windows 8 or Windows 8.1

Windows Server 2008 or Windows Server 2008 R2

Windows Vista or Windows 7

How To

How to create a global FastCGI handler mapping for PHP

How to create a FastCGI application for PHP

How add a FastCGI environment variable for PHP

Configuration

Attributes

Child Elements

Configuration Sample

Sample Code

AppCmd.exe

C#

VB.NET

JavaScript

VBScript

Feedback

Additional resources