Share via

processModel Element (ASP.NET Settings Schema)

  • Article

Configures the ASP.NET process model settings on a Microsoft Internet Information Services (IIS) Web server. The processModel section can be set only within the Machine.config file and affects all ASP.NET applications that are running on the server.

Warning

Changes to the processModel element take effect only when the worker process is restarted—not immediately after the setting is changed, as with other configuration elements. For more information, see "Remarks," later in this topic.

<processModel 
   enable="true|false"
   timeout="hrs:mins:secs|Infinite" 
   idleTimeout="hrs:mins:secs|Infinite"
   shutdownTimeout="hrs:mins:secs|Infinite"
   requestLimit="num|Infinite"
   requestQueueLimit="num|Infinite"
   restartQueueLimit="num|Infinite"
   memoryLimit="percent"
   webGarden="true|false"
   cpuMask="num"
   userName="username"
   password="password"
   logLevel="All|None|Errors"
   clientConnectedCheck="hrs:mins:secs|Infinite"
   comAuthenticationLevel="Default|None|Connect|Call| 
               Pkt|PktIntegrity|PktPrivacy"
   comImpersonationLevel="Default|Anonymous|Identify|
               Impersonate|Delegate"
   responseDeadlockInterval="hrs:mins:secs|Infinite"
   responseRestartDeadlockInterval="hrs:mins:secs|Infinite"
   autoConfig="true|false"
   maxWorkerThreads="num"
   maxIoThreads="num"
   minWorkerThreads="num"
   minIoThreads="num"
   serverErrorMessageFile="" 
   pingFrequency="Infinite" 
   pingTimeout="Infinite" 
   maxAppDomains="2000"
/>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute Description

autoConfig

Specifies whether to automatically configure the following settings to achieve optimal performance based on the machine configuration:

The values are set according to the KB article at https://support.microsoft.com/?id=821268.

This attribute does not affect the .NET Framework client applications; only ASP.NET applications.

The autoConfig attribute can be one of the following values.

Term Definition

True

Indicates that ASP.NET automatically configures the attributes in the preceding list to achieve optimal performance based on the machine configuration.

False

Indicates that ASP.NET should use the explicitly defined values for the attributes in the preceding list.

The default in the Machine.config file is True, unless there is a previously existing configuration.

clientConnectedCheck

Specifies how long a request is left in the queue before ASP.NET does a check to determine whether the client is connected.

The default is "00:00:05" (5 seconds).

comAuthenticationLevel

Specifies the level of authentication for DCOM security.

The comAuthenticationLevel attribute can be one of the following values.

Value Description

Call

Specifies that DCOM authenticates the credentials of the client when the server receives the request at the beginning of each remote procedure call.

Connect

Specifies that DCOM authenticates the credentials of the client only when the client establishes a connection to the server.

Default

Specifies that DCOM determines the authentication level using its standard security negotiation algorithm.

None

Specifies no authentication.

Pkt

Specifies that DCOM authenticates that all data received is from the expected client. Datagram transports always use Pkt authentication.

PktIntegrity

Specifies that DCOM authenticates and verifies that none of the data that is transferred between the client and the server is modified.

PktPrivacy

Specifies that DCOM authenticates all previous levels and encrypts the argument value of each remote procedure call.

The default is Connect.

comImpersonationLevel

Specifies the authentication level for COM security.

The comImpersonationLevel attribute can be one of the following values.

Value Description

Anonymous

Specifies that the client is anonymous to the server. The server can impersonate the client, but the impersonation token will not contain any information. Anonymous is not supported in the .NET Framework version 1.1.

Default

Specifies that DCOM determines the impersonation level using its standard security negotiation algorithm.

Delegate

Specifies that the server process can impersonate the security context for the client while acting on behalf of the client. The server process can also make outgoing calls to other servers while acting on behalf of the client, using cloaking. The server can use the security context for the client on other computers to gain access to local and remote resources as the client. When impersonating at this level, the impersonation token can be passed across any number of machine boundaries.

Identify

Specifies that the server can obtain the identity for the client. The server can impersonate the client for access control list (ACL) checking, but it cannot access system objects as the client.

Impersonate

Specifies that the server process can impersonate the security context for the client while acting on behalf of the client. This level of impersonation can be used to access local resources, such as files. When impersonating at this level, the impersonation token can be passed across only one machine boundary.

The default is Impersonate.

cpuMask

Specifies which processors (CPUs) on a multiprocessor server are qualified to run ASP.NET processes. This value specifies a bit pattern that indicates the CPUs that are qualified to run ASP.NET threads. For example, the cpuMask hexadecimal value 0x0d represents the bit pattern 1101. On a computer with four CPUs, this indicates that ASP.NET processes can be scheduled on CPUs 0, 2, and 3, but not on CPU 1. ASP.NET launches one worker process for each qualified CPU. If the webGarden attribute is true, this attribute limits worker processes to the number of qualified CPUs. The maximum for worker processes is equal to the number of CPUs. If webGarden is false, this attribute is ignored and only one worker process will run. This is the default behavior.

The default is "0xffffffff".

enable

Specifies whether the process model is enabled.

The enable attribute can be one of the following values.

Value Description

True

Indicates that the process model is enabled.

False

Indicates that the process model is not enabled.

The default is true.

idleTimeout

Specifies the period of inactivity, in the string format hr:min:sec, after which ASP.NET automatically ends the worker process.

The default is Infinite.

logLevel

Specifies event types to log to the event log.

The logLevel attribute can be one of the following values.

Value Description

All

Specifies that all process events are logged.

Errors

Specifies that only unexpected shutdowns, memory limit shutdowns, and deadlock shutdowns are logged.

None

Specifies that no events are logged.

The default is Errors.

maxAppDomains

Specifies the maximum number of application domains that are allowed in one process.

This attribute can be less than or equal to 2000.

The default is 2000.

maxIoThreads

Configures the maximum number of I/O threads to use for the process on a per-CPU basis. For example, if this value is 25 on a single-processor server, ASP.NET uses the runtime APIs to set the process limit to 25. On a two-processor server, the limit is set to 50. The value of this attribute must be equal to or greater than the minFreeThread attribute setting in the httpRuntime configuration section.

For information about threading types, see "Threading Explained" in Improving ASP.NET Performance.

The range for this attribute is from 5 through 100.

The default is 20.

maxWorkerThreads

Configures the maximum amount of worker threads to use for the process on a per-CPU basis. For example, if this value is 25 on a single-processor server, ASP.NET uses the runtime APIs to set the process limit to 25. On a two-processor server, the limit is set to 50. The value of this attribute must be equal to or greater than the minFreeThread attribute setting in the httpRuntime configuration section.

For information about threading types, see "Threading Explained" in Improving ASP.NET Performance.

The range for this attribute is from 5 through 100.

The default is 20.

memoryLimit

Specifies the maximum allowed memory size, as a percentage of total system memory, that the worker process can consume before ASP.NET launches a new process and reassigns existing requests.

The default is 60.

minIoThreads

Configures the minimum number of I/O threads to use for the process on a per-CPU basis. Also see maxIoThreads.

For information about threading types, see "Threading Explained" in Improving ASP.NET Performance.

The default is 1.

minWorkerThreads

Configures the maximum amount of worker threads to use for the process on a per-CPU basis. Also see maxWorkerThreads.

For information about threading types, "Threading Explained" in Improving ASP.NET Performance.

The default is 1.

password

Causes, if present (and in conjunction with a userName), the worker process to run with the configured Microsoft Windows identity. See userName for more information about the special names System and Machine, which do not require a password, and for information about storing encrypted worker process credentials in the registry.

The default is AutoGenerate.

pingFrequency

Specifies the time interval, in standard process model format (hr:min:sec), at which the ISAPI extension pings the worker process to determine whether it is running. If it is not running for the pingTimeout interval, the worker process is restarted.

The default is Infinite.

pingTimeout

Specifies the time interval, in standard process model format (hr:min:sec), after which a responsive worker process that is not responding is restarted. The ISAPI extensions ping the worker process at the pingFrequency interval. If the worker process does not respond within the pingTimeout interval, the process is restarted.

The default is Infinite.

requestLimit

Specifies the number of requests that are allowed before ASP.NET automatically launches a new worker process to take the place of the current one.

The default is Infinite.

requestQueueLimit

Specifies the number of requests that are allowed in the queue before ASP.NET begins returning the message "503 – Server Too Busy" to new requests.

The default is 5000.

responseDeadlockInterval

Specifies the time interval, in standard process model format (hr:min:sec), after which the process is restarted, if the following conditions are met:

  • There are queued requests.

  • There has not been a response during this interval.

The default is "0:03:00" (3 minutes).

responseRestartDeadlockInterval

This attribute is no longer used by ASP.NET and is provided for compatibility only. It will not cause a configuration error, if it is already present in a configuration file. All recycling in the event of a deadlock condition is now controlled by the responseDeadlockInterval attribute.

The default is "0:03:00" (3 minutes).

restartQueueLimit

Specifies the maximum number of requests that are queued while waiting for the worker process to restart after a nonstandard termination. This setting does not apply in the case of a clean shutdown or standard restart.

The default is 10.

serverErrorMessageFile

Specifies the contents of a file to use instead of the default message "Server Unavailable" in the event of a fatal error. The file location is relative to the Machine.config file or it can be an absolute path. If this attribute is not present, the default message "Server Unavailable" is used.

shutdownTimeout

Specifies the number of minutes that are allowed for the worker process to shut down. When the time-out expires, ASP.NET shuts down the worker process. The time is expressed in hr:min:sec string format.

The default is "0:00:05" (5 seconds).

timeout

Specifies the number of minutes until ASP.NET launches a new worker process to take the place of the current one.

The default is Infinite.

userName

Specifies that ASP.NET will run the worker process with a Windows identity that is different from the Windows identity for the default process identity. By default, this attribute is set to the Machine, and the process runs under a user account named ASPNET that is created automatically when ASP.NET is installed. The password for the ASPNET account is cryptographically generated at the time of installation. If valid credentials are presented in this attribute and the password attribute, the process is run with the given account. One other value for userName is System, with the password AutoGenerate, which runs the process as an administrative account and allows all ASP.NET user code that is running under the process to have full administrative privileges. See "Remarks," later in this topic for information about using ASP.NET on a server that is a domain controller.

This attribute and the password attribute are stored in clear text in the configuration file. Although Microsoft Internet Information Services (IIS) do not transmit .config files in response to a user agent request, configuration files can be read by other means. For example, a configuration file can be read by an authenticated user with proper credentials on the domain for the server. For security reasons, the processModel section supports storage of encrypted userName and password attributes in the registry. The credentials must be in REG_BINARY format and encrypted by the Windows 2000 and Windows XP Data Protection API (DPAPI) encryption functions. For more information, see "Remarks" and "Example," later in this topic.

The default is "machine".

webGarden

Controls CPU affinity when used in conjunction with the cpuMask attribute. (A multiprocessor Web server is called a Web garden).

The webGarden attribute can be one of the following values.

Value Description

True

Indicates that the cpuMask attribute is used to specify which CPUs are qualified to run ASP.NET processes.

False

Indicates that CPU usage is scheduled by the Windows operating system. The cpuMask attribute is ignored and only one worker process is run.

The default is False.

Child Elements

None.

Parent Elements

Element Description

system.web

Specifies the root element for the ASP.NET configuration section and contains configuration elements that configure ASP.NET Web applications and control how the applications behave.

Remarks

The managed code configuration system does not read the processModel configuration settings. Instead, the processModel configuration settings are read directly by the aspnet_isapi.dll unmanaged DLL. Changes to this section are not applied until the IIS worker process is restarted.

When ASP.NET is running under IIS version 6 in native mode, the IIS 6 process model is used and some attributes in the processModel section are ignored. However, the following attributes still apply:

  • autoConfig

  • maxIoThreads

  • maxWorkerThreads

  • minIoThreads

  • minWorkerThreads

  • requestQueueLimit

  • responseDeadlockInterval

To configure the process identity, cycling, or other process model values in IIS 6.0, use the Internet Services Manager user interface to configure the IIS worker process for your application.

Note

ASP.NET 2.0 cannot be used when you configure IIS 6 to run ASP.NET in IIS 5.0 isolation mode.

Time values are in the form "hours:minutes:seconds". If a single number with no colons is given, the value is assumed to be minutes; thus timeout="4" is equal to timeout="00:04:00".

If an ASP.NET application is causing the ASP.NET worker process (aspnet_wp.exe on Windows 2000 and Windows XP Professional and w3wp.exe on Windows Server 2003) to restart with an error message indicating that the restart was due to a suspected deadlock state, you should increase the responseDeadlockInterval attribute.

Domain Controllers and the Local ASPNET Account

If you install the .NET Framework version 1.1 on a domain controller, the installation does not create the local ASPNET account. Instead, ASP.NET applications run under other identities, as follows:

  • On domain controllers that are running Windows 2000 Server, ASP.NET applications run under the identity IWAM_machinename.

  • On domain controllers running Windows Server 2003, ASP.NET applications run under the NETWORK SERVICE identity, regardless of the IIS isolation mode.

Under some circumstances, running ASP.NET on a domain controller requires that you take extra steps to make the installation work correctly. For more information about running the .NET Framework version 1.1 on a domain controller, go to the Knowledge Base (KB) search page and see article Q824308, "IWAM Account is Not Granted the Impersonate Privilege for ASP.NET 1.1 on Windows 2000 Domain Controller with SP4." For more information about running the .NET Framework version 1.0 on a domain controller, go to the Knowledge Base (KB) search page and see article Q315158, "ASP.NET Does Not Work with the Default ASPNET Account on a Domain Controller."

Storing a User Name and Password in the Registry

To encrypt the user name and password and store them in the registry, set the userName and password attributes as shown in the following example.

   userName="registry:HKLM\Software\AspNetProcess,Name"
   password="registry:HKLM\Software\AspNetProcess,Pwd"

The portion of the string after the keyword registry and before the comma (,) indicates the name of the registry key that ASP.NET opens. The portion after the comma (,) contains a single string value name from which ASP.NET reads the credentials. The comma (,) is required and the credentials must be stored in the HKLM hive. If the configuration format is incorrect, ASP.NET will not launch the worker process and will follow the current account creation failure code path.

The credentials must be in REG_BINARY format, containing the output of a call to the Windows API function CryptProtectData. You can use Aspnet_setreg.exe to create the encrypted credentials and store them in the registry. Aspnet_setreg.exe uses CryptProtectData to accomplish the encryption. To download Aspnet_setreg.exe, along with the Microsoft Visual C++ source code and documentation, go to the ASP.NET Web site and search for "aspnet_setreg".

You should configure access to the key that is storing the encrypted credentials so that access is provided only to Administrators and SYSTEM. Because the key is read by the ASP.NET process running as SYSTEM, set the following permissions:

Administrators:F
SYSTEM:F
CREATOR OWNER:F 
ProcessAccount: R

This helps protect the data in the following ways:

  • The ACL permissions require that the identity that is accessing the data is Administrator.

  • An attacker must run code on the server (CryptUnprotectData) to recover the credentials for the account.

Default Configuration

The following default processModel element is not explicitly configured in the Machine.config file or in the root Web.config file. However, it is the default configuration that is returned by application.

<processModel 
   enable="true" 
   timeout="Infinite" 
   idleTimeout="Infinite" 
   shutdownTimeout="00:00:05" 
   requestLimit="Infinite" 
   requestQueueLimit="5000" 
   restartQueueLimit="10" 
   memoryLimit="60" 
   webGarden="false" 
   cpuMask="0xffffffff" 
   userName="machine" 
   password="AutoGenerate" 
   logLevel="Errors" 
   clientConnectedCheck="00:00:05" 
   comAuthenticationLevel="Connect" 
   comImpersonationLevel="Impersonate" 
   responseDeadlockInterval="00:03:00" 
   responseRestartDeadlockInterval="00:03:00" 
   autoConfig="true" 
   maxWorkerThreads="20" 
   maxIoThreads="20" 
   minWorkerThreads="1" 
   minIoThreads="1" 
   serverErrorMessageFile="" 
   pingFrequency="Infinite" 
   pingTimeout="Infinite" 
   asyncOption="20" 
   maxAppDomains="2000" 
/>

The following default processModel element is configured in the Machine.config file in the .NET Framework versions 1.0 and 1.1.

<processModel
   enable="true"
   timeout="Infinite"
   idleTimeout="Infinite"
   shutdownTimeout="0:00:05" 
   requestLimit="Infinite" 
   requestQueueLimit="5000" 
   restartQueueLimit="10"
   memoryLimit="60" 
   webGarden="false"
   cpuMask="0xffffffff"
   userName="machine"
   password="AutoGenerate"
   logLevel="Errors"
   clientConnectedCheck="0:00:05"
   comAuthenticationLevel="Connect"
   comImpersonationLevel="Impersonate"
   responseRestartDeadlockInterval="00:09:00"
   responseDeadlockInterval="00:03:00" 
   <!-- In the .NET Framework version 1.1, the next two attributes are
        set to 20. -->
   maxWorkerThreads="25"
   maxIoThreads="25"
        />

Element Information

Configuration section handler

ProcessModelSection

Configuration member

ProcessModel

Configurable locations

Machine.config

Requirements

Microsoft Internet Information Services (IIS) version 5.0, 5.1, or 6.0

The .NET Framework version 1.0, 1.1, or 2.0

Microsoft Visual Studio 2003 or Visual Studio 2005

See Also

Tasks

How to: Configure Specific Directories Using Location Settings
How to: Lock ASP.NET Configuration Settings

Reference

system.web Element (ASP.NET Settings Schema)
configuration Element (General Settings Schema)
System.Configuration
System.Web.Configuration
ProcessModel
ProcessModelSection

Concepts

Configuring ASP.NET Process Identity
ASP.NET Configuration File Hierarchy and Inheritance
Securing ASP.NET Configuration
ASP.NET Configuration Scenarios

Other Resources

General Configuration Settings (ASP.NET)
ASP.NET Configuration Settings
Configuring ASP.NET Applications
ASP.NET Configuration Files
ASP.NET Configuration API
Improving ASP.NET Performance