Customizing IIS 6.0’s Custom Error Pages

This is geared for IIS 6 but the same ideas apply to IIS 7.x

By default, IIS 6 websites have a standard set of static custom error pages to return to clients.

These htm files are found on Windows 2003 web servers at c:\windows\help\iishelp\common.

These htm files can be modified with notepad, an html editor, or replaced with other htm pages of the same name.

Global level or Site Level?

The first decision that must be made is whether all sites should use the same custom error pages or if individual websites need to use different custom error pages.

By default all websites are set to use these custom error pages. By default the setting to use these custom error pages is set at the global (or root level) of IIS and this setting is inherited by all the websites. If all of your websites can and should use the same custom error page, you can just modify the files at c:\windows\help\iishelp\common. If each website needs its own custom error page, you should create separate folders for each website either at c:\windows\help\iishelp\common\{WebsiteName} or c:\inetpub\wwwroot\{WebsiteName} or in some other folder that has NTFS permissions for IIS_WPG and other accounts needed for IIS to gain access.

In this scenario, I am going to create a new folder in wwwroot, copy all the pages from common into it, and give them further customization.

Static or Dynamic?

There is an option to use a dynamic page (.asp or .aspx) as your custom error page but it is prudent to stick with htm pages. If the web server suffered some injury (like a corruption of a .net framework or a mismatch of dlls in the inetsrv folder) it is not unlikely that the client would not be served the error page. The likelihood of IIS serving a custom error page if it is a static htm/html page is higher.

Editing

I open the 400.htm page with an html editor (in this case it is Microsoft Web Expressions 3) and I replace most of the information by with this generic template:

Oops!

We just ran into a problem when trying to log you into the portal.

If this is the first time you have seen this error please close your browser and try again.

If the problem persists please notify the help desk by emailing helpdesk@domain.xyz.

If the issue is critical please call helpdesk at (xxx)xxx-xxxx.

Please be ready to provide the help desk technician with the following information:

1. · Error message: {insert error message here}

2. · The address you were browsing to when the error was encountered

3. · Server name = WEB204 {<<change server name here}

4. · The time you saw the error message

We appreciate your patience and understanding as we work to get this solved.

Additional details about this error:

{add optional details here to help the helpdesk tech solve this problem}

Before editing, the 400.htm page appears like this in the browser:

After editing, the 400.htm page looks like this in the client browser:

The template may be good for most of the http response codes. However, there may be good reasons to deviate from the template in certain exceptions. For the 403-4.htm (“Forbidden: SSL is required to view this resource”) page and the similar 403-5.htm page (“Forbidden: SSL 128 is required to view this resource) it may be better to communicate something like the following to help the end user solve their own problem without involving helpdesk.

Oops!

We just ran into a problem when trying to log you into the portal.

This site requires SSL. Please ensure you have entered https rather than http in the address bar and try browsing to the page again.

Access to this site requires your CAC to be registered with {supply name of department or organization here}.

To register your CAC please click the following link:

...(insert hyperlink here)...

For further assistance please email the helpdesk at helpdesk@domain.xyz.

If the issue is a critical please phone the helpdesk at (xxx)xxx-xxxx.

Please be ready to provide the help desk technician with the following information:

1. Error message: {insert error message here}

2. The address you were browsing to when the error was encountered

3. Server name = WEB204 {<<change server name here}

4. The time you saw the error message

We appreciate your patience and understanding as we work to get this solved.

Configuring the Website to use the New Custom Error Page

Assuming you need to make changes at the site level rather than the global level, and assuming your edited custom error pages sit in a different folder than the default custom error pages, here are steps for repointing a website to the new custom error page.

In the IIS manager, right-click on the website and select Properties from the menu.

Select the “Custom Errors” tab, highlight one page at a time (in this scenario the 400.htm page) and click the Edit button.

Click the BROWSE button.

Proceed to browse to the location of the improved 400.htm page.

Select the 400.htm page and click the Open button.

Click OK

Confirm that the reconfiguration looks right and click OK.

From this point on, IIS will send the updated 400.htm to the client if the client sends IIS a poorly formed request.

Exceptions

There are a few errors that could be presented to the client which custom IIS pages cannot affect. The 503 “Service Unavailable” error, for example, is sent to the client by http.sys rather than IIS and cannot be customized.

Another example could be that if an SSL certificate was corrupted or missing and used on an IIS website, the client browser may reach the website fine with http but may get a vague “Internet Explorer cannot display the web page…” error when browsing to https.

There is also a chance that ASP.net or SharePoint may have custom error handling that could potentially supersede the use of some of the custom error pages by IIS. If this proves to be a problem, one possibility would be to edit the web.config file to include redirects.

Example:

</customErrors>

Additional Information

If you prefer to give additional details about each error in the custom error page you can read more about each http error message and get clues on how to solve for these errors at these links:

http://support.microsoft.com/default.aspx?scid=kb;EN-US;943891

943891 The HTTP status codes in IIS 7.0

http://msdn.microsoft.com/en-us/library/ms525983(VS.90).aspx

IIS Custom HTTP Error Messages

And for the 401 error page you could, for example, include links for helpful kb articles.

907273 Troubleshooting HTTP 401 errors in IIS

http://support.microsoft.com/default.aspx?scid=kb;EN-US;907273

871179 You receive an "HTTP Error 401.1 - Unauthorized: Access is denied due to invalid credentials" error message when you try to access a Web site that is part of an IIS 6.0 application pool

http://support.microsoft.com/default.aspx?scid=kb;EN-US;871179

This type of information would be for the sake of helping the helpdesk or server administrators rather than the end user. The friendly information for the end user could be placed at the top of the custom error page and the detailed information could be placed at the bottom of the custom error page in a way that doesn’t distract the end user.