Avi Vantage Custom Error Responses

Overview

On encountering an error that prevents it from processing a HTTP request or response, Avi Vantage returns a generic error message with a status code to the client. This article discusses customizing the error message page returned by Avi Vantage on encountering an error.

Note: Customized error response page is different from having Avi Vantage return a custom web page using a DataScript or policy, when the server returns the error page.

403_error

Avi Vantage generates error pages for the listed conditions:

  • A request is blocked due to a Web Application Firewall (WAF) policy match.
  • HTTP request or response parsing error, such as an invalid request.
  • Back-end server handshake failure or connection timeout.
  • Logic failure in a DataScript.

Pool Fail Action

In cases where all servers are down and the pool servers are unable to return a page, a pool may be configured to return a custom error page.

Navigate to Applications > Pools and click on the pool to be edited. In the Advanced tab, under Pool Failure Settings, set the Pool Fail Action to HTTP Local Response. Set the desired return code under Status Code and optionally upload the HTML file in the Upload File field.

pool_fail_action

By default, the pool fail action is set to Close Connection and a TCP reset is sent to the client. This action takes effect after an HTTP request is received and before the response. For instance, a WAF security violation triggered by a client request would take precedence. The WAF would send out a 403 error page rather than a page sent by the Pool Fail Action.

DataScript

DataScripts can be used to return custom error messages to the client. For this, the DataScript needs to first detect the error.

A custom error page DataScript is triggered by the RESP_FAILED event, which occurs when Avi Vantage is unable to process a transaction and return a page to the client. Note that this event is only executed when Avi Vantage generates the error. If the error is generated by the server, as in the case of 503 (service unavailable) response, the DataScript should use the HTTP_RESP event to overwrite the page that is returned by the server. The avi.http.internal_status() function will return the reason for this error. This information is embedded within the returned custom error page. The response is then sent to the client by embedding the custom HTML into the avi.http.response() function. Alternatively, an HTTP redirect could be used via avi.http.redirect().

 

-- RESP_FAILED
status = avi.http.internal_status()
html = "Your request could not be completed. Please contact support."

if status then html = html .. " Reason: " .. status end
html = html .. ""
avi.http.response(503, {content_type="text/html"}, html)

Error Page Profile

You can configure one or more custom error pages on Avi Vantage.

Navigate to Templates > Error Page > Error Page Profile and click on Create.

customerrorprofile

These pages are simple HTML pages that are defined in the error page body. An error page profile can point to multiple error page bodies. Ensure that each error page profile is associated with a different HTTP status code or a range of status codes.

Custom tokens or variables are dynamic data generated by Avi Vantage that can be inserted into the returned page. These variables must be separated by a space, after and before. The Avi parser will reject other string ($) characters contained within the HTML of an error page. The following are the available variables:

  • $status – Returns the status code that Avi Vantage returns to the client.

  • $request_id – Returns an unique identifier that Avi Vantage assigns to the specific request or response. This identifier is also included in the logs. When this identifier is returned to the client, the specific transaction can be located in the logs to find the reason for the error. A common use case is that of WAF, which may block a client request for a wide range of violations. By locating the request ID in the logs, the administrator can validate if the blocked request or WAF signature should be exempted from blocking future requests.

  • $vs_name – Returns the name of the virtual service. This name could be different from the connected FQDN clients.

customerrorpage

Style sheets, JavaScript, or even base64-encoded images can be embedded within a single HTML file as inline objects for robust error pages. Alternatively, the HTML page can include links to another site for retrieving these additional objects.

Custom Error Page Profile

Starting with 21.1.1, every virtual service will have a user-defined HTML error page (Custom-Error-Page-Profile) for Avi-generated 4xx and 5xx errors.
You can update or add specific error page profiles and pages​ as required.
The Custom-Error-Page (HTML) is packaged in the Controller. The size of this page is ~4KB.

Note: Custom-Error-Page-Profile is currently available only for the Enterprise license tier.

To edit the custom error page profile,

  1. From the Avi UI, navigate to Templates > Error Page > Error Page Profile > Custom-Error-Page-Profile.

    customerrorpageprofile

  2. Click on the edit button.

  3. In the Edit Error Page Profile sub-screen, hovering the mouse over the custom-error-page will make the delete and edit icons available. Click on the edit icon to modify the body of the error page.

    customerrorpageprofile

  4. Click on the three dotted lines against the Custom Error Page and click on the Edit icon.

    customerrorpageprofile

  5. The page body has the logo, response code, application name and the Request ID defined by default. Edit the HTML content as required.

    customerrorpageprofile

  6. Click on Save to update the changes.

The default custom error page appears as shown below:
customerrorpageprofile

Uncomment the line in this page to get the Request ID and  virtual service name:
<!-- Please contact our technical support with Request ID: $request_id and Application Name: $vs_name -->
                 Virtual services, by default, refer to the Custom-Error-Page-Profile.

customerrorpageprofile

Returning a JSON Error Page

Starting with Avi Vantage 18.2.3, it is possible to return an error page in JSON format instead of HTML. At this time, configuration is supported via the CLI only. The three major steps are illustrated below.

Step One: Create the Error Page

The first step is to create an error page body using the configure command.

[admin:10-10-26-45]: > configure errorpagebody Json-Error-Page-Body
[admin:10-10-26-45]: errorpagebody> format error_page_format_json
[admin:10-10-26-45]: errorpagebody> error_page_body --
Please input the value for field error_page_body (Enter END to terminate input):"{ \"request_id\":\" $request_id \", \"application_name\":\" $vs_name \", \"status_code\":\" $status \" }"
END
[admin:10-10-26-45]: errorpagebody> save
+-----------------+----------------------------------------------------------------------------------+
| Field           | Value                                                                            |
+-----------------+----------------------------------------------------------------------------------+
| uuid            | errorpagebody-6a0ee492-30bc-41fc-8105-ec6166f7ae04                               |
| name            | Json-Error-Page-Body                                                             |
| tenant_ref      | admin                                                                            |
| error_page_body | "{ \"request_id\":\" $request_id \", \"application_name\":\" $vs_name \", \"stat |
|                 | us_code\":\" $status \" }"                                                       |
| format          | ERROR_PAGE_FORMAT_JSON                                                           |
+-----------------+----------------------------------------------------------------------------------+

Step Two: Create an Error Page Profile

The below illustrates creation of an error page profile that references the error page body and associates it with the status code that will trigger its return to the client.

[admin:10-10-26-45]: > configure errorpageprofile Json-Error-Profile
[admin:10-10-26-45]: errorpageprofile> error_pages index 0
New object being created
[admin:10-10-26-45]: errorpageprofile:error_pages> enable
[admin:10-10-26-45]: errorpageprofile:error_pages> match match_criteria is_in status_codes 503
[admin:10-10-26-45]: errorpageprofile:error_pages:match> save
[admin:10-10-26-45]: errorpageprofile:error_pages> error_page_body_ref Json-Error-Page-Body
[admin:10-10-26-45]: errorpageprofile:error_pages> save
[admin:10-10-26-45]: errorpageprofile> save
+-----------------------+-------------------------------------------------------+
| Field                 | Value                                                 |
+-----------------------+-------------------------------------------------------+
| uuid                  | errorpageprofile-f8381196-ab7e-4716-96c6-ad99db8beb41 |
| name                  | Json-Error-Profile                                    |
| tenant_ref            | admin                                                 |
| error_pages[1]        |                                                       |
|   index               | 0                                                     |
|   enable              | True                                                  |
|   match               |                                                       |
|     match_criteria    | IS_IN                                                 |
|     status_codes[1]   | 503                                                   |
|   error_page_body_ref | Json-Error-Page-Body                                  |
+-----------------------+-------------------------------------------------------+
[admin:10-10-26-45]: >

Step Three: Associate the Virtual Service with the Error Page Profile

This is the third and final step. Imagine the name of the VS is MyVS. In one CLI command the association between the virtual service and error profile can be made:

[admin:10-10-26-45]: > configure virtualservice MyVS error_page_profile_ref Json-Error-Profile