How to install IIS 5.0 debug tools on an Application Center 2000 cluster (837518)


The information in this article applies to:

  • Microsoft Application Center 2000 SP2
  • Microsoft Internet Information Server 5.0

SUMMARY

Microsoft Application Center 2000 replicates IIS settings from the cluster controller to the cluster members. This replication behavior can cause issues with IIS debug tools. This article lists steps to install the IIS debug tools on the cluster controller. The article also describes how to use automatic synchronization from the Application Center 2000 cluster controller to the member servers to set up and configure the debug tools on the members instantaneously.

INTRODUCTION

If a Web application is causing the Internet Information Service to quit unexpectedly (crash) or to stop responding (hang), an IIS support professional may request that you install the IIS debug tools to help troubleshoot the problem. This step-by-step article describes how to install the IIS debug tools on the cluster controller. The article also describes how to use the Application Center 2000 automatic synchronization in the cluster to set up and configure all the cluster members.

Note These steps are written explicitly for the Microsoft Internet Information Server 5.0 product that is included only with Microsoft Windows 2000.

This article assumes that all members of the Application Center 2000 cluster are configured for automatic synchronization. You have to stop and restart the IIS Admin Service on each server.

This article discusses two typical methods that you can use to set up the IIS debug tools:
  • To capture a Web application that stops responding
  • To capture a Web application that quits unexpectedly
The two implementations are similar because they both use the IISCrashHangAgent filter. However, to capture a Web application that quits unexpectedly, you also have to do the following:
  • Perform some special configurations in both IIS and the registry.
  • Attach a debugger from a console session. Avoid attaching the debugger to the IIS processes by using a terminal services session. If you cannot use a console session, the IIS support professional can provide alternatives. However, a console session is the best method to use and is the easiest method to use.

MORE INFORMATION

If IIS stops responding or if IIS quits unexpectedly, you can set up the IIS debug tools to capture the Web application.

This section discusses how to set up the IIS debug tools to capture a Web application that behaves this way on any server in an Application Center 2000 cluster.

Note This article assumes that the %SystemDrive% is the C drive.

How to set up the IIS debug tools to capture a Web application that stops responding (hangs)

  1. Install the IIS debug tools on the cluster controller only.
    1. Install the tools. Accept the default values during the installation.
    2. Do not choose to restart IIS after the installation. You will restart IIS later.
    To download the debug tools, visit the following Microsoft Download Center Web site:

    http://www.microsoft.com/downloads/details.aspx?FamilyID=01c4f89d-cc68-42ba-98d2-0c580437efcf&DisplayLang=en

    After the tools are installed, the files are located in the following folder on the server:

    %SystemDrive%\IISDebugTools

  2. Edit the Internet Server API (ISAPI) filter in the properties of the WWW Service Master.
    1. Open the Application Center 2000 Microsoft Management Console (MMC).
    2. Open Internet Information Services, right-click the server name for the cluster controller, and then click Properties.
    3. Click Edit for the WWW Service Master properties.
    4. On the ISAPI Filters tab, click the filter that is named IISCrashHangAgent, and then click Edit.

      Notice that a red down arrow appears next to the filter. This arrow indicates that the filter is not loaded in memory because you have not restarted the IIS Admin Service yet.
    5. Locate the following executable path:
      \\?\C:\IISDebugTools\IISCHAgent.dll
      Change the previous executable path to the following executable path:
      C:\IISDebugTools\IISCHAgent.dll
    6. Click OK until the master properties dialog box is closed.

      Note This change will limit the path length that the tools can work with. However, this limitation is mitigated if you keep the file paths short in the .ini file that is described in step 8 (the IISchagent.ini file).
  3. Create a virtual directory to the debug tools folder to replicate the files to the other servers.
    1. Right-click the Application Center 2000 administrative site, click New, and then click Virtual Directory. The Virtual Directory Creation Wizard starts.
    2. Click Next, and then type debug in Alias.
    3. Click Next, and then move to the C:\IISDebugTools folder.
    4. Click Next two times, and then click Finish to create the virtual directory.
  4. Use Windows Explorer to create two folders.
    1. Open Windows Explorer on the cluster controller and move to the C:\IISDebugTools folder.
    2. In C:\IISDebugTools, create a folder that is named Logs, and then create a folder that is named History.
  5. Use the Application Center 2000 MMC to exclude from synchronization the folders that you created in the previous step.
    1. In the left pane, expand the cluster name so that you can see Synchronizations.
    2. Right-click Synchronizations, and then click Properties.
    3. Add to the list of exclusions the two new folders that you created earlier: C:\IISDebugTools\Logs and C:\IISDebugTools\History.
  6. Reset the IIS Admin Service on each server in the cluster.
    You can reset the IIS Admin Service on each server without disrupting production. You can do this from the Application Center 2000 Microsoft Management Console (MMC). If you use a third-party load balancing solution instead of network load balancing, set the servers offline by using the load balancer. To do this, follow these steps:
    1. Drain the current connections for an appropriate time for the applications that are running on the Web site.
    2. Set each server offline, one at a time.
    3. After the server is offline, restart the IIS service, and then set the server online again.
    By repeating this process for each server in the cluster, the Web applications will remain available.
  7. Move the IISCrashHangAgent ISAPI to the top of the list.
    1. Open the Application Center 2000 MMC.
    2. Open Internet Information Services, right-click the server name for the cluster controller, and then click Properties.
    3. Click Edit for the WWW Service Master properties.
    4. On the ISAPI Filters tab, click the filter that is named IISCrashHangAgent.

      Notice that a green arrow now indicates that the filter is loaded in memory.
    5. Move the filter to the top of the list. To do so, click the Up button.
    6. Click OK until the master properties dialog box is closed.
  8. Edit the IISchagent.ini file to configure the debug tools to capture a Web application that stops responding.
    1. Open Windows Explorer on the cluster controller and move to the C:\IISDebugTools folder.
    2. Open the IISchagent.ini file in a text editor such as Notepad. Scroll down to the bottom of the file to find the [HangAgent] section.
    3. Modify the file as follows:
      [HangAgent]
Enable=0
LogLocation=c:\iisdebugtools\logs
MaxLogFiles=10
WriteLog=1
RequestTimeLimit=240   
ActionCommand=c:\iisdebugtools\iisdump.exe
MaxActionsAllowed=1
      Note the following:
      • The large dump files will be created in the C:\IISDebugTools\Logs folder. If drive space is limited, the dump files can be redirected to another drive.
      • The value of the RequestTimeLimit parameter is in seconds. Set the value of this parameter to a value that will not cause the debug tools to dump the processes for a typical request that takes longer than the configured time limit. An example of this kind of request is posting lots of data.
    4. Change the ActionCommand parameter to the following:

      actioncommand=c:\iisdebugtools\iisdump.exe -o drive:\path

      For example, use the following command:

      actioncommand=c:\iisdebugtools\iisdump.exe -o d:\dumpfiles

    5. Make sure of the following:
      • The destination folder has been created.
      • The LogLocation entry is not changed and appears exactly as shown in the sample code in step c.
The server is now set up to dump the IIS processes when the application stops responding.

After the server is set up

Continue to work with your IIS support professional to resolve the problem.

How to set up the IIS debug tools to capture a Web application that quits unexpectedly (crashes)

This section discusses files that are obtained only from the IIS support professional who requested that you install the debug tools.

Note This article assumes that the %SystemDrive% is the C drive.
  1. Install the IIS debug tools on the cluster controller only.
    1. Install the tools. Accept the default values during the installation.
    2. Do not choose to restart IIS after the installation. You will restart IIS later.
    To download the debug tools, visit the following Microsoft Download Center Web site:

    http://www.microsoft.com/downloads/details.aspx?FamilyID=01c4f89d-cc68-42ba-98d2-0c580437efcf&DisplayLang=en

    After the tools are installed, the files are located in the following folder on the server:

    %SystemDrive%\IISDebugTools

  2. Edit the Internet Server API (ISAPI) filter in the properties of the WWW Service Master.
    1. Open the Application Center 2000 MMC.
    2. Open Internet Information Services, right-click the server name for the cluster controller, and then click Properties.
    3. Click Edit for the WWW Service Master properties.
    4. On the ISAPI Filters tab, click the filter that is named IISCrashHangAgent, and then click Edit.

      Notice that a red down arrow appears next to the filter. This arrow indicates that the filter is not loaded in memory because you have not restarted the IIS Admin Service yet.
    5. Change the following executable path:
      \\?\C:\IISDebugTools\IISCHAgent.dll
      Change the previous executable path to the following executable path:
      C:\IISDebugTools\IISCHAgent.dll
    6. Click OK until the master properties dialog box is closed.

      Note This change will limit the path length that the tools can work with. However, this limitation is mitigated if you keep the file paths short in the .ini settings. The .ini settings are described earlier in step 8 under the heading "How to set up the IIS debug tools to capture a Web application that stops responding (hangs)."
  3. Create a virtual directory to the debug tools folder to replicate the files to the other servers.
    1. Right-click the Application Center 2000 administrative site, click New, and then click Virtual Directory. The Virtual Directory Creation Wizard starts.
    2. Click Next, and then type debug in Alias.
    3. Click Next, and then move to the C:\IISDebugTools folder.
    4. Click Next two times, and then click Finish to create the virtual directory.
  4. Use Windows Explorer to create two folders.
    1. Open Windows Explorer on the cluster controller and move to the C:\IISDebugTools folder.
    2. In C:\IISDebugTools, create a folder that is named Logs, and then create a folder that is named History.
  5. Use the Application Center 2000 MMC to exclude from synchronization the folders that you created in the previous step.
    1. In the left pane, expand the cluster name so that you can see Synchronizations.
    2. Right-click Synchronizations, and then click Properties.
    3. Add to the list of exclusions the two new folders that you created earlier: C:\IISDebugTools\Logs and C:\IISDebugTools\History.
  6. Disable the FailFast registry entry.
    The IIS support professional who sent you instructions to set up the servers for the crash dump files will have included some registry files. You will use these registry files to disable the FailFast registry entry. Just double-click the registry file that is named Win2k_DisableFailFast.reg to add these settings to the registry.

    Note Use this registry file only after all troubleshooting is completed.
  7. Turn off the Debug Exception Catching option.
    To make sure that IIS is passing the exception to the debugger correctly, turn off this option in the properties of the Web service. To do so, follow these steps:
    1. Open the IIS MMC.
    2. Right-click the computer name in the left pane, and then click Properties.
    3. Click the Edit button for the WWW Service Master properties.
    4. On the Home Directory tab, click the Configuration button.
    5. On the Process Options tab, clear the Enable Debug Exception Catching check box, and then click OK to close the properties dialog box.
  8. Turn on the Leave Running When Idle option.
    Important Make sure that the processes that are hosting COM+ components do not shut down by themselves because of inactivity. This shutdown would trigger a false crash dump file.
    1. Open Component Services. To do so, click Start, click Control Panel, open Administrative Tools, and then double-click Component Services.
    2. In the left pane, expand the following series of nodes: Component Services, Computers, My Computer, and COM+Applications
    3. For each custom package or Web site or Web directory that is running in Medium or High isolation, follow these steps:
      • Right-click the item, and then click Properties.
      • On the Advanced tab, select the Leave Running when Idle check box, and then click OK.
  9. Reset the IIS Admin Service on each server in the cluster.
    You can reset the IIS Admin Service on each server without disrupting production. You can do this from the Application Center 2000 MMC. If you use a third-party load balancing solution instead of network load balancing, set the servers offline by using the load balancer. To do this, follow these steps:
    1. Drain the current connections for an appropriate time for the applications that are running on the Web site.
    2. Set each server offline, one at a time.
    3. After the server is offline, restart the IIS service , and then set the server online again.
    By repeating this process for each server in the cluster, the Web applications will remain available.
  10. Move the IISCrashHangAgent ISAPI to the top of the list.
    1. Open the Application Center 2000 MMC.
    2. Open Internet Information Services, right-click the server name for the cluster controller, and then click Properties.
    3. Click Edit for the WWW Service Master properties.
    4. On the ISAPI Filters tab, click the filter that is named IISCrashHangAgent.

      Notice that a green arrow now indicates that the filter is loaded in memory.
    5. Move the filter to the top of the list. To do so, click the Up button.
    6. Click OK buttons until the master properties dialog box is closed.
  11. Attach the debugger to the IIS processes.
    Perform this step from a console session that is running on the server. You can use pcAnywhere. However, avoid using a terminal services session.
    1. Open a command prompt, and then change directory to the C:\IISDebugTools directory.
    2. Run the following command:

      iisdump.exe -i

The server is now set up to dump the IIS processes when the application quits unexpectedly.

After the server is set up

Continue to work with your IIS support professional to resolve the problem.

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, regarding the performance or reliability of these products.

REFERENCES

For additional information about errors that may occur after you install the IIS debug tools, click the following article number to view the article in the Microsoft Knowledge Base:

837517 Errors occur after you install the IIS debug tools in Application Center 2000

Modification Type:MinorLast Reviewed:8/12/2004
Keywords:kbhowto KB837518 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.