<processModel> Element

  • 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 running on the server.

**CAUTION   **Read the Remarks section for this element.

<configuration>
   <system.web>
      <processModel>

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

Optional Attributes

Attribute Option Description
clientConnectedCheck     Specifies how long a request is left in the queue before ASP.NET does a client connected check.
comAuthenticationLevel     Specifies the level of authentication for DCOM security. The default is Connect.
    Default Specifies that DCOM determines the authentication level using its normal security negotiation algorithm.
    None Specifies no authentication.
    Connect Specifies that DCOM authenticates the credentials of the client only when the client establishes a relationship with the server.
    Call Specifies that DCOM authenticates the credentials of the client when the server receives the request at the beginning of each remote procedure call.
    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 transferred between the client and the server has been modified.
    PktPrivacy Specifies that DCOM authenticates all previous levels and encrypts the argument value of each remote procedure call.
comImpersonationLevel     Specifies the authentication level for COM security.
    Default Specifies that DCOM determines the impersonation level using its normal security negotiation algorithm.
    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 version 1.1.
    Identify Specifies that the server can obtain the client's identity. 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 client's security context 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.
    Delegate Specifies that the server process can impersonate the client's security context 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 client's security context on other computers to access local and remote resources as the client. When impersonating at this level, the impersonation token can be passed across any number of machine boundaries.
cpuMask     Specifies which processors on a multiprocessor server are eligible to run ASP.NET processes. The cpuMask value specifies a bit pattern that indicates the CPUs eligible 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 eligible CPU. If the webGarden attribute (see below) is set to true, the cpuMask limits worker processes to the number of eligible CPUs. (The maximum allowed number of worker processes is equal to the number of CPUs.) By default, all CPUs are enabled and ASP.NET launches one process for each CPU. If webGarden is set to false, the cpuMask attribute is ignored and only one worker process will run.
enable     Specifies whether the process model is enabled.
    true Indicates that the process model is enabled.
    false Indicates that the process model is not enabled.
idleTimeout     Specifies the period of inactivity, in hr:min:sec string format, after which ASP.NET automatically ends the worker process. The default is Infinite.
logLevel     Specifies event types to be logged to the event log.
    All Specifies that all process events are logged.
    None Specifies that no events are logged.
    Errors Specifies that only unexpected shutdowns, memory limit shutdowns, and deadlock shutdowns are logged. Errors is the default.
maxWorkerThreads 5 to 100 Configures the maximum amount of worker threads to be used 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 default is 20. The value of maxWorkerThreads must be equal to or greater than the minFreeThread attribute setting in the <httpRuntime> configuration section.
maxIoThreads 5 to 100 Configures the maximum number of I/O threads to be used 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 default is 20. The value of maxIoThreads must be equal to or greater than the minFreeThread attribute setting in the <httpRuntime> configuration section.
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 percent.
password     If present (and in conjunction with a userName), this attribute causes the worker process to run with the configured Windows identity. The default value is AutoGenerate. See userName for more details on the special names System and Machine, which do not require a password, and for information about storing encrypted worker process credentials in the registry.
pingFrequency     Specifies the time interval, in standard process model format (hr:min:sec), at which the ISAPI extension pings the worker process to see if it is running. If it is not running for the pingTimeout interval, the worker process is restarted. The default is 30 seconds.
pingTimeout     Specifies the time interval, in standard process model format (hr:min:sec), after which a nonresponsive worker process 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 5 seconds.
requestLimit     Specifies the number of requests 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 allowed in the queue before ASP.NET begins returning "503 – Server Too Busy" errors to new requests. The default is 5000.
responseDeadlockInterval     Specifies the time interval, in standard process model format (hr:min:sec), after which the process will be restarted if the following conditions are met:
  • There are queued requests.
  • There has not been a response during this interval.

The default is 3 minutes.
responseRestartDeadlockInterval     This attribute is no longer used by ASP.NET and is provided for backward 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.
serverErrorMessageFile     If present, specifies the contents of a file to use instead of the default "Server Unavailable" message in the event of a fatal error. The file location is relative to Machine.config or can be an absolute file path. If this attribute is not present, the default "Server Unavailable" message will be used.
shutdownTimeout     Specifies the number of minutes allowed for the worker process to shut itself down. When the timeout expires, ASP.NET shuts down the worker process. The time is expressed in hr:min:sec string format. The default is 5 seconds, or 0:00:05.
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     If present, the userName attribute runs the ASP.NET worker process with a Windows identity different from that of the default process identity. By default, userName is set to the special value 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 the userName and password attributes, the process is run with the given account. One other special value for userName is System, with the password AutoGenerate, which runs the process as an administrative account and allows all ASP.NET user code running under the process to have full administrative privileges. See the Remarks section below for information about using ASP.NET on a server that is a domain controller.

userName and password are stored in clear text in the configuration file. Although IIS will not transmit .config files in response to a user agent request, configuration files can be read by other means, for instance by an authenticated user with proper credentials on the domain that contains 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 encrypted by the Windows 2000 and Windows XP Data Protection API (DPAPI) encryption functions. For more information, see the Remarks and Example sections below.
webGarden     Controls CPU affinity when used in conjunction with the cpuMask attribute. (A multiprocessor Web server is called a Web garden).
    true Indicates that the cpuMask attribute is used to specify which CPUs are eligible 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 will run. The default is false.

Remarks

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

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. On Windows 2000 domain controller servers, ASP.NET applications run under the IWAM_machinename identity. On Windows 2003 domain controller servers, 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 properly. For more information about potential problems running version 1.1 on a domain controller, see article Q824308, "IWAM Account is Not Granted the Impersonate Privilege for ASP.NET 1.1 on Windows 2000 Domain Controller with SP4," in the Microsoft Knowledge Base at https://support.microsoft.com. For more information about running version 1.0 of the .NET Framework on a domain controller, see article Q315158, "ASP.NET Does Not Work with the Default ASPNET Account on a Domain Controller," in the Microsoft Knowledge Base at https://support.microsoft.com.

When ASP.NET is running under IIS version 6 in native mode, the IIS 6 process model is used and the settings in the <processModel> section are ignored. To configure the process identity, cycling, or other process model values, use the Internet Services Manager user interface to configure the IIS worker process for your application.

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 equivalent 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, w3wp.exe on Windows Server 2003 family) to restart with an error message indicating that the restart was due to a suspected deadlock state, you should increase the responseDeadlockInterval setting.

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 as follows.

   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 will read 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 the current account creation failure code path will be followed.

The credentials must be in REG_BINARY format, containing the output of a call to the Windows API function CryptProtectData. You can create the encrypted credentials and store them in the registry with the ASP.NET Set Registry console application (Aspnet_setreg.exe), which uses CryptProtectData to accomplish the encryption. To download Aspnet_setreg.exe, along with the Visual C++ source code and documentation, visit the Web site www.asp.net and search for "aspnet_setreg".

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

Administrators:F

SYSTEM:F

CREATOR OWNER:F

ProcessAccount: R

This provides two lines of defense to help protect the data:

  • The ACL permissions require the identity accessing the data to be an Administrator.
  • An attacker must run code on the server (CryptUnprotectData) to recover the credentials for the account.

Examples

The following example specifies several <processModel> configuration settings.

<configuration>
   <system.web>
      <processModel 
         enable="true"
         timeout="15" 
         idleTimeout="25"
         shutdownTimeout="5"
         requestLimit="1000"
         requestQueueLimit="500"
         responseDeadlockInterval="00:03:00"              
         responseRestartDeadlockInterval="Infinite"
         memoryLimit="20"
         webGarden="true"
         maxWorkerThreads="25"
         maxIoThreads="25"/>
   </system.web>
</configuration>

The following example specifies that the encrypted username and password are stored in the registry under the user-defined key AspNetProcess.

<configuration>
   <system.web>
      <processModel> 
         userName="registry:HKLM\Software\AspNetProcess,Name"
         password="registry:HKLM\Software\AspNetProcess,Pwd"
      </processModel>
   </system.web>
</configuration>

Requirements

Contained Within: <system.web>

Web Platform: IIS 5.0, IIS 5.1, IIS 6.0

Configuration File: Machine.config

Configuration Section Handler: System.Web.Configuration.ProcessModelConfigurationHandler

See Also

ASP.NET Configuration | ASP.NET Settings Schema