Home > Guardian Error Handling System > Help > 1000

How to enable custom error messages on Microsoft IIS

This document describes how to configure the Microsoft IIS web server so that it will redirect common server errors - like 404 Not Found or 500 Internal Server Error - to a Perl CGI script for processing. Applies to IIS 4.0 and newer.

In order to configure IIS, you must:

  1. Be an Administrator of the web server (or a member of the Web Site Operators group)

  2. Have access to an IIS admin interface. The most common interface is the Microsoft Management Console, from an interactive session on the web server itself. That approach will be described here.

If you are mere IIS user without administrator privileges and/or without physical access to the computer, you will have to ask your administrator to take these steps on your behalf.

Follow these steps to add a custom error page to IIS:

  1. Before you tweak IIS, first make an initial request to your custom error page using its direct URL. Make sure it displays properly. If your error page is a Perl CGI script or ASP file, and it is failing, then it will be very difficult to debug what is going on when other errors are redirected to it.

  2. Also before you begin, request a file from your website that doesn't exist, like www.foo.com/no_such_file. Observe the 404 Not Found error handling: do you see a plaintext file like "404 Not Found"? Or do you see a pretty error message that someone else has already customized, perhaps one specific to your web hosting company? Or are you redirected to a special file, like www.foo.com/404.html? You need to know what the baseline behavior is so that you can evaluate the behavior later after you start tweaking things.

  3. Use the Microsoft Management Console to open the Internet Information Services snap-in. On Windows 2000, you can select the My Computer icon, right-click, and choose "Manage".

    First view of the Internet Information Services snap-in

  4. Select your web site, right-click, and choose Properties:

    Web site properties dialog

  5. From the Properties window, select the "Custom Errors" tab:

    Custom Errors tab of the Web site properties

  6. From the "Custom Errors" tab, scroll through the error codes to find the ones you are interested in. Interesting errors include: "401 Authorization Required", "403 Permission Denied", and "404 Not Found":

    Selecting the 404 Error

  7. Choose "Edit Properties" for the error code you wish to customize. Select "Message Type: URL" and enter the path, from the root document, to your Perl CGI script:

    Customizing the 404 error mapping

  8. Next, choose "Okay" / "Apply" to activate your changes. It is not necessary to restart the web service.

  9. Finally, test the change by requesting a file that does not exist. Note that IIS will internally redirect to the Perl CGI handler, rather than returning a "302 Moved" response to client. The client will only see the output of the script. The internal request it makes to your Perl CGI handler will include a query string of the format "?ErrorCode;ErrorURL". In the example below, the internal query string "404;http://local.xav.com/no_such_file" is used (which our Perl script uses to customize the TITLE):

    Testing the error handler from the command line

Other Resources

Visit the Discussion Forum if you want help installing Guardian, or configuring IIS to use it as an error handler.

See also:


    "How to enable custom error messages on Microsoft IIS"
    http://www.xav.com/scripts/guardian/help/1000.html