Alerts and monitoring

Error pages

Available since

  • HAProxy 2.2
  • HAProxy Enterprise 2.2r1
  • HAProxy ALOHA 12.5

You can customize the HTTP error pages clients receive to add your own styling, text, and images. Two scenarios exist:

  • Customize HTTP errors generated by the load balancer
  • Customize HTTP errors received from the backend web servers

Customize load balancer errors Jump to heading

The http-errors section locates custom HTML pages to return to clients when errors occur. By default, the load balancer 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.

To define custom error pages:

  1. Create a file with a .http file extension and 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 error page, and save it as 403.http:

    403.http
    html
    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>
    403.http
    html
    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>
  2. In your load balancer configuration, add an http-errors section with one or more errorfile directives, where each specifies an HTTP response status code and the path to an error file. In the following example, we define one custom error page to use for 403 Forbidden errors:

    haproxy
    http-errors myerrors
    errorfile 403 /403.http
    haproxy
    http-errors myerrors
    errorfile 403 /403.http

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

    haproxy
    http-errors myerrors
    errorfile 403 /403.http
    errorfile 404 /404.http
    errorfile 500 /500.http
    haproxy
    http-errors myerrors
    errorfile 403 /403.http
    errorfile 404 /404.http
    errorfile 500 /500.http
  3. To use custom error pages, reference the name of the http-errors section by using an errorfiles directive in your frontend:

    haproxy
    frontend www
    bind :80
    default_backend webservers
    errorfiles myerrors
    haproxy
    frontend www
    bind :80
    default_backend webservers
    errorfiles myerrors

Customize web server errors Jump to heading

You can intercept error responses from backend web servers and replace them with your custom error pages.

  1. In your load balancer configuration, add an http-errors section with one or more errorfile directives, where each specifies an HTTP response status code and the path to an error file. In the following example, we define one custom error page to use for 404 Not Found errors:

    haproxy
    http-errors myerrors
    errorfile 404 /404.http
    haproxy
    http-errors myerrors
    errorfile 404 /404.http
  2. In your frontend, add an errorfiles directive that refers to your http-errors section. Also, add an http-response return directive to intercept any response from the server that has a 404 status. It then, by specifying default-errorfiles, returns the 404 errorfile that was defined in the myerrors section:

    haproxy
    frontend www
    bind :80
    default_backend webservers
    errorfiles myerrors
    http-response return status 404 default-errorfiles if { status 404 }
    haproxy
    frontend www
    bind :80
    default_backend webservers
    errorfiles myerrors
    http-response return status 404 default-errorfiles if { status 404 }
  3. Optional: The default-errorfiles argument instructs the load balancer 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 argument on the http-response return line. In the following example, we use the 404 page from the alternative_errors if the status is 404 and the Host header is example.com:

    haproxy
    http-errors myerrors
    errorfile 403 /403.http
    errorfile 404 /404.http
    errorfile 500 /500.http
    http-errors alternative_errors
    errorfile 403 /403-alt.http
    errorfile 404 /404-alt.http
    errorfile 500 /500-alt.http
    frontend www
    bind :80
    default_backend webservers
    http-request set-var(txn.host) req.hdr(host)
    errorfiles myerrors
    http-response return status 404 errorfiles alternative_myerrors if { status 404 } { var(txn.host) example.com }
    http-response return status 404 default-errorfiles if { status 404 } !{ var(txn.host) example.com }
    haproxy
    http-errors myerrors
    errorfile 403 /403.http
    errorfile 404 /404.http
    errorfile 500 /500.http
    http-errors alternative_errors
    errorfile 403 /403-alt.http
    errorfile 404 /404-alt.http
    errorfile 500 /500-alt.http
    frontend www
    bind :80
    default_backend webservers
    http-request set-var(txn.host) req.hdr(host)
    errorfiles myerrors
    http-response return status 404 errorfiles alternative_myerrors if { status 404 } { var(txn.host) example.com }
    http-response return status 404 default-errorfiles if { status 404 } !{ var(txn.host) example.com }

See also Jump to heading

If this page was useful, please, Leave the feedback.