HAProxy Enterprise Documentation 2.3r1

Http-errors

The http-errors section locates custom HTML pages to return to clients when errors occur. When defining an http-errors section, assign it a unique label (e.g. custom_errors).

http-errors custom_errors
   # custom error pages listed

Add one or more errorfile directives to the section, where each specifies an HTTP response status code and the path to an HTML page. In the following example, we define one custom error page to use for 403 Forbidden errors. Error pages should use the .http file extension:

http-errors custom_errors
   errorfile 403 /etc/hapee-2.3/errors/403.http

When defining a custom error page, add HTTP metadata at the top of the file. The metadata should include the HTTP start line and headers. In the following example, we define a custom 403 page, which we store as 403.http:

HTTP/1.1 403 Forbidden
Cache-Control: no-cache
Connection: close
Content-Type: text/html

<!DOCTYPE html>
<html>
   <body>
      <h1>403 Forbidden</h1>
      <p>Sorry, but you are not authorized to view this page.</p>
   </body>
</html>

To use custom error pages, reference the name of the http-errors section by using an errorfiles directive in your frontend:

frontend www
   bind :80
   default_backend webservers
   errorfiles custom_errors

You can define different error page files for different response status code:

http-errors my_custom_errors
   errorfile 403 /etc/hapee-2.3/errors/403.http
   errorfile 404 /etc/hapee-2.3/errors/404.http
   errorfile 500 /etc/hapee-2.3/errors/500.http

By default, HAProxy Enterprise will serve these pages only if it initiated the error itself. For example, it will return the page for a 503 Service Unavailable error if it can't reach any backend servers. However, it is more common for errors to be sent back from the backend server. In that case, you must intercept the response from the server and replace it with your custom error page.

In the configuration sample below, the frontend www uses the http-response return directive to intercept any response from the server that has a 404 status. It then returns the 404 errorfile that was defined in the my_custom_errors section:

frontend www
   bind :80
   default_backend webservers
   errorfiles my_custom_errors
   http-response return  status 404  default-errorfiles  if { status 404 }

The default-errorfiles parameter instructs HAProxy Enterprise to use the error files specified by the errorfiles directive within the frontend. Alternatively, you can indicate a different set of error files to use by setting the errorfiles parameter on the http-response return line. In the following example, we use the 404 page from the alternative_custom_errors if the status is 404 and the Host header is example.com:

http-errors my_custom_errors
   errorfile 403 /etc/hapee-2.1/errors/403.http
   errorfile 404 /etc/hapee-2.1/errors/404.http
   errorfile 500 /etc/hapee-2.1/errors/500.http

http-errors alternative_custom_errors
   errorfile 403 /etc/hapee-2.1/errors/403-alt.http
   errorfile 404 /etc/hapee-2.1/errors/404-alt.http
   errorfile 500 /etc/hapee-2.1/errors/500-alt.http

frontend www
   bind :80
   default_backend webservers
   http-request set-var(txn.host) req.hdr(host)
   errorfiles my_custom_errors
   http-response return  status 404  errorfiles alternative_custom_errors  if { status 404 } { var(txn.host) example.com }

Next up

Mailers