Product Documentation

Imports

December 10, 2018

Several App Firewall features make use of external files that you upload to the App Firewall when configuring it. Using the GUI, you manage those files in the Imports pane, which has four tabs corresponding to the four types of files you can import: HTML error objects, XML error objects, XML schemas, and Web Services Description Language (WSDL) files. Using the NetScaler command line, you can import these types of files, but you cannot export them.

HTML error object

When a user’s connection to an HTML or Web 2.0 page is blocked, or a user asks for a non-existent HTML or Web 2.0 page, the App Firewall sends an HTML-based error response to the user’s browser. When configuring which error response the App Firewall should use, you have two choices:

  • You can configure a redirect URL, which can be hosted on any Web server to which users also have access. For example, if you have a custom error page on your Web server, 404.html, you can configure the App Firewall to redirect users to that page when a connection is blocked.
  • You can configure an HTML error object, which is an HTML-based Web page that is hosted on the App Firewall itself. If you choose this option, you must upload the HTML error object to the App Firewall. You do that in the Imports pane, on the HTML Error Object tab.

The error object must be a standard HTML file that contains no non-HTML syntax except for App Firewall error object customization variables. It cannot contain any CGI scripts, server-parsed code, or PHP code. The customization variables enable you to embed troubleshooting information in the error object that the user receives when a request is blocked. While most requests that the App Firewall blocks are illegitimate, even a properly configured App Firewall can occasionally block legitimate requests, especially when you first deploy it or after you make significant changes to your protected Web sites. By embedding information in the error page, you provide the user with the information that he or she needs to give to the technical support person so that any issues can be fixed.

The App Firewall error page customization variables are:

  • ${NS_TRANSACTION_ID}. The transaction ID that the App Firewall assigned to this transaction.
  • ${NS_APPFW_SESSION_ID}. The App Firewall session ID.
  • ${NS_APPFW_VIOLATION_CATEGORY}. The specific App Firewall security check or rule that was violated.

  • ${NS_APPFW_VIOLATION_LOG}. The detailed error message associated with the violation.

  • ${COOKIE The contents of the specified cookie. For <CookieName>, substitute the name of the specific cookie that you want to display on the error page. If you have multiple cookies whose contents you want to display for troubleshooting, you can use multiple instances of this customization variable, each with the appropriate cookie name. Note: If you have blocking enabled for the Cookie Consistency Check, any blocked cookies are not displayed on the error page because the App Firewall blocks them.

To use these variables, you embed them in the HTML or XML of the error page object as if they were an ordinary text string. When the error object is displayed to the user, for each customization variable the App Firewall substitutes the information to which the variable refers. An example HTML error page that uses custom variables is shown below.

<!doctype html public "-//w3c//dtd html 4.0//en">  <html>  <head>  <title>Page Not Accessible</title>  </head>  <body>  <h1>Page Not Accessible</h1>  <p>The page that you accessed is not available. You can:</p>  <ul>  <li>return to the <b><a href="[homePage]">home page</a></b>, re-establish your session, and try again, or,</li>  <li>report this incident to the help desk via <b><a href="mailto:[helpDeskEmailAddress]">email</a></b> or by calling [helpDeskPhoneNumber].</li>  </ul>  <p>If you contact the help desk, please provide the following information:</p>  <table cellpadding=8 width=80%>  <tr><th align="right" width=30%>Transaction ID:</th><td align="left" valign="top" width=70%>${NS_TRANSACTION_ID}</td></tr>  <tr><th align="right" width=30%>Session ID:</th><td align="left" valign="top" width=70%>${NS_APPFW_SESSION_ID}</td></tr>  <tr><th align="right" width=30%>Violation Category:</th><td align="left" valign="top" width=70%>${NS_APPFW_VIOLATION_CATEGORY}</td></tr>  <tr><th align="right" width=30%>Violation Log:</th><td align="left" valign="top" width=70%>${NS_APPFW_VIOLATION_LOG}</td></tr>  <tr><th align="right" width=30%>Cookie Name:</th><td align="left" valign="top" width=70%>${COOKIE("[cookieName]")}</td></tr>  </table>  <body>  <html>

To use this error page, copy it into a text or HTML editor. Substitute the appropriate local information for the following variables, which are enclosed in square brackets to distinguish them from the NetScaler variables. (Leave those unchanged.):

  • [homePage]. The URL for your web site’s home page.
  • [helpDeskEmailAddress]. The email address that you want users to use to report blocking incidents.
  • [helpDeskPhoneNumber]. The phone number that you want users to call to report blocking incidents.
  • [cookieName]. The name of the cookie whose contents you want to display on the error page.

XML error object

When a user’s connection to an XML page is blocked, or a user asks for a nonexistent XML application, the App Firewall sends an XML-based error response to the user’s browser. You configure the error response by uploading an XML-based error page to the App Firewall in the Imports Pane, on the XML Error Object tab. All XML error responses are hosted on the App Firewall. You cannot configure a redirect URL for XML applications.

Note: You can use the same customization variables in an XML error object as in an HTML error object.

XML Schema

When the App Firewall performs a validation check on a user’s request for an XML or Web 2.0 application, it can validate the request against the XML schema or design type document (DTD) for that application and reject any request that does not follow the schema or DTD. Both an XML schema and a DTD are standard XML configuration files that describe the structure of a specific type of XML document.

WSDL

When the App Firewall performs a validation check on a user’s request for an XML SOAP-based web service, it can validate the request against the web services type definition (WSDL) file for that web service. A WSDL file is a standard XML SOAP configuration file that defines the elements of a specific XML SOAP web service.

Imports

In this article