HttpPlatformHandler Configuration Reference

by IIS Team

This article provides an overview of the HttpPlatformHandler and explains the configuration of the module.

Functionality Overview

The HttpPlatformHandler is an IIS Module, for IIS 8+, which does the following two things:

  1. Process management of http listeners - this could be any process that can listen on a port for http requests. For example - Tomcat, Jetty, Node.exe, Ruby etc;
  2. Proxy requests to the process that it manages.

HttpPlatformHandler Configuration

The HttpPlatformHandler is configured via a site or applications web.config file and has its own configuration section within system.webServer - httpPlatform.

Configuration Attributes

Attribute Description
processPath Required attribute. Path to the executable or script that will launch a process listening for HTTP requests. As of v1.2 relative paths are supported, if the path begins with '.' the path is considered to be relative to the site root. There is no default value
arguments Optional string value. Arguments to the executable or script specified in the processPath setting. There is no default value.
startupTimeLimit Optional integer attribute. Duration in seconds for which HttpPlatformHandler will wait for the executable/script to start a process listening on the port. If this time limit is exceeded, HttpPlatformHandler will kill the process and try to launch it again startupRetryCount times. The default value is 10.
startupRetryCount Optional integer attribute. Number of times HttpPlatformHandler will try to launch the process specified in processPath. See startupTimeLimit for more details. The default value is 10.
rapidFailsPerMinute Optional integer attribute. Specifies the number of times the process specified in processPath is allowed to crash per minute. If this limit is exceeded, HttpPlatformHandler will stop launching the process for the remainder of the minute. The managedPipelineMode attribute can be one of the following possible values. The default is 10.
requestTimeout Optional timespan attribute. Specifies the duration for which HttpPlatformHandler will wait for a response from the process listening on %HTTP_PLATFORM_PORT%. The default value is "00:02:00".
stdoutLogEnabled Optional boolean attribute. If true, stdout and stderr for the process specified in the processPath setting will be redirected to the file specified in stdoutLogFile. The default value is false.
stdoutLogFile Optional string attribute. Specifies the relative OR absolute file path for which stdout and stderr from the process specified in processPath will be logged. Relative paths are relative to the root of the site. As of v1.2 any path starting with '.' will be relative to the site root and all other paths will be treated as absolute paths. The default value is httpplatform-stdout.
processesPerApplication Optional integer attribute. Specifies the number of instances of the process specified in the processPath setting that can be spun up per application. Maximum is 100. The default value is 1.
forwardWindowsAuthToken True or False. New for v1.2. If this setting is set to true, the token will be forwarded to the child process listening on %HTTP_PLATFORM_PORT% as a header 'X-IIS-WindowsAuthToken' per request. It is the responsibility of that process to call CloseHandle on this token per request. The default value is false.

Child Elements

Element Description
environmentVariables Configures environmentVariables collection for the process specified in the processPath setting.
recycleOnFileChange configures file collection which recycles the worker process when changes are made to file in the specified list. Element syntax e.g. <file path=".\touch.txt"/> or <file path="c:\file.txt"/>

HttpPlatformHandler Configuration Examples

Below are configuration examples for running a number of applications with different processes.

Tomcat

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat" 
                  arguments="" 
                  stdoutLogEnabled="true" 
                  stdoutLogFile="\\?c:\dev\javasites\log.txt">
      <environmentVariables>
        <environmentVariable name="JRE_HOME" value="%programfiles%\java\jdk1.8.0_25" />
        <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value"/>
        <environmentVariable name="CATALINA_HOME" value="c:\dev\javasites\bin\apache-tomcat-8.0.15" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

Jetty

<?xml version="1.0"?>
<configuration>
    <system.webServer>
      <handlers>
        <add name="httpplatformhandler" path="*" verb="*" modules ="httpPlatformHandler" resourceType="Unspecified"/>
      </handlers>
      <httpPlatform processPath="c:\Program Files\Java\jdk1.8.0_25\bin\java.exe" 
                    arguments="-Djava.net.preferIPv4Stack=true -Djetty.port=%HTTP_PLATFORM_PORT% -Djetty.base=&quot;c:\dev\javasites\bin\jetty-distribution-9.2.6.v20141205&quot; -jar &quot;c:\dev\javasites\bin\jetty-distribution-9.2.6.v20141205\start.jar&quot;" 
                    startupTimeLimit="20" 
                    startupRetryCount="20" 
                    stdoutLogEnabled="true"></httpPlatform>
    </system.webServer>
</configuration>

Sample Code

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.GetWebConfiguration("JavaSites");
            
            ConfigurationSection httpPlatformSection = config.GetSection("system.webServer/httpPlatform");
            httpPlatformSection["processPath"] = @"c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat";
            httpPlatformSection["arguments"] = @"";
            httpPlatformSection["stdoutLogFile"] = @"=""\\?c:\dev\javasites\log.txt";
            
            ConfigurationElementCollection environmentVariablesCollection = httpPlatformSection.GetCollection("environmentVariables");
            
            ConfigurationElement environmentVariableElement = environmentVariablesCollection.CreateElement("environmentVariable");
            environmentVariableElement["name"] = @"JRE_HOME";
            environmentVariableElement["value"] = @"=""%programfiles%\java\jdk1.8.0_25";
            environmentVariablesCollection.Add(environmentVariableElement);
            
            ConfigurationElement environmentVariableElement1 = environmentVariablesCollection.CreateElement("environmentVariable");
            environmentVariableElement1["name"] = @"CATALINA_OPTS";
            environmentVariableElement1["value"] = @"=""-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value";
            environmentVariablesCollection.Add(environmentVariableElement1);
            
            ConfigurationElement environmentVariableElement2 = environmentVariablesCollection.CreateElement("environmentVariable");
            environmentVariableElement2["name"] = @"CATALINA_HOME";
            environmentVariableElement2["value"] = @"c:\dev\javasites\bin\apache-tomcat-8.0.15";
            environmentVariablesCollection.Add(environmentVariableElement2);
            
            serverManager.CommitChanges();
        }
    }
}

JavaScript

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

var httpPlatformSection = adminManager.GetAdminSection("system.webServer/httpPlatform", "MACHINE/WEBROOT/APPHOST/JavaSites");
httpPlatformSection.Properties.Item("processPath").Value = "c:\\dev\\javasites\\bin\\apache-tomcat-8.0.15\\bin\\startup.bat";
httpPlatformSection.Properties.Item("arguments").Value = "";
httpPlatformSection.Properties.Item("stdoutLogFile").Value = "=\"\\\\?c:\\dev\\javasites\\log.txt";

var environmentVariablesCollection = httpPlatformSection.ChildElements.Item("environmentVariables").Collection;

var environmentVariableElement = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement.Properties.Item("name").Value = "JRE_HOME";
environmentVariableElement.Properties.Item("value").Value = "=\"%programfiles%\\java\\jdk1.8.0_25";
environmentVariablesCollection.AddElement(environmentVariableElement);

var environmentVariableElement1 = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement1.Properties.Item("name").Value = "CATALINA_OPTS";
environmentVariableElement1.Properties.Item("value").Value = "=\"-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value";
environmentVariablesCollection.AddElement(environmentVariableElement1);

var environmentVariableElement2 = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement2.Properties.Item("name").Value = "CATALINA_HOME";
environmentVariableElement2.Properties.Item("value").Value = "c:\\dev\\javasites\\bin\\apache-tomcat-8.0.15";
environmentVariablesCollection.AddElement(environmentVariableElement2);

adminManager.CommitChanges();

Command Line (AppCmd)

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /processPath:"c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat" /arguments:"" /stdoutLogFile:"="""\\?c:\dev\javasites\log.txt"  

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /+"environmentVariables.[name='JRE_HOME',value='="""%programfiles%\java\jdk1.8.0_25']" 

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /+"environmentVariables.[name='CATALINA_OPTS',value='="""-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value']" 

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /+"environmentVariables.[name='CATALINA_HOME',value='c:\dev\javasites\bin\apache-tomcat-8.0.15']"

PowerShell

Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform" -name "processPath" -value "c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat"
Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform" -name "arguments" -value ""
Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform" -name "stdoutLogFile" -value "="""\\?c:\dev\javasites\log.txt"

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform/environmentVariables" -name "." -value @{name='JRE_HOME';value='="""%programfiles%\java\jdk1.8.0_25'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform/environmentVariables" -name "." -value @{name='CATALINA_OPTS';value='="""-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform/environmentVariables" -name "." -value @{name='CATALINA_HOME';value='c:\dev\javasites\bin\apache-tomcat-8.0.15'}