20.5 Appliance Error Messages

The appliance lets you specify a language for the error messages it sends to browsers. This section explains appliance error message support and provides instructions on how to modify error message text and create support for additional languages.

The appliance provides error messages to browsers through a set of language-specific directories, each of which contains two files.

When you select a language in the browser-based management tool, you are actually selecting one of these language-specific directories and the files it contains.

The two files the appliance uses are:

The language-specific directories that contain these two files are located in \etc\proxy\data\errpage\nls\language, where language is the English name of the language.

For example, the English files are stored in \etc\proxy\data\errpage\nls\english.

Other common appliance error message directories include:

You can specify the language for error page vending in Configure > Mini Web.

20.5.1 Checking the Language Directories on Your Appliance

To see a list of the directories on your appliance:

  1. In the browser-based management tool, click Configure > Mini Web, then open the drop-down list.

20.5.2 Customizing the Appliance Error Template and Message Files

You can create error message support for additional languages and customize existing error message text and format, as described in the following topics:

Creating a New Language

  1. Start FTP and log in as explained in Starting an FTP Session with the Appliance.

  2. Enter the following:

    get /etc/proxy/data/errpage/nls/english/pxyerr.htm

    get /etc/proxy/data/errpage/nls/english/message.cfg

  3. Modify the message.cfg file.

    There are explicit instructions in the file that clearly indicate which parts can be translated.

    The http status messages contain a number at the beginning of the Translated Message. You should not modify the number followed by a space at the beginning of the message. Anything after the space can be modified.

    You cannot delete or add error messages, nor can you change the number or order of the messages.

    IMPORTANT:When customizing the messages, do not use a semi-colon (;) in the message. If you do, the message truncates at the semi-colon and only the portion of the message before the semi-colon is displayed.

  4. Modify the pxyerr.htm file.

    Because this is an HTML file, you can customize it in a variety of ways. To interface with the appliance’s message delivery mechanisms, you must ensure the following:

    • The keywords <PROXY_ADDRESS>, <ERROR_STATUS>, and <ERROR_DESCRIPTION> must be retained because they are dynamically replaced with the information that their names imply.

    • Graphics that you add should be put in the sys:\etc\proxy\data directory. References to these graphics must use the <PROXY_ADDRESS> keyword as a starting reference point. See the usage of alertbar.gif in the pxyerr.htm file.

  5. Save the file when modifications are complete.

  6. Using FTP, create a new language directory in the path given in Section 20.5, Appliance Error Messages.

  7. Enter the following, where language is the new language directory you created:

    put pxyerr.htm /etc/proxy/data/errpage/nls/language/message.cfg

    put pxyerr.htm /etc/proxy/data/errpage/nls/language/pxyerr.htm

The new language is dynamically available in the browser-based management tool and from the command line. You do not need to restart the appliance.

Customizing the Error Message Text of an Existing Language

Referring to the procedure in Creating a New Language for details, complete the following basic steps:

  1. Open the message.cfg file from an existing language-specific directory.

  2. Modify the file.

    IMPORTANT:There are limitations on what you can change in this file. See Creating a New Language for details.

  3. Save the file when modifications are completed.

Customizing the Error Message Format of an Existing Language

Refer to the procedure in Creating a New Language for details, then complete the following basic steps:

  1. Open the pxyerr.htm file from an existing language-specific directory.

  2. Modify the file.

    IMPORTANT:There are limitations on what you can change in this file. See Creating a New Language for details.

  3. Save the file when modifications are completed.

Certificate Error Handling

Currently if accelerators have mutual authentication (this can include mutual and other authentication) enabled, when users present bad certificates (expired or revoked) to access these accelerators, the browsers display a “page not found” error. The certificate error handling feature enables administrators to configure the error messages so that they define what the problem is with a particular certificate. For example, if a certificate is expired, the administrator can configure an error message to let the user know that the certificate has expired. This feature helps administrators more effectively troubleshoot certificate problems. It also helps the user better understand why certificates might not be working.

NOTE:If users use mutual authentication or other authentication, and they cancel a certificate or have a bad certificate, the authentication fails at mutual authentication and they are not prompted for other authentication. If you turn on the certificate error handling feature, the system prompts you for other authentication. There is no error page for failure of mutual authentication.

Using Certificate Error Handling

To use the certificate error handling feature, you must go to the Authentication page and select the Send an Error Page When a Mutual-SSL Certificate Error Occurs option, then select the language from the drop-down list (see Figure 20-1).

NOTE:The certificate error handling feature applies to all accelerators. After this feature is enabled or disabled, you must restart the iChain server. Also, if you change the error messages or error pages, the iChain server must be restarted.

Figure 20-1 Certificate Error Handling

Customizing Error Messages

There are two error message files, message.cfg (message file) and crfterrpg.htm (error page). These files are located at sys:\etc\proxy\data\errpage\nls\english.

The message.cfg file is for error status and description in the cererrpg.htm.

There are 60 certificate messages (101 to 160) in the message.cfg file. You can change the content after Translated Message=. For messages 109 and 113, uses must keep %d for error code.

The messages are paired for status and description fields in the error page. For example, message 111 (status) and message 112 (description) are shown here:

[Message 11]
Message ID=LOC_MSG_CERT_NOT_YET_STATUS
English Message=Certificate Not Valid Yet
Translated Message=Certificate Not Valid Yet

[Message 12]
Message ID=LOC_MSG_CERT_NOT_YET_DESC
English Message=Your certificate's start date is in the future. Please try later or contact your system administrator.
Translated Message=Your certificate's start date is in the future. Please try later or contact your system administrator.

When customized, message 111 (status) and 112 (description) might look like this:

[Message 11]
Message ID=LOC_MSG_CERT_NOT_YET_STATUS
English Message=Certificate Not Valid Yet
Translated Message=Certificate Not For Now

[Message 12]
Message ID=LOC_MSG_CERT_NOT_YET_DESC
English Message=Your certificate's start date is in the future. Please try later or contact your system administrator.
Translated Message=Your certificate is not for now. Please try later.

NOTE:Only the content following Translated Message= is changed.

Customizing the Error Page

To customize an error page, change the static messages in the crterrpg.htm. Users can redesign their own pages as long as they use the crterrpg.htm as the file name and they have <ERROR_STATUS> and <ERROR_DESCRIPTION> fields in the HTML page.

Localizing Error Messages

The current default language is English; however, you can translate error messages and the error page into other languages.

To localize error messages:

  1. After modifying the MESSAGE.CFG file, make sure you save it in UTF-8 format.

  2. Translate the content of the Translated Message for every message (messages 101 to 160). The *_STATUS and *_DESC messages in the message.cfg file are used to replace the <ERROR_STATUS> and <ERROR_DESCPTION> fields in the crterrpg.htm file.

Localizing Error Pages

To localize an error page, translate the static messages in the CRTERRPG.HTM. Users can redesign their own pages as long as they use the CRTERRPG.HTM as the file name and they have <ERROR_STATUS> and <ERROR_DESCRIPTION> fields in the HTML page.