IIS Technical Notes

Important:

InterSystems recommends using the Web Gateway, which is an updated and more feature-rich version of the CSP Gateway. The Web Gateway is compatible with Caché and Ensemble starting with version 2017.1. For more information, read the Web Gateway GuideOpens in a new tab in the latest InterSystems IRIS® documentation.

For those interested who use IIS, this appendix describes application pools, web gardens, and bitness.

IIS Application Pools and Web Gardens

With IIS Version 6, Microsoft further improved the scalability and resilience of the overall web server environment.

IIS Version 6 delivers web hosting services through an adjustable architecture that can be used to manage server resources with improved stability, efficiency, and performance. IIS separates applications into isolated pools of processes and automatically detects memory leaks, defective processes, and overutilized resources. When problems occur, IIS manages them by shutting down and redeploying faulty resources and connecting faulty processes to analytical tools.

IIS Version 6 can run in either of two mutually exclusive modes of operation:

Worker process isolation mode. This is the default mode of IIS 6.0. It isolates key components of the World Wide Web Publishing Service (WWW service) from the effects of errant applications, and protects applications from each other by using the worker process architecture. Microsoft recommends that worker process isolation mode should be used unless there is a specific compatibility issue that makes the use of IIS 5 isolation mode necessary. Web sites that serve static content, simple ASP applications and CSP applications should be able to move to IIS 6.0 running in worker process isolation mode.
IIS 5.0 isolation mode. With this mode, it is possible to run applications that are incompatible with worker process isolation mode because they were developed specifically for earlier versions of IIS. Applications that run correctly on IIS 5.0 should run correctly on IIS 6.0 in IIS 5.0 isolation mode. It is not necessary to use this mode for CSP applications.

Worker process isolation mode provides better default security for running web applications than IIS 5.0 isolation mode. By default, worker processes run with the Network Service identity. The Network Service account has lower access rights than the default account for IIS 5.0 isolation mode. web applications that run in-process in IIS 5.0 application mode run as Local System. The Local System account can read, execute, and change most of the resources on the computer.

Application Pools

An application pool is a configuration that links one or more applications to a set of one or more worker processes. Because applications in an application pool are separated from other applications by worker process boundaries, an application in one application pool is not affected by problems caused by applications running in other application pools.

By creating new application pools and assigning Web sites and applications to them, it is possible to make the server more efficient and reliable. Applications working through pools are always available, even when a worker process serving a different application develops a fault.

Applications are defined by their path in IIS. For example: /csp

Web Gardens

For even greater reliability, it is possible to configure an application pool to be supported by multiple worker processes. An application pool that uses more than one worker processes is called a web garden. The worker processes in a web garden share the requests that arrive for that particular application pool. If a worker process fails, another worker process can continue to process other requests.

It should be noted that web gardens are different from web farms. A web garden is configured on a single server by specifying multiple worker processes for an application pool. web farms use multiple servers for supporting a web site.

Creating a web garden for an application pool can enhance performance in the following situations:

Robust processing of requests: When a worker process in an application pool is tied up (for example, when a script engine stops responding), other worker processes can accept and process requests for the application pool.
Reduced contention for resources: When a web garden reaches a steady state, each new TCP/IP connection is assigned, according to a round-robin scheme, to a worker process in the web garden. This helps smooth out workloads and reduce contention for resources that are bound to a worker process.

Application Pools, Web Gardens, and CSP

Application Pool and Web Garden configurations do not affect the operation of NSD-based Gateway configurations because the ISAPI module communicating with the NSD does not pool any persistent information or other resources (such as connections to Caché). All persistent resources are held in the NSD module. The ISAPI module communicating with the NSD is unaffected by changes in the way it is managed by IIS.

The non-NSD based Gateway configuration (CSPms.dll and CSPmsSys.dll) is more sensitive to changes in the way ISAPI extensions are managed in IIS because the pooling of persistent resources (such as connections to Caché) takes place in the extension itself.

Application pools that are configured to use no more than one worker process have no visible impact on the way the Gateway operates within the context of a single web application path (for example, /csp). However, for configurations where multiple worker processes are used (a Web Garden) the workload for the CSP Gateway is evenly distributed amongst all participating worker processes in the pool. Each worker process manages its own instance of the CSP Gateway modules. This process management architecture does not pose a problem with respect to the way the Gateway operates but the following restrictions must be borne in mind:

IIS must be restarted in order for changes to the Gateway’s configuration to take effect. This must be done by completely restarting the World Wide Web Publishing service from the main Windows Services control panel; not through the Internet Services Manager control panel.
The Gateway’s Systems Management form (System Status) cannot be used to accurately monitor the connections used by CSP applications. At any given time the Systems Status reflects the status for the instance of the Gateway that happens to be attached to the current worker process (that is, the worker process that happens to service the Gateway’s request).
Each CSP application (as defined by the web path to the application) maintains its own pool of persistent connections to Caché. Also, each worker process within an application pool maintains its own pool of persistent connections to Caché. This gearing should be remembered when configuring the maximum and minimum number of connections to Caché that the Gateway uses. These settings apply to each and every Gateway instance in the pool.
State-aware sessions (preserve mode 1) cannot be used with Web Garden configurations because there is no control over the instance of the Gateway which is used to serve any particular request. The net result is that it’s not possible to route state-aware requests to their dedicated Caché processes in these configurations.

It is envisaged that some of these restrictions will be completely or partially lifted in future versions of the CSP Gateway. However, it should be remembered that the NSD-based options are not subject to these restrictions because the Gateway is managed independently of IIS.

Finally, the affect of certain worker process configuration parameters on the non-NSD version of the Gateway should be considered. In particular, the effect of the idle timeout and process recycling facility should be borne in mind.

Idle Timeout for Worker Processes

Often it is necessary to conserve system resources by terminating unused worker processes. It is possible to configure a worker process to gracefully close after a specified period of time. This feature can be used to better manage the resources when the processing load is heavy, when identified applications consistently fall into an idle state, or when new processing space is not available.

When a worker process is terminated, the instance of the Gateway that it manages also close and the pool of connections to Caché held by that Gateway instance is terminated. Of course, additional stateless connections can always be replaced in a way that is transparent to users of a CSP application but state-aware sessions (preserve mode 1) terminate when their hosting connection is closed.

Recycling Worker Processes

IIS can be configured to periodically restart worker processes, so that faulty web applications can be recycled. This facility helps to ensure that application pools remain healthy and that any leaked system resources are recovered.

It is possible to configure worker processes to restart based on elapsed time, number of requests served, scheduled times and on the basis of memory usage.

The effect on the CSP Gateway of closing worker processes was discussed in the previous section (Idle Timeout). The same considerations apply here. Because CSP applications can only interact with the CSP Gateway through carefully managed channels, it is recommended that worker processes supporting the CSP applications should not be recycled.

Bitness — 32-bit Apps on 64-bit Servers for Windows

Note:

This section applies to modules that are loaded into the address space of the hosting web serve: ISAPI Extensions and Native Modules (CSPms[Sys].dll and CSPcms.dll). CGI modules are not affected since they run as a detached process with respect to IIS.

With 64 bit Windows 2003 installations, IIS 6.0 could be configured to either run in 32 bit mode or 64 bit mode. The Enable32bitAppOnWin64 metabase key could be toggled and all worker process would run in the selected bitness mode. This setting applied to the whole IIS installation (that is, it was globally applied to all Application Pools managed by the server).

With IIS 7.0, the Enable32bitAppOnWin64 setting has been moved down to the Application Pool level. Therefore it is now possible to set the bitness for a particular Application Pool. In other words, it is possible, within a single server installation, to configure one Application Pool to run native 64-bit applications and another to run 32-bit applications.

To access the bitness setting for an Application Pool, enter the IIS control panel:

Select Application Pools in the left hand panel.
Select the appropriate Application Pool.
Select Advanced Settings in the right hand panel.
The Advanced Settings dialogue appears. The Enable 32-Bit Applications setting is found in the General section. This can be set to True or False.

Incidentally, this configuration setting can be manipulated at the Windows Command line using the appcmd command. For example:

appcmd set apppool /apppool.name:DefaultAppPool/enable32bitapponwin64:true

This sets the Application Pool DefaultAppPool to run in 32 bit mode.

It is also possible to list the Application Pools based on bitness using the appcmd command. For example, to list all the application pools running in 64 bit mode use the following command:

appcmd list apppools /enable32bitapponwin64:false

Finally, since application pools can be run in different bitness modes it is necessary to ensure that Native Modules (and ISAPI extensions) that are loaded by the Application Pool are themselves of the correct bitness for the pool. For example, if the hosting application pool is 64-bit then the 64-bit Gateway modules (such as CSPms[Sys].dll) must be used. If the hosting Application Pool is 32-bit then the 32-bit Gateway modules must be used instead.

The bitness check for individual modules is done via a preCondition in the module’s web.config file. For the CSP Gateway, this file typically looks something like the following:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="CSPGateway_All" path="*" verb="*" modules="CSPms" resourceType="Unspecified" \
             preCondition="bitness64" />
        </handlers>
        <security>
            <requestFiltering>
                <hiddenSegments>
                    <remove segment="bin" />
                </hiddenSegments>
            </requestFiltering>
        </security>
    </system.webServer>
</configuration>

Note the bitness setting in the precondition clause. In this case bitness is set to bitness64 which means that IIS checks for 64-bit Gateway modules operating in a 64-bit Application Pool.

If a 32-bit Application Pool is used then the 32-bit Gateway modules must be used and the preCondition set to bitness32.

If there is an inconsistency between the modules installed, the precondition clause, and/or the expectations of the hosting Application Pool, IIS returns an error condition similar to the one shown below.

Error:
The module(s) assigned to this handler mapping has the following preconditions that are not
present in the handler mapping:
bitness64
Runtime errors may occur if a handler mapping does not have a set of preconditions that are
equally as restrictive as, or more restrictive, than the module(s) assigned to the mapping.
Please ensure that this handler mapping has the correct preconditions, and that the 
preconditions are not in conflict.