Troubleshooting 101: Diagnostics in IIS 7.0 • Chapter 17 857 Table 17.2 Continued Attribute Name Value Replace When an error message is generated (e.g., 404, File not Found), IIS will take over the error and call the appropriate custom error page or URL. PassThrough When an error message is generated (e.g., 404, File not Found), IIS will not call out to the custom page but will allow the error to be handled by a module. For example, when calling a page that doesn’t exist and has an extension of .aspx, which results in a 404 File not Found error, the error response will be created by ASP.NET and not IIS. So in this case, the custom page or detailed page, as defi ned in the web.confi g, will not be generated. SOME INDEPENDENT ADVICE For a site or application to leverage an error page that’s in a different application pool than its own, the following registry change will need to be made. Keep in mind that this is a serverwide change and could open the attack surface on a Web server that is “hosting” a number of different Web sites. Note: It is recommended that you back up your registry before modifying the registry with the new data. If you use Registry Editor (Regedit.exe) incorrectly, you could cause serious problems that might require you to reinstall your operating system. 1. Open Regedit.exe (you can quickly fi nd this using Windows Vista search by clicking the Windows button and typing in RegEdit). 2. Navigate to the following key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC. 3. Within the W3SVC key, create a new DWORD called IgnoreAppPoolForCustomErrors and with a value of 1. 4. For this change to take effect, you’ll need to restart IIS 7.0. The <httpErrors> node defi nes the base values for all the child <error> nodes (see Table 17.2). The child nodes for <httpErrors> are <error>, <remove>, and <clear>. The <error> node defi nes a set of properties for a given error code. As you can see, each error code is then mapped to a specifi c fi le, which then provides appropriate error response. A number of options are available by error code, including handling suberror codes. Table 17.3 provides details on the available attributes that can be used as part of the <error> XML node. 858 Chapter 17 • Troubleshooting 101: Diagnostics in IIS 7.0 Within a given error code, additional suberror codes provide an even greater amount of detail. The following XML node can be added to the <httpErrors> node to handle a suberror code: <error statusCode=“404” subStatusCode=14 prefi xLanguageFilePath=“%SystemDrive%\ inetpub\custerr” path=“404-14.htm” /> This XML looks much like the previous XML, except it uses a new XML attribute, subStatusCode, which takes an integer and is the suberror code. Thus, the preceding XML is capturing the 404.14 statusCode and is then being redirected to the 404-14.htm fi le. If an error code is raised and it’s actually a suberror code, but no subStatusCode is defi ned in the <httpErrors> XML, the “parent” statusCode will be used. The following URL points to a Microsoft Support page that provides a general list and description of Error Codes used by IIS 6.0 and 7.0: http://support.microsoft.com/kb/318380 The prefi xLanguageFilePath attribute provides a pointer to a folder that holds additional folders with the language-specifi c error pages. For example, the default error code pages are located at =“%SystemDrive%\inetpub\custerr and contain a child folder named en-US. The en-US folder contains all of the individual error pages, such as 404-14.htm. The syntax (folder name) and acceptable languages that can be used here are defi ned in RFC 1766 (www.ietf.org/rfc/rfc1766.txt). Overriding for a Site Until now, we’ve focused mainly on confi guring the errors page and behavior at the server level. As stated earlier, error confi guration can be delegated down to the site and application/virtual directory level. This gives a Web site administrator and Web developer a greater amount of control than in the past, to defi ne and manage how errors are handled for their site. The following is a simple web.confi g fi le that overrides the default behavior when a fi le isn’t found (404 error): Table 17.3 <error> XML Node Attributes and Values Attribute Name Value Type Value statusCode String Primary status code for a given error. subStatusCode Integer Substatus code for a given error that is a “child” of a high-level code. prefi xLanguageFilePath String Location of language-specifi c error code folders. Path String Actual fi lename for the given page that will be used to provide the error message to the user. responseMode String Defi nes the type of response that will be given. This will also treat the value in Path a bit differently. This is the same as Path Type as defi ned in the IIS Manager. Troubleshooting 101: Diagnostics in IIS 7.0 • Chapter 17 859 <confi guration> <system.webServer> <httpErrors errorMode=“Custom”> <remove statusCode=“404” subStatusCode=“-1” /> <error statusCode=“404” prefi xLanguageFilePath=“” path=“http://agramont.net/” responseMode=“Redirect” /> </httpErrors> </system.webServer> </confi guration> You’ll notice that there are two XML nodes within the <httpErrors> node. Before you can add an error node that overrides a previously defi ned node, such as the default error nodes, you must fi rst remove it using the <remove> node. Only then can you add the <remove> node that redefi nes that setting. When the preceding XML code is defi ned in the web.confi g, you’ll see the information shown in Figure 17.5 represented in the IIS Manager. Figure 17.5 HTTP Errors 860 Chapter 17 • Troubleshooting 101: Diagnostics in IIS 7.0 The IIS Manager provides a list of all the error pages defi ned for this given site. This also includes an aggregated view of the inherited and explicit (defi ned as “Local” in the Entry Type column) error pages and their associated values. Understanding and Reading Custom Error Messages in IIS 7.0 In IIS 7.0, the data shared in custom errors is more robust than ever. IIS 7.0 offers detailed information about the request information itself as well as reasons that the failure might have occurred. In an unprecedented feature never available in custom errors in previous versions, step-by-step instructions provide information on how to further troubleshoot or fi x the error. It is important to understand how to read the information IIS provides as well as how to further your research if the recommended steps don’t resolve your problem. The detailed error provides a wealth of information that can help a Web administrator or developer quickly narrow down the root cause of a given error. There are a number of helpful pieces of information on the Detailed Error page. Although the Error Code value provides the actual error code that was raised, it’s only one piece of the puzzle. The other properties listed here provide additional context to the request that generated the error: ■ Description A user-friendly description of the error. ■ Error Code The actual error code. ■ Notifi cation Event handler within the Module (see next bullet) that generated the error. ■ Module A pointer to the module that generated the error. ■ Requested URL The URL that was used by the end user. This will also include any information in the query string as well. ■ Physical Path A pointer to the actual physical path of the page that generated the error. This could be an ASP, ASPX, or even HTML page. This is useful if a user was trying to browse a given page (e.g., cart.aspx) and then was redirected to a different page that generated the actual error (e.g., newcart.aspx). ■ Logon User The username that was used by IIS 7.0 and Windows in performing the request. ■ Logon Method Defi nes the type of authentication method that was used as part of this request. For most public sites, this will be set to Anonymous. ■ Failed Request Tracing Log Directory A pointer to the directory that will hold the trace fi le for this error. This doesn’t tell you the actual fi lename, which is a good thing from a security perspective. ■ Handler The Handler within IIS 7.0 that raised the error. ■ Most likely causes IIS 7.0 provides a list of pointers for each status code that can help you troubleshoot the issue or at least give you an idea of where to look next. ■ What you can try This fi eld provides some helpful troubleshooting tasks that the developer or administrator can perform. Troubleshooting 101: Diagnostics in IIS 7.0 • Chapter 17 861 ■ More Information This fi eld provides yet another set of ideas on what the issue might be and how you could resolve it. What’s interesting is that by clicking the “More Information” link, you’ll be routed to a Microsoft support article that will provide—yes, you guessed it—more information. Delegating Custom Errors This detailed error data doesn’t have security in mind, hence they aren’t sent to any clients other than requests started at the IIS server console. However, in some situations, it is useful to have some of the custom errors delegated to clients other than the just the console. This section outlines ways you can carefully delegate custom errors and the security risks associated with doing so. Controlling custom errors is, by default, a server-specifi c setting and can only be controlled by the Web server administrator. The great thing about IIS 7 is that it provides the ability to allow a Web site administrator or developer to control their own custom errors. To do this, you fi rst must allow the ability to “override” the default settings that are defi ned in the applicationHost.confi g XML fi le. Within the applicationHost.confi g fi le, you must make a change to the following XML node and change the overrideModeDefault from Deny to Allow: <section name=“httpErrors” overrideModeDefault=“Deny” /> NOTE Although shown here directly changing the XML confi guration fi les, you can also do this in IIS Manager by clicking Feature Delegation (Under Management Area) | Error Pages and changing to Read\Write. If you neglect to make this change before proceeding to the next set of steps, you’ll get an “HTTP Error 500.19—Internal Server Error” error message from IIS that proceeds to tell you that overrideModeDefault needs to be changed. Making a change to the Custom Errors properties using IIS Manager for a virtual directory named Chapter06 within the Default Web Site will result in the following XML being stored within the applicationHost.confi g fi le: <location path=“Default Web Site/Chapter06”> <system.webServer> <httpErrors> <remove statusCode=“500” subStatusCode=“−1” /> <error statusCode=“500” prefi xLanguageFilePath=“” path=“D:\\ web\Chapter06\ Error.aspx” responseMode=“File” /> </httpErrors> </system.webServer> </location> . includes an aggregated view of the inherited and explicit (defi ned as “Local” in the Entry Type column) error pages and their associated values. Understanding and Reading Custom Error Messages in. page and behavior at the server level. As stated earlier, error confi guration can be delegated down to the site and application/virtual directory level. This gives a Web site administrator and. takes an integer and is the suberror code. Thus, the preceding XML is capturing the 404.14 statusCode and is then being redirected to the 404-14.htm fi le. If an error code is raised and it’s actually