ACL Criterion

The criterion is generally the name of a sample fetch method, or one of the Sample fetch ACL derivatives declinations.

The ACL declinations can describe alternate matching methods for a same sample fetch method.

As a reminder, sample fetch methods can return the following data types:

• boolean

• integer (signed or unsigned)

• IPv4 or IPv6 address

• string

• binary data block

Criterion converters

Converters transform any supported data type any other data type.

The resulting sample's type is the same as the type of the last converter applied to the list, which defaults to the type of the sample fetch method.

Sample fetch ACL derivatives

All ACL-specific criteria imply a default matching method. Most often, these criteria are built by concatenating the name of the original sample fetch method and the matching method.

For example, hdr_beg applies the beg match to the sample retrieved using the hdr fetch.

Since all ACL-specific criteria rely on a sample fetch method, you can use the original sample fetch method and the explicit matching method with -m.

If an alternate match is specified using -m on an ACL-specific criterion, the matching method is applied to the underlying sample fetch method.

For example, all ACLs below are exactly equivalent:

acl short_form  hdr_beg(host)        www.
acl alternate1  hdr_beg(host) -m beg www.
acl alternate2  hdr_dom(host) -m beg www.
acl alternate3  hdr(host)     -m beg www.

The table below presents ACL derivatives from their respective sample fetch:

acl -f flag

The -f flag must be followed by the name of a file from which all lines will be read as individual pattern. It is possible to pass multiple -f arguments if the patterns must be loaded from multiple files.

The following actions happen when HAProxy loads an ACL pattern list from a file:

• Empty lines are ignored

• Lines starting with a sharp (#) are ignored

• All leading spaces and tabs are stripped

acl -M flag

The -M flag allows an ACL to use a map file. With this flag set, the file is parsed as a two column file:

The first column contains the patterns used by the ACL, and the second column contain the samples. The samples can be used later by a map. This can be useful in some cases where an ACL would be used to check for a pattern in a map before it applies mapping.

acl -u flag

The -u flag forces the unique ID of the ACL.

This unique ID is used with the stats socket interface to identify an ACL and dynamically change its values.

acl -m flag

The -m flag is used to select a specific matching method on the input sample.

All ACL-specific criteria imply a matching method and generally do not need this flag. However, this flag is useful with generic sample fetch methods to describe how they get matched against the patterns.

This is required for sample fetches which return data type for which there is no obvious matching method (e.g. string or binary).

When -m is specified and followed by a matching method name, this method is used instead of the default one for the criterion. This makes it possible to match contents in ways that were not initially planned, or with sample fetch methods which return a string. The matching method also affects the way the patterns are parsed.

The matching <methods> must be one of the following:

acl -n flag

The -n flag forbids DNS resolutions. It is used when loading IPs from a file. By default, when the parser can not parse an IP address, it considers that the parsed string is a domain name and tries to resolve it using DNS.

If the DNS server is not reachable, the HAProxy configuration parsing can take several minutes waiting for DNS timeouts. During this time, it does not display error messages.

Matching booleans

Boolean matching applies by default to boolean fetch methods or converters.

In order to match a Boolean, no pattern is required and all patterns are ignored. When using Boolean matching, the criterion returns the sample as is (hence the fetch), which means that a Boolean true will always match and a Boolean false will never match.

You can enforce Boolean matching by using the flag -m bool on fetch method returning an integer type. In such cases, 0 is converted to a Boolean false and all other values are converted to Boolean true.

Matching integers

Integer matching applies by default to integer fetch methods or converters.

You can also enforce it on boolean fetches using the flag -m int. In such cases, false is converted to the integer 0, and true is converted to the integer 1.

Integer matching also supports integer ranges and operators.

Matching strings

By default, string matching applies to string or binary fetch methods or converters, and exists in 6 formats.

They use the -m flag:

String matching applies to verbatim strings as they are passed, with the exception of the backslash (\). This enables you to avoid characters such as the space.

When the flag -i is passed before the first string, then the matching performed is not case-sensitive.

To match the pattern -i, you can either set it after, or pass the specific flag -- before the first pattern. The same applies to match the pattern -.

Matching regular expressions

Regex matching applies to verbatim samples as they are passed, with the exception of the backslash (\). This enables you to avoid characters such as the space.

When the flag -i is passed before the first regex, then the matching performed is not case-sensitive.

To match the pattern -i, you can either set it after, or pass the specific flag -- before the first pattern. The same applies to match the pattern -.

Matching arbitrary data blocks

It is possible to match samples against a binary block which may not be safely represented as a string. For this, the patterns must be passed as a series of hexadecimal digits in an even number.

This works when the match method is set to binary. Each sequence of two digits represents a byte. The hexadecimal digits can either be in upper or lower case.

Matching IPv4 and IPv6 addresses

You can specify a pattern of IPv4 addresses either as plain addresses or with an appended netmask, in which case the IPv4 address matches whenever it is within the network.

You can also replace plain addresses with a resolvable host name using DNS, but this practice is generally not recommended as it makes it more difficult to read and debug configurations.

If you use host names, ensure that they are present in /etc/hosts so that the configuration does not depend on any random DNS match at the moment the configuration is parsed.

You can enter IPv6 addresses in their usual form, with or without an appended netmask . Only bit counts are accepted for IPv6 netmasks.

To avoid any risk of problems with randomly resolved IP addresses, host names are never allowed for IPv6 patterns.

HAProxy can also match IPv4 addresses with IPv6 addresses in the following situations: