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

Starting with Avi Vantage release 18.1, 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.

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