HAProxy Enterprise Documentation 2.3r1

Overview

An ACL is an expresson that returns true or false, which you can then use to make a decision in your configuration. For example, should I route this request to backend A or backend B? Or, should I redirect this request to another domain? Or perhaps should I reject this client's connection?

First, let's examine an ACL on its own, without referencing it anywhere. The following ACL, which begins with the acl keyword, returns true if the requested URL path begins with /images/:

frontend www
   bind :80
   acl image_url path -i -m beg /images/
  • The -i flag performs a case-insensitive match of the requested URL path.

  • The -m beg flag sets the match type to begins with.

You can also use a shorthand syntax, path_beg, instead of path:

frontend www
   bind :80
   acl image_url path_beg -i /images/

Specify multiple values to match against by separating them with spaces:

frontend www
   bind :80
   acl image_url path_beg -i /images/ /photos/

It's possible to specify an ACL on multiple lines, in which case it behaves as the previous example, where the values were separated by spaces:

frontend www
   bind :80
   acl image_url path_beg -i /images/
   acl image_url path_beg -i /photos/

The functions path and path_beg are called fetch methods or fetches for short. Most fetches do not have a shorthand syntax like path_beg, but check the Reference Manual to learn about those that do.

When HAProxy Enterprise evaluates an ACL, it always returns true or false. You can then use the ACL on any line that allows a conditional if or unless statement. For instance, to select a specific backend if the URL path begins with /images/, place the name of the ACL after an if statement at the end of a use_backend line in a frontend section:

frontend www
   bind :80
   acl image_url path_beg -i /images/
   use_backend static_assets if image_url

Now, request that begin with /images/ are routed to the backend pool of servers named static_assets.

You can reference multiple ACLs in a condition. In this case, a logical AND operator is implied:

frontend www
   bind :80
   acl api_url path_beg /api/
   acl is_post method POST

   # The path begins with /api/ and the method is POST
   use_backend api_server if api_url meth_post

   # This is equivalent
   use_backend api_server if { path_beg /api/ } { method POST }

You can also specify a logical OR operator by using ||:

frontend www
   bind :80
   acl api_url path_beg /api/
   acl is_post method POST

   # The path begins with /api/ or the method is POST
   use_backend api_server if api_url || meth_post

To negate a condition, use the unless operator:

frontend www
   bind :80
   acl api_url path_beg /api/

   # Use webservers only if the path does not begin with /api/
   use_backend webservers unless api_url

Next up

Syntax