Thursday, May 10, 2012

YAML configuration support in iisnode

Upon popular demand for YAML configuration (or rather lack of demand for angle brackets of web.config), iisnode v0.1.20 adds support for specifying configuration options in a YAML file. This allows you to use an established, user-friendly format to control most aspects of hosting node.js applications in IIS on Windows using iisnode.


You can use iisnode.yml file to control several configuration options for iisnode. For a full and current list with a description see here.

# The optional iisnode.yml file provides overrides of 
# the iisnode configuration settings specified in web.config.

node_env: production
nodeProcessCommandLine: "c:\program files\nodejs\node.exe"
interceptor: "c:\program files\iisnode\interceptor.js"
nodeProcessCountPerApplication: 1
maxConcurrentRequestsPerProcess: 1024
maxNamedPipeConnectionRetry: 24
namedPipeConnectionRetryDelay: 250
maxNamedPipeConnectionPoolSize: 512
maxNamedPipePooledConnectionAge: 30000
asyncCompletionThreadCount: 0
initialRequestBufferSize: 4096
maxRequestBufferSize: 65536
watchedFiles: *.js;iisnode.yml
uncFileChangesPollingInterval: 5000
gracefulShutdownTimeout: 60000
loggingEnabled: true
logDirectory: iisnode
debuggingEnabled: true
debuggerPortRange: 5058-6058
debuggerPathSegment: debug
maxLogFileSizeInKB: 128
maxTotalLogFileSizeInKB: 1024
maxLogFiles: 20
devErrorsEnabled: true
flushResponse: false
enableXFF: false

The iisnode.yml configuration file is not a replacement of web.config: both can exist at the same time. However, if iisnode.yml is present, its settings override the values specified in the system.webServer\iisnode section of web.config.


By default, when the iisnode.yml configuration file changes, iisnode will gracefully recycle the node.js application. Active requests will be allowed to finish, but all new requests will be handled by a newly created node.js process that uses new configuration values.

So why do I still need web.config?

Even if you use iisnode.yml file to configure your node.js application running in iisnode, you still need to include a web.config file. Since IIS is a hosting environment that supports a vast (and extensible) variety of content types running side by side (static files, ASP.NET apps, PHP, node.js , …), web.config is a mechanism to tell IIS that your node.js entry point (e.g. server.js) should be handled by iisnode. In addition, web.config provides the full control over how IIS behaves and can add unique value to your node.js application as explained below.

The good news is that in majority of situations you can use a boilerplate web.config below and never come back to it, relying solely on iisnode.yml for configuration of node.js applications running in IIS.

<?xml version="1.0" encoding="utf-8"?>
<add name="iisnode" path="server.js" verb="*" modules="iisnode"/>
<rule name="LogFile" patternSyntax="ECMAScript" stopProcessing="true">
<match url="iisnode"/>
<rule name="NodeInspector" patternSyntax="ECMAScript" stopProcessing="true">
<match url="^server.js\/debug[\/]?" />
<rule name="StaticContent">
<action type="Rewrite" url="public{{REQUEST_URI}}"/>
<rule name="DynamicContent">
<add input="{{REQUEST_FILENAME}}" matchType="IsFile" negate="True"/>
<action type="Rewrite" url="server.js"/>

The web.config above has the following effect:

  1. It specifies server.js as the entry point to your node.js application.
  2. It redirects all requests for URLs that map to physical files in the “public” subdirectory to an IIS static file handler. Using IIS static file handler has a large performance benefit compared to serving static content from within a node.js application. The handler leverages IIS and OS low level caching mechanisms which offer superb performance.
  3. It allows IIS to serve the log files that capture output of a node.js application as static files such that you can access them over HTTP. By default, if your server.js entry point is reached at, the log files would be accessible at
  4. It exposes the built-in node-inspector debugger at Learn more about debugging with iisnode.
  5. It sends all other HTTP requests to be processed by your node.js application in server.js.

Try it out

Get your copy if iisnode at and give YAML config a try!

1 comment:

  1. Thanks. That boilerplate web.config is great. It would be nice if that were on the home page or in your installation instructions. The example web.configs that are installed in the www directory are much more basic.


My Photo
My name is Tomasz Janczuk. I am currently working on my own venture - Mobile Chapters ( Formerly at Microsoft (12 years), focusing on node.js, JavaScript, Windows Azure, and .NET Framework.