DOC: major reorg of ACL + sample fetch
The split between ACL and sample fetch was a terrible mess in the doc,
as it caused all entries to be duplicated with most of them not easy to
find, some missing and some wrong.
The new approach consists in describing the sample fetch methods and
indicating the ACLs that are derived from these fetches. The doc is
much smaller (1500 lines added, 2200 removed, net gain = 700 lines)
and much clearer.
The description of the ACL mechanics was revamped to take account of
the latest evolutions and clearly describe the compatibility between
types of fetches and ACL patterns.
The deprecated keywords have been marked as such, though they still
appear in the examples given for various other keywords.
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 13e136d..93437bb 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -59,18 +59,22 @@
6. HTTP header manipulation
-7. Using ACLs and pattern extraction
-7.1. Matching integers
-7.2. Matching strings
-7.3. Matching regular expressions (regexes)
-7.4. Matching IPv4 and IPv6 addresses
-7.5. Available matching criteria
-7.5.1. Matching at Layer 4 and below
-7.5.2. Matching contents at Layer 4
-7.5.3. Matching at Layer 7
-7.6. Pre-defined ACLs
-7.7. Using ACLs to form conditions
-7.8. Pattern extraction
+7. Using ACLs and fetching samples
+7.1. ACL basics
+7.1.1. Matching booleans
+7.1.2. Matching integers
+7.1.3. Matching strings
+7.1.4. Matching regular expressions (regexes)
+7.1.5. Matching arbitrary data blocks
+7.1.6. Matching IPv4 and IPv6 addresses
+7.2. Using ACLs to form conditions
+7.3. Fetching samples
+7.3.1. Fetching samples from internal states
+7.3.2. Fetching samples at Layer 4
+7.3.3. Fetching samples at Layer 5
+7.3.4. Fetching samples from buffer contents (Layer 6)
+7.3.5. Fetching HTTP samples (Layer 7)
+7.4. Pre-defined ACLs
8. Logging
8.1. Log levels
@@ -5903,7 +5907,7 @@
no | no | yes | yes
Arguments :
- <pattern> is a pattern extraction rule as described in section 7.8. It
+ <pattern> is a pattern extraction rule as described in section 7.3. It
describes what elements of the incoming request or connection
will be analysed in the hope to find a matching entry in a
stickiness table. This rule is mandatory.
@@ -6022,7 +6026,7 @@
no | no | yes | yes
Arguments :
- <pattern> is a pattern extraction rule as described in section 7.8. It
+ <pattern> is a pattern extraction rule as described in section 7.3. It
describes what elements of the incoming request or connection
will be analysed, extracted and stored in the table once a
server is selected.
@@ -6329,7 +6333,7 @@
no | no | yes | yes
Arguments :
- <pattern> is a pattern extraction rule as described in section 7.8. It
+ <pattern> is a pattern extraction rule as described in section 7.3. It
describes what elements of the response or connection will
be analysed, extracted and stored in the table once a
server is selected.
@@ -6478,7 +6482,7 @@
These actions take one or two arguments :
<key> is mandatory, and is a pattern extraction rule as described
- in section 7.8. It describes what elements of the incoming
+ in section 7.3. It describes what elements of the incoming
request or connection will be analysed, extracted, combined,
and used to select which table entry to update the counters.
Note that "tcp-request connection" cannot use content-based
@@ -8211,22 +8215,35 @@
before switching.
-7. Using ACLs and pattern extraction
-------------------------------------
+7. Using ACLs and fetching samples
+----------------------------------
+
+Haproxy is capable of extracting data from request or response streams, from
+client or server information, from tables, environmental information etc...
+The action of extracting such data is called fetching a sample. Once retrieved,
+these samples may be used for various purposes such as a key to a stick-table,
+but most common usages consist in matching them against predefined constant
+data called patterns.
+
+
+7.1. ACL basics
+---------------
The use of Access Control Lists (ACL) provides a flexible solution to perform
content switching and generally to take decisions based on content extracted
from the request, the response or any environmental status. The principle is
simple :
- - define test criteria with sets of values
- - perform actions only if a set of tests is valid
+ - extract a data sample from a stream, table or the environment
+ - apply one or multiple pattern matching methods on this sample
+ - perform actions only when a pattern matches the sample
-The actions generally consist in blocking the request, or selecting a backend.
+The actions generally consist in blocking a request, selecting a backend, or
+adding a header.
In order to define a test, the "acl" keyword is used. The syntax is :
- acl <aclname> <criterion> [flags] [operator] <value> ...
+ acl <aclname> <criterion> [flags] [operator] [<value>] ...
This creates a new ACL <aclname> or completes an existing one with new tests.
Those tests apply to the portion of request/response specified in <criterion>
@@ -8241,38 +8258,84 @@
There is no enforced limit to the number of ACLs. The unused ones do not affect
performance, they just consume a small amount of memory.
+The criterion generally is the name of a sample fetch method, or one of its ACL
+specific declinations. The default test method is implied by the output type of
+this sample fetch method. The ACL declinations can describe alternate matching
+methods of a same sample fetch method.
+
+Sample fetch methods return data which can be of the following types :
+ - boolean
+ - integer (signed or unsigned)
+ - IPv4 or IPv6 address
+ - string
+ - data block
+
+The ACL engine can match these types against patterns of the following types :
+ - boolean
+ - integer or integer range
+ - IP address / network
+ - string (exact, substring, suffix, prefix, subdir, domain)
+ - regular expression
+ - hex block
+
The following ACL flags are currently supported :
-i : ignore case during matching of all subsequent patterns.
-f : load patterns from a file.
- -m : changes the pattern matching method
+ -m : use a specific pattern matching method
-- : force end of flags. Useful when a string looks like one of the flags.
+The "-f" flag is followed by the name of a file from which all lines will be
+read as individual values. It is even possible to pass multiple "-f" arguments
+if the patterns are to be loaded from multiple files. Empty lines as well as
+lines beginning with a sharp ('#') will be ignored. All leading spaces and tabs
+will be stripped. If it is absolutely necessary to insert a valid pattern
+beginning with a sharp, just prefix it with a space so that it is not taken for
+a comment. Depending on the data type and match method, haproxy may load the
+lines into a binary tree, allowing very fast lookups. This is true for IPv4 and
+exact string matching. In this case, duplicates will automatically be removed.
+
+Also, note that the "-i" flag applies to subsequent entries and not to entries
+loaded from files preceding it. For instance :
+
+ acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
+
+In this example, each line of "exact-ua.lst" will be exactly matched against
+the "user-agent" header of the request. Then each line of "generic-ua" will be
+case-insensitively matched. Then the word "test" will be insensitively matched
+as well.
+
-The "-m" flag is special. It allows the default pattern matching method to be
-changed for the fetched sample. The default method depends on the keyword and
-is described later in this document. When "-m" is specified and followed by a
-pattern matching method name, this method is used instead. This makes it
-possible to match contents in ways that were not initially planned. There are
-some restrictions however. Not all methods can be used with all sample fetch
-methods. Also, if "-m" is used in conjunction with "-f", it must be placed
-first. The pattern matching method must be one of the following :
+The "-m" flag is used to select a specific pattern matching method on the input
+sample. All ACL-specific criteria imply a pattern matching method and generally
+do not need this flag. However, this flag is useful with generic sample fetch
+methods to describe how they're going to be matched against the patterns. This
+is required for sample fetches which return data type for which there is no
+obvious matching method (eg: string or binary). When "-m" is specified and
+followed by a pattern 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.
+
+There are some restrictions however. Not all methods can be used with all
+sample fetch methods. Also, if "-m" is used in conjunction with "-f", it must
+be placed first. The pattern matching method must be one of the following :
- "found" : only check if the requested sample could be found in the stream,
but do not compare it against any pattern. It is recommended not
- to pass any pattern to avoid any confusion. This matching method
- is particularly useful to detect presence of certain contents
- such as headers, cookies, etc... even if they are empty and
- without comparing them to anything nor counting them.
+ to pass any pattern to avoid confusion. This matching method is
+ particularly useful to detect presence of certain contents such
+ as headers, cookies, etc... even if they are empty and without
+ comparing them to anything nor counting them.
- "bool" : check the value as a boolean. It can only be applied to fetches
which return a boolean or integer value, and takes no pattern.
- Value zero does not match, all other values do match.
+ Value zero or false does not match, all other values do match.
- "int" : match the value as an integer. It can be used with integer and
- boolean samples.
+ boolean samples. Boolean false is integer 0, true is integer 1.
- "ip" : match the value as an IPv4 or IPv6 address. It is compatible
- with IP addresse only.
+ with IP address samples only, so it is implied and never needed.
- "bin" : match the contents against an hexadecimal string representing a
binary sequence. This may be used with binary or string samples.
@@ -8280,28 +8343,29 @@
- "len" : match the sample's length as an integer. This may be used with
binary or string samples.
- - "str" : match the contents against a string. This may be used with
- binary or string samples.
+ - "str" : exact match : match the contents against a string. This may be
+ used with binary or string samples.
- - "beg" : check that the contents begin like the provided string patterns.
- This may be used with binary or string samples.
+ - "sub" : substring match : check that the contents contain at least one of
+ the provided string patterns. This may be used with binary or
+ string samples.
- - "sub" : check that the contents contain at least one of the provided
- string patterns. This may be used with binary or string samples.
+ - "reg" : regex match : match the contents against a list of regular
+ expressions. This may be used with binary or string samples.
- - "dir" : check that a slash-delimited portion of the contents exactly
- match one of the provided string patterns. This may be used with
- binary or string samples.
+ - "beg" : prefix match : check that the contents begin like the provided
+ string patterns. This may be used with binary or string samples.
- - "dom" : check that a dot-delimited portion of the contents exactly
- match one of the provided string patterns. This may be used with
- binary or string samples.
+ - "end" : suffix match : check that the contents end like the provided
+ string patterns. This may be used with binary or string samples.
- - "end" : check that the contents end like the provided string patterns.
+ - "dir" : subdir match : check that a slash-delimited portion of the
+ contents exactly matches one of the provided string patterns.
This may be used with binary or string samples.
- - "reg" : match the contents against a list of regular expressions. This
- may be used with binary or string samples.
+ - "dom" : domain match : check that a dot-delimited portion of the contents
+ exactly match one of the provided string patterns. This may be
+ used with binary or string samples.
For example, to quickly detect the presence of cookie "JSESSIONID" in an HTTP
request, it is possible to do :
@@ -8313,45 +8377,84 @@
acl script_tag payload(0,500) -m reg -i <script>
-The "-f" flag is special as it loads all of the lines it finds in the file
-specified in argument and loads all of them before continuing. It is even
-possible to pass multiple "-f" arguments if the patterns are to be loaded from
-multiple files. Empty lines as well as lines beginning with a sharp ('#') will
-be ignored. All leading spaces and tabs will be stripped. If it is absolutely
-needed to insert a valid pattern beginning with a sharp, just prefix it with a
-space so that it is not taken for a comment. Depending on the data type and
-match method, haproxy may load the lines into a binary tree, allowing very fast
-lookups. This is true for IPv4 and exact string matching. In this case,
-duplicates will automatically be removed. Also, note that the "-i" flag applies
-to subsequent entries and not to entries loaded from files preceding it. For
-instance :
+All ACL-specific criteria imply a default matching method. Most often, these
+criteria are composed by concatenating the name of the original sample fetch
+method and the matching method. For example, "hdr_beg" applies the "beg" match
+to samples retrieved using the "hdr" fetch method. Since all ACL-specific
+criteria rely on a sample fetch method, it is always possible instead to use
+the original sample fetch method and the explicit matching method using "-m".
- acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test
+If an alternate match is specified using "-m" on an ACL-specific criterion,
+the mathing method is simply applied to the underlying sample fetch method. For
+example, all ACLs below are exact equivalent :
-In this example, each line of "exact-ua.lst" will be exactly matched against
-the "user-agent" header of the request. Then each line of "generic-ua" will be
-case-insensitively matched. Then the word "test" will be insensitively matched
-too.
+ 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.
-Note that right now it is difficult for the ACL parsers to report errors, so if
-a file is unreadable or unparsable, the most you'll get is a parse error in the
-ACL. Thus, file-based ACLs should only be produced by reliable processes.
-Supported types of values are :
+The table below summarizes the compatibility matrix between sample fetch types
+and the pattern types to fetch against. It indicates for each compatible
+combination the name of the matching method to be used, prefixed with "*" when
+the method is implicit and will work by default without "-m".
- - integers or integer ranges
- - strings
- - regular expressions
- - IP addresses and networks
+ +-------------------------------------------------+
+ | Input sample type |
+ +----------------------+---------+---------+---------+---------+---------+
+ | pattern type | boolean | integer | IP | string | binary |
+ +----------------------+---------+---------+---------+---------+---------+
+ | none (presence only) | found | found | found | found | found |
+ +----------------------+---------+---------+---------+---------+---------+
+ | none (boolean value) | *bool | bool | | | |
+ +----------------------+---------+---------+---------+---------+---------+
+ | integer (value) | int | *int | | | |
+ +----------------------+---------+---------+---------+---------+---------+
+ | integer (length) | | | | len | len |
+ +----------------------+---------+---------+---------+---------+---------+
+ | IP address | | | *ip | | |
+ +----------------------+---------+---------+---------+---------+---------+
+ | exact string | | | | str | str |
+ +----------------------+---------+---------+---------+---------+---------+
+ | prefix | | | | beg | beg |
+ +----------------------+---------+---------+---------+---------+---------+
+ | suffix | | | | end | end |
+ +----------------------+---------+---------+---------+---------+---------+
+ | substring | | | | sub | sub |
+ +----------------------+---------+---------+---------+---------+---------+
+ | subdir | | | | dir | dir |
+ +----------------------+---------+---------+---------+---------+---------+
+ | domain | | | | dom | dom |
+ +----------------------+---------+---------+---------+---------+---------+
+ | regex | | | | reg | reg |
+ +----------------------+---------+---------+---------+---------+---------+
+ | hex block | | | | bin | bin |
+ +----------------------+---------+---------+---------+---------+---------+
-7.1. Matching integers
-----------------------
+7.1.1. Matching booleans
+------------------------
+
+In order to match a boolean, no value is needed and all values are ignored.
+Boolean matching is used by default for all fetch methods of type "boolean".
+When boolean matching is used, the fetched value is returned as-is, which means
+that a boolean "true" will always match and a boolean "false" will never match.
+
+Boolean matching may also be enforced using "-m bool" on fetch methods which
+return an integer value. Then, integer value 0 is converted to the boolean
+"false" and all other values are converted to "true".
+
-Matching integers is special in that ranges and operators are permitted. Note
-that integer matching only applies to positive values. A range is a value
-expressed with a lower and an upper bound separated with a colon, both of which
-may be omitted.
+7.1.2. Matching integers
+------------------------
+
+Integer matching applies by default to integer fetch methods. It can also be
+enforced on boolean fetches using "-m int". In this case, "false" is converted
+to the integer 0, and "true" is converted to the integer 1.
+
+Integer matching also supports integer ranges and operators. Note that integer
+matching only applies to positive values. A range is a value expressed with a
+lower and an upper bound separated with a colon, both of which may be omitted.
For instance, "1024:65535" is a valid range to represent a range of
unprivileged ports, and "1024:" would also work. "0:1023" is a valid
@@ -8384,8 +8487,31 @@
acl sslv3 req_ssl_ver 3:3.1
-7.2. Matching strings
----------------------
+7.1.3. Matching strings
+-----------------------
+
+String matching applies to string or binary fetch methods, and exists in 6
+different forms :
+
+ - exact match (-m str) : the extracted string must exactly match the
+ patterns ;
+
+ - substring match (-m sub) : the patterns are looked up inside the
+ extracted string, and the ACL matches if any of them is found inside ;
+
+ - prefix match (-m beg) : the patterns are compared with the beginning of
+ the extracted string, and the ACL matches if any of them matches.
+
+ - suffix match (-m end) : the patterns are compared with the end of the
+ extracted string, and the ACL matches if any of them matches.
+
+ - subdir match (-m sub) : the patterns are looked up inside the extracted
+ string, delimited with slashes ("/"), and the ACL matches if any of them
+ matches.
+
+ - domain match (-m dom) : the patterns are looked up inside the extracted
+ string, delimited with dots ("."), and the ACL matches if any of them
+ matches.
String matching applies to verbatim strings as they are passed, with the
exception of the backslash ("\") which makes it possible to escape some
@@ -8395,8 +8521,8 @@
before the first string. Same applies of course to match the string "--".
-7.3. Matching regular expressions (regexes)
--------------------------------------------
+7.1.4. Matching regular expressions (regexes)
+---------------------------------------------
Just like with string matching, regex matching applies to verbatim strings as
they are passed, with the exception of the backslash ("\") which makes it
@@ -8407,8 +8533,22 @@
match the string "--".
-7.4. Matching IPv4 and IPv6 addresses
-----------------------------
+7.1.5. Matching arbitrary data blocks
+-------------------------------------
+
+It is possible to match some extracted samples against a binary block which may
+not safely be represented as a string. For this, the patterns must be passed as
+a series of hexadecimal digits in an even number, when the match method is set
+to binary. Each sequence of two digits will represent a byte. The hexadecimal
+digits may be used upper or lower case.
+
+Example :
+ # match "Hello\n" in the input stream (\x48 \x65 \x6c \x6c \x6f \x0a)
+ acl hello payload(0,6) -m bin 48656c6c6f0a
+
+
+7.1.6. Matching IPv4 and IPv6 addresses
+---------------------------------------
IPv4 addresses values can be specified either as plain addresses or with a
netmask appended, in which case the IPv4 address matches whenever it is
@@ -8437,66 +8577,190 @@
converted to IPv6 by prefixing ::ffff: in front of it, then the match is
applied in IPv6 using the supplied IPv6 mask.
+
+7.2. Using ACLs to form conditions
+----------------------------------
+
+Some actions are only performed upon a valid condition. A condition is a
+combination of ACLs with operators. 3 operators are supported :
+
+ - AND (implicit)
+ - OR (explicit with the "or" keyword or the "||" operator)
+ - Negation with the exclamation mark ("!")
-7.5. Available matching criteria
---------------------------------
+A condition is formed as a disjunctive form:
-A number of predefined criteria may be used to form ACL expressions. The ones
-that are ACL-specific are detailed here. In addition to these ones, all sample
-fetch methods described in section 7.8 may be used. However, with these last
-ones, no default pattern matching method is defined, so it is mandatory to pass
-"-m" followed by a method. When a same keyword exists in both forms, the ACL
-compatible form prevails.
+ [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
+Such conditions are generally used after an "if" or "unless" statement,
+indicating when the condition will trigger the action.
-7.5.1. Matching at Layer 4 and below
-------------------------------------
+For instance, to block HTTP requests to the "*" URL with methods other than
+"OPTIONS", as well as POST requests without content-length, and GET or HEAD
+requests with a content-length greater than 0, and finally every request which
+is not either GET/HEAD/POST/OPTIONS !
+
+ acl missing_cl hdr_cnt(Content-length) eq 0
+ block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
+ block if METH_GET HTTP_CONTENT
+ block unless METH_GET or METH_POST or METH_OPTIONS
+
+To select a different backend for requests to static contents on the "www" site
+and to every request on the "img", "video", "download" and "ftp" hosts :
+
+ acl url_static path_beg /static /images /img /css
+ acl url_static path_end .gif .png .jpg .css .js
+ acl host_www hdr_beg(host) -i www
+ acl host_static hdr_beg(host) -i img. video. download. ftp.
+
+ # now use backend "static" for all static-only hosts, and for static urls
+ # of host "www". Use backend "www" for the rest.
+ use_backend static if host_static or host_www url_static
+ use_backend www if host_www
+
+It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
+expressions that are built on the fly without needing to be declared. They must
+be enclosed between braces, with a space before and after each brace (because
+the braces must be seen as independent words). Example :
+
+ The following rule :
+
+ acl missing_cl hdr_cnt(Content-length) eq 0
+ block if METH_POST missing_cl
+
+ Can also be written that way :
+
+ block if METH_POST { hdr_cnt(Content-length) eq 0 }
+
+It is generally not recommended to use this construct because it's a lot easier
+to leave errors in the configuration when written that way. However, for very
+simple rules matching only one source IP address for instance, it can make more
+sense to use them than to declare ACLs with random names. Another example of
+good use is the following :
+
+ With named ACLs :
+
+ acl site_dead nbsrv(dynamic) lt 2
+ acl site_dead nbsrv(static) lt 2
+ monitor fail if site_dead
+
+ With anonymous ACLs :
+
+ monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
+
+See section 4.2 for detailed help on the "block" and "use_backend" keywords.
+
+
+7.3. Fetching samples
+---------------------
+
+Historically, sample fetch methods were only used to retrieve data to match
+against patterns using ACLs. With the arrival of stick-tables, a new class of
+sample fetch methods was created, most often sharing the same syntax as their
+ACL counterpart. These sample fetch methods are also known as "fetches". As
+of now, ACLs and fetches have converged. All ACL fetch methods have been made
+available as fetch methods, and ACLs may use any sample fetch method as well.
+
+This section details all available sample fetch methods and their output type.
+Some sample fetch methods have deprecated aliases that are used to maintain
+compatibility with existing configurations. They are then explicitly marked as
+deprecated and should not be used in new setups.
+
+The ACL derivatives are also indicated when available, with their respective
+matching methods. These ones all have a well defined default pattern matching
+method, so it is never necessary (though allowed) to pass the "-m" option to
+indicate how the sample will be matched using ACLs.
+
+As indicated in the sample type versus matching compatibility matrix above,
+when using a generic sample fetch method in an ACL, the "-m" option is
+mandatory unless the sample type is one of boolean, integer, IPv4 or IPv6. When
+the same keyword exists as an ACL keyword and as a standard fetch method, the
+ACL engine will automatically pick the ACL-only one by default.
+
+Some of these keywords support one or multiple mandatory arguments, and one or
+multiple optional arguments. These arguments are strongly typed and are checked
+when the configuration is parsed so that there is no risk of running with an
+incorrect argument (eg: an unresolved backend name). Fetch function arguments
+are passed between parenthesis and are delimited by commas. When an argument
+is optional, it will be indicated below between square brackets ('[ ]'). When
+all arguments are optional, the parenthesis may be omitted.
+
+Thus, the syntax of a standard sample fetch method is one of the following :
+ - name
+ - name(arg1)
+ - name(arg1,arg2)
+
+At the moment, the stickiness features are the most advanced users of the
+sample fetch system. The "stick on", and "stick store-request" directives
+support sample fetch rules which allow a list of transformations to be applied
+on top of the fetched sample, and the finaly result is automatically converted
+to the type of the table. These transformations are enumerated as a series
+of specific keywords after the sample fetch method. These keywords can also
+support some arguments (eg: a netmask) which must be passed in parenthesis.
-A first set of criteria applies to information which does not require any
-analysis of the request or response contents. Those generally include TCP/IP
-addresses and ports, as well as internal values independent on the stream.
+The currently available list of transformation keywords include :
-always_false
- This one never matches. All values and flags are ignored. It may be used as
- a temporary replacement for another one when adjusting configurations.
+ lower Convert a string sample to lower case. This can only be placed
+ after a string sample fetch function or after a transformation
+ keyword returning a string type. The result is of type string.
-always_true
- This one always matches. All values and flags are ignored. It may be used as
- a temporary replacement for another one when adjusting configurations.
+ upper Convert a string sample to upper case. This can only be placed
+ after a string sample fetch function or after a transformation
+ keyword returning a string type. The result is of type string.
-avg_queue <integer>
-avg_queue(<backend>) <integer>
+ ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for
+ lookups and storage. This can be used to make all hosts within
+ a certain mask to share the same table entries and as such use
+ the same server. The mask can be passed in dotted form (eg:
+ 255.255.255.0) or in CIDR form (eg: 24).
+
+
+7.3.1. Fetching samples from internal states
+--------------------------------------------
+
+A first set of sample fetch methods applies to internal information which does
+not even relate to any client information. These ones are sometimes used with
+"monitor-fail" directives to report an internal status to external watchers.
+The sample fetch methods described in this section are usable anywhere.
+
+always_false : boolean
+ Always returns the boolean "false" value. It may be used with ACLs as a
+ temporary replacement for another one when adjusting configurations.
+
+always_true : boolean
+ Always returns the boolean "true" value. It may be used with ACLs as a
+ temporary replacement for another one when adjusting configurations.
+
+avg_queue([<backend>]) : integer
Returns the total number of queued connections of the designated backend
- divided by the number of active servers. This is very similar to "queue"
- except that the size of the farm is considered, in order to give a more
- accurate measurement of the time it may take for a new connection to be
- processed. The main usage is to return a sorry page to new users when it
- becomes certain they will get a degraded service. Note that in the event
- there would not be any active server anymore, we would consider twice the
- number of queued connections as the measured value. This is a fair estimate,
- as we expect one server to get back soon anyway, but we still prefer to send
- new traffic to another backend if in better shape. See also the "queue",
- "be_conn", and "be_sess_rate" criteria.
+ divided by the number of active servers. The current backend is used if no
+ backend is specified. This is very similar to "queue" except that the size of
+ the farm is considered, in order to give a more accurate measurement of the
+ time it may take for a new connection to be processed. The main usage is with
+ ACL to return a sorry page to new users when it becomes certain they will get
+ a degraded service, or to pass to the backend servers in a header so that
+ they decide to work in degraded mode or to disable some functions to speed up
+ the processing a bit. Note that in the event there would not be any active
+ server anymore, twice the number of queued connections would be considered as
+ the measured value. This is a fair estimate, as we expect one server to get
+ back soon anyway, but we still prefer to send new traffic to another backend
+ if in better shape. See also the "queue", "be_conn", and "be_sess_rate"
+ sample fetches.
-be_conn <integer>
-be_conn(<backend>) <integer>
+be_conn([<backend>]) : integer
Applies to the number of currently established connections on the backend,
possibly including the connection being evaluated. If no backend name is
specified, the current one is used. But it is also possible to check another
backend. It can be used to use a specific farm when the nominal one is full.
See also the "fe_conn", "queue" and "be_sess_rate" criteria.
-be_id <integer>
- Applies to the backend's id. Can be used in frontends to check from which
- backend it was called.
-
-be_sess_rate <integer>
-be_sess_rate(<backend>) <integer>
- Returns true when the sessions creation rate on the backend matches the
- specified values or ranges, in number of new sessions per second. This is
- used to switch to an alternate backend when an expensive or fragile one
- reaches too high a session rate, or to limit abuse of service (eg. prevent
- sucking of an online dictionary).
+be_sess_rate([<backend>]) : integer
+ Returns an integer value corresponding to the sessions creation rate on the
+ backend, in number of new sessions per second. This is used with ACLs to
+ switch to an alternate backend when an expensive or fragile one reaches too
+ high a session rate, or to limit abuse of service (eg. prevent sucking of an
+ online dictionary). It can also be useful to add this element to logs using a
+ log-format directive.
Example :
# Redirect to an error page if the dictionary is requested too often
@@ -8505,21 +8769,12 @@
acl being_scanned be_sess_rate gt 100
redirect location /denied.html if being_scanned
-srv_sess_rate(<backend>/<server>) <integer>
- Returns true when the sessions creation rate on the server matches the
- specified values or ranges, in number of new sessions per second. This is
- used to switch to an alternate backend when an expensive or fragile one
- reaches too high a session rate, or to limit abuse of service (eg. prevent
- latent requests from overloading servers).
-
- Example :
- # Redirect to a separate back
- acl srv1_full srv_sess_rate(be1/srv1) gt 50
- acl srv2_full srv_sess_rate(be1/srv2) gt 50
- use_backend be2 if srv1_full or srv2_full
+connslots([<backend>]) : integer
+ Returns an integer value corresponding to the number of connection slots
+ still available in the backend, by totalizing the maximum amount of
+ connections on all servers and the maximum queue size. This is probably only
+ used with ACLs.
-connslots <integer>
-connslots(<backend>) <integer>
The basic idea here is to be able to measure the number of connection "slots"
still available (connection + queue), so that anything beyond that (intended
usage; see "use_backend" keyword) can be redirected to a different backend.
@@ -8529,55 +8784,36 @@
Note that while "fe_conn" may be used, "connslots" comes in especially
useful when you have a case of traffic going to one single ip, splitting into
- multiple backends (perhaps using acls to do name-based load balancing) and
+ multiple backends (perhaps using ACLs to do name-based load balancing) and
you want to be able to differentiate between different backends, and their
available "connslots". Also, whereas "nbsrv" only measures servers that are
- actually *down*, this acl is more fine-grained and looks into the number of
+ actually *down*, this fetch is more fine-grained and looks into the number of
available connection slots as well. See also "queue" and "avg_queue".
OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
- then this acl clearly does not make sense, in which case the value returned
+ then this fetch clearly does not make sense, in which case the value returned
will be -1.
-dst <ip_address>
- Applies to the local IPv4 or IPv6 address the client connected to. It can be
- used to switch to a different backend for some alternative addresses.
-
-dst_conn <integer>
- Applies to the number of currently established connections on the same socket
- including the one being evaluated. It can be used to either return a sorry
- page before hard-blocking, or to use a specific backend to drain new requests
- when the socket is considered saturated. This offers the ability to assign
- different limits to different listening ports or addresses. See also the
- "fe_conn" and "be_conn" criteria.
-
-dst_port <integer>
- Applies to the local port the client connected to. It can be used to switch
- to a different backend for some alternative ports.
-
-fe_conn <integer>
-fe_conn(<frontend>) <integer>
- Applies to the number of currently established connections on the frontend,
+fe_conn([<frontend>]) : integer
+ Returns the number of currently established connections on the frontend,
possibly including the connection being evaluated. If no frontend name is
specified, the current one is used. But it is also possible to check another
- frontend. It can be used to either return a sorry page before hard-blocking,
- or to use a specific backend to drain new requests when the farm is
- considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
- criteria.
-
-fe_id <integer>
- Applies to the frontend's id. Can be used in backends to check from which
- frontend it was called.
+ frontend. It can be used to return a sorry page before hard-blocking, or to
+ use a specific backend to drain new requests when the farm is considered
+ full. This is mostly used with ACLs but can also be used to pass some
+ statistics to servers in HTTP headers. See also the "dst_conn", "be_conn",
+ "fe_sess_rate" fetches.
-fe_sess_rate <integer>
-fe_sess_rate(<frontend>) <integer>
- Returns true when the session creation rate on the current or the named
- frontend matches the specified values or ranges, expressed in new sessions
- per second. This is used to limit the connection rate to acceptable ranges in
- order to prevent abuse of service at the earliest moment. This can be
- combined with layer 4 ACLs in order to force the clients to wait a bit for
- the rate to go down below the limit.
+fe_sess_rate([<frontend>]) : integer
+ Returns an integer value corresponding to the sessions creation rate on the
+ frontend, in number of new sessions per second. This is used with ACLs to
+ limit the incoming session rate to an acceptable range in order to prevent
+ abuse of service at the earliest moment, for example when combined with other
+ layer 4 ACLs in order to force the clients to wait a bit for the rate to go
+ down below the limit. It can also be useful to add this element to logs using
+ a log-format directive. See also the "rate-limit sessions" directive for use
+ in frontends.
Example :
# This frontend limits incoming mails to 10/s with a max of 100
@@ -8593,41 +8829,128 @@
tcp-request content accept if ! too_fast
tcp-request content accept if WAIT_END
-nbsrv <integer>
-nbsrv(<backend>) <integer>
- Returns true when the number of usable servers of either the current backend
- or the named backend matches the values or ranges specified. This is used to
+nbsrv([<backend>]) : integer
+ Returns an integer value corresponding to the number of usable servers of
+ either the current backend or the named backend. This is mostly used with
+ ACLs but can also be useful when added to logs. This is normally used to
switch to an alternate backend when the number of servers is too low to
to handle some load. It is useful to report a failure when combined with
"monitor fail".
-queue <integer>
-queue(<backend>) <integer>
+queue([<backend>]) : integer
Returns the total number of queued connections of the designated backend,
including all the connections in server queues. If no backend name is
specified, the current one is used, but it is also possible to check another
- one. This can be used to take actions when queuing goes above a known level,
- generally indicating a surge of traffic or a massive slowdown on the servers.
- One possible action could be to reject new users but still accept old ones.
- See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
+ one. This is useful with ACLs or to pass statistics to backend servers. This
+ can be used to take actions when queuing goes above a known level, generally
+ indicating a surge of traffic or a massive slowdown on the servers. One
+ possible action could be to reject new users but still accept old ones. See
+ also the "avg_queue", "be_conn", and "be_sess_rate" fetches.
+
+srv_conn([<backend>/]<server>) : integer
+ Returns an integer value corresponding to the number of currently established
+ connections on the designated server, possibly including the connection being
+ evaluated. If <backend> is omitted, then the server is looked up in the
+ current backend. It can be used to use a specific farm when one server is
+ full, or to inform the server about our view of the number of active
+ connections with it. See also the "fe_conn", "be_conn" and "queue" fetch
+ methods.
+
+srv_is_up([<backend>/]<server>) : boolean
+ Returns true when the designated server is UP, and false when it is either
+ DOWN or in maintenance mode. If <backend> is omitted, then the server is
+ looked up in the current backend. It is mainly used to take action based on
+ an external status reported via a health check (eg: a geographical site's
+ availability). Another possible use which is more of a hack consists in
+ using dummy servers as boolean variables that can be enabled or disabled from
+ the CLI, so that rules depending on those ACLs can be tweaked in realtime.
+
+srv_sess_rate([<backend>/]<server>) : integer
+ Returns an integer corresponding to the sessions creation rate on the
+ designated server, in number of new sessions per second. If <backend> is
+ omitted, then the server is looked up in the current backend. This is mosly
+ used with ACLs but can make sense with logs too. This is used to switch to an
+ alternate backend when an expensive or fragile one reaches too high a session
+ rate, or to limit abuse of service (eg. prevent latent requests from
+ overloading servers).
+
+ Example :
+ # Redirect to a separate back
+ acl srv1_full srv_sess_rate(be1/srv1) gt 50
+ acl srv2_full srv_sess_rate(be1/srv2) gt 50
+ use_backend be2 if srv1_full or srv2_full
+
+table_avl([<table>]) : integer
+ Returns the total number of available entries in the current proxy's
+ stick-table or in the designated stick-table. See also table_cnt.
+
+table_cnt([<table>]) : integer
+ Returns the total number of entries currently in use in the current proxy's
+ stick-table or in the designated stick-table. See also src_conn_cnt and
+ table_avl for other entry counting methods.
+
+
+7.3.2. Fetching samples at Layer 4
+----------------------------------
+
+The layer 4 usually describes just the transport layer which in haproxy is
+closest to the connection, where no content is yet made available. The fetch
+methods described here are usable as low as the "tcp-request connection" rule
+sets unless they require some future information. Those generally include
+TCP/IP addresses and ports, as well as elements from stick-tables related to
+the incoming connection.
+
+be_id : integer
+ Returns an integer containing the current backend's id. It can be used in
+ frontends with responses to check which backend processed the request.
+
+dst : ip
+ This is the destination IPv4 address of the connection on the client side,
+ which is the address the client connected to. It can be useful when running
+ in transparent mode. It is of type IP and works on both IPv4 and IPv6 tables.
+ On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent, according to
+ RFC 4291.
+
+dst_conn : integer
+ Returns an integer value corresponding to the number of currently established
+ connections on the same socket including the one being evaluated. It is
+ normally used with ACLs but can as well be used to pass the information to
+ servers in an HTTP header or in logs. It can be used to either return a sorry
+ page before hard-blocking, or to use a specific backend to drain new requests
+ when the socket is considered saturated. This offers the ability to assign
+ different limits to different listening ports or addresses. See also the
+ "fe_conn" and "be_conn" fetches.
-sc1_bytes_in_rate <integer>
-sc2_bytes_in_rate <integer>
-sc3_bytes_in_rate <integer>
+dst_port : integer
+ Returns an integer value corresponding to the destination TCP port of the
+ connection on the client side, which is the port the client connected to.
+ This might be used when running in transparent mode, when assigning dynamic
+ ports to some clients for a whole application session, to stick all users to
+ a same server, or to pass the destination port information to a server using
+ an HTTP header.
+
+fe_id : integer
+ Returns an integer containing the current frontend's id. It can be used in
+ backends to check from which backend it was called, or to stick all users
+ coming via a same frontend to the same server.
+
+sc1_bytes_in_rate : integer
+sc2_bytes_in_rate : integer
+sc3_bytes_in_rate : integer
Returns the average client-to-server bytes rate from the currently tracked
counters, measured in amount of bytes over the period configured in the
table. See also src_bytes_in_rate.
-sc1_bytes_out_rate <integer>
-sc2_bytes_out_rate <integer>
-sc3_bytes_out_rate <integer>
+sc1_bytes_out_rate : integer
+sc2_bytes_out_rate : integer
+sc3_bytes_out_rate : integer
Returns the average server-to-client bytes rate from the currently tracked
counters, measured in amount of bytes over the period configured in the
table. See also src_bytes_out_rate.
-sc1_clr_gpc0 <integer>
-sc2_clr_gpc0 <integer>
-sc3_clr_gpc0 <integer>
+sc1_clr_gpc0 : integer
+sc2_clr_gpc0 : integer
+sc3_clr_gpc0 : integer
Clears the first General Purpose Counter associated to the currently tracked
counters, and returns its previous value. Before the first invocation, the
stored value is zero, so first invocation will always return zero. This is
@@ -8642,35 +8965,35 @@
tcp-request connection accept if !abuse save
tcp-request connection reject if abuse kill
-sc1_conn_cnt <integer>
-sc2_conn_cnt <integer>
-sc3_conn_cnt <integer>
+sc1_conn_cnt : integer
+sc2_conn_cnt : integer
+sc3_conn_cnt : integer
Returns the cumulated number of incoming connections from currently tracked
counters. See also src_conn_cnt.
-sc1_conn_cur <integer>
-sc2_conn_cur <integer>
-sc3_conn_cur <integer>
+sc1_conn_cur : integer
+sc2_conn_cur : integer
+sc3_conn_cur : integer
Returns the current amount of concurrent connections tracking the same
tracked counters. This number is automatically incremented when tracking
begins and decremented when tracking stops. See also src_conn_cur.
-sc1_conn_rate <integer>
-sc2_conn_rate <integer>
-sc3_conn_rate <integer>
+sc1_conn_rate : integer
+sc2_conn_rate : integer
+sc3_conn_rate : integer
Returns the average connection rate from the currently tracked counters,
measured in amount of connections over the period configured in the table.
See also src_conn_rate.
-sc1_get_gpc0 <integer>
-sc2_get_gpc0 <integer>
-sc3_get_gpc0 <integer>
+sc1_get_gpc0 : integer
+sc2_get_gpc0 : integer
+sc3_get_gpc0 : integer
Returns the value of the first General Purpose Counter associated to the
currently tracked counters. See also src_get_gpc0 and sc1/sc2/sc3_get_gpc0.
-sc1_gpc0_rate <integer>
-sc2_gpc0_rate <integer>
-sc3_gpc0_rate <integer>
+sc1_gpc0_rate : integer
+sc2_gpc0_rate : integer
+sc3_gpc0_rate : integer
Returns the average increment rate of the first General Purpose Counter
associated to the currently tracked counters. It reports the frequency
which the gpc0 counter was incremented over the configured period. See also
@@ -8678,39 +9001,39 @@
"gpc0_rate" counter must be stored in the stick-table for a value to be
returned, as "gpc0" only holds the event count.
-sc1_http_err_cnt <integer>
-sc2_http_err_cnt <integer>
-sc3_http_err_cnt <integer>
+sc1_http_err_cnt : integer
+sc2_http_err_cnt : integer
+sc3_http_err_cnt : integer
Returns the cumulated number of HTTP errors from the currently tracked
counters. This includes the both request errors and 4xx error responses.
See also src_http_err_cnt.
-sc1_http_err_rate <integer>
-sc2_http_err_rate <integer>
-sc3_http_err_rate <integer>
+sc1_http_err_rate : integer
+sc2_http_err_rate : integer
+sc3_http_err_rate : integer
Returns the average rate of HTTP errors from the currently tracked counters,
measured in amount of errors over the period configured in the table. This
includes the both request errors and 4xx error responses. See also
src_http_err_rate.
-sc1_http_req_cnt <integer>
-sc2_http_req_cnt <integer>
-sc3_http_req_cnt <integer>
+sc1_http_req_cnt : integer
+sc2_http_req_cnt : integer
+sc3_http_req_cnt : integer
Returns the cumulated number of HTTP requests from the currently tracked
counters. This includes every started request, valid or not. See also
src_http_req_cnt.
-sc1_http_req_rate <integer>
-sc2_http_req_rate <integer>
-sc3_http_req_rate <integer>
+sc1_http_req_rate : integer
+sc2_http_req_rate : integer
+sc3_http_req_rate : integer
Returns the average rate of HTTP requests from the currently tracked
counters, measured in amount of requests over the period configured in
the table. This includes every started request, valid or not. See also
src_http_req_rate.
-sc1_inc_gpc0 <integer>
-sc2_inc_gpc0 <integer>
-sc3_inc_gpc0 <integer>
+sc1_inc_gpc0 : integer
+sc2_inc_gpc0 : integer
+sc3_inc_gpc0 : integer
Increments the first General Purpose Counter associated to the currently
tracked counters, and returns its new value. Before the first invocation,
the stored value is zero, so first invocation will increase it to 1 and will
@@ -8721,25 +9044,25 @@
acl kill sc1_inc_gpc0 gt 0
tcp-request connection reject if abuse kill
-sc1_kbytes_in <integer>
-sc2_kbytes_in <integer>
-sc3_kbytes_in <integer>
+sc1_kbytes_in : integer
+sc2_kbytes_in : integer
+sc3_kbytes_in : integer
Returns the amount of client-to-server data from the currently tracked
counters, measured in kilobytes over the period configured in the table. The
test is currently performed on 32-bit integers, which limits values to 4
terabytes. See also src_kbytes_in.
-sc1_kbytes_out <integer>
-sc2_kbytes_out <integer>
-sc3_kbytes_out <integer>
+sc1_kbytes_out : integer
+sc2_kbytes_out : integer
+sc3_kbytes_out : integer
Returns the amount of server-to-client data from the currently tracked
counters, measured in kilobytes over the period configured in the table. The
test is currently performed on 32-bit integers, which limits values to 4
terabytes. See also src_kbytes_out.
-sc1_sess_cnt <integer>
-sc2_sess_cnt <integer>
-sc3_sess_cnt <integer>
+sc1_sess_cnt : integer
+sc2_sess_cnt : integer
+sc3_sess_cnt : integer
Returns the cumulated number of incoming connections that were transformed
into sessions, which means that they were accepted by a "tcp-request
connection" rule, from the currently tracked counters. A backend may count
@@ -8747,9 +9070,9 @@
backend sessions if some HTTP keep-alive is performed over the connection
with the client. See also src_sess_cnt.
-sc1_sess_rate <integer>
-sc2_sess_rate <integer>
-sc3_sess_rate <integer>
+sc1_sess_rate : integer
+sc2_sess_rate : integer
+sc3_sess_rate : integer
Returns the average session rate from the currently tracked counters,
measured in amount of sessions over the period configured in the table. A
session is a connection that got past the early "tcp-request connection"
@@ -8757,52 +9080,58 @@
connection could result in many backend sessions if some HTTP keep-alive is
performed over the connection with the client. See also src_sess_rate.
-sc1_tracked
-sc2_tracked
-sc3_tracked
+sc1_tracked : boolean
+sc2_tracked : boolean
+sc3_tracked : boolean
Returns true if the designated session counter is currently being tracked by
the current session. This can be useful when deciding whether or not we want
to set some values in a header passed to the server.
-sc1_trackers <integer>
-sc2_trackers <integer>
-sc3_trackers <integer>
+sc1_trackers : integer
+sc2_trackers : integer
+sc3_trackers : integer
Returns the current amount of concurrent connections tracking the same
tracked counters. This number is automatically incremented when tracking
begins and decremented when tracking stops. It differs from sc1_conn_cur in
that it does not rely on any stored information but on the table's reference
count (the "use" value which is returned by "show table" on the CLI). This
- may sometimes be more suited for layer7 tracking.
+ may sometimes be more suited for layer7 tracking. It can be used to tell a
+ server how many concurrent connections there are from a given address for
+ example.
-so_id <integer>
- Applies to the socket's id. Useful in frontends with many bind keywords.
+so_id : integer
+ Returns an integer containing the current listening socket's id. It is useful
+ in frontends involving many "bind" lines, or to stick all users coming via a
+ same socket to the same server.
-src <ip_address>
- Applies to the client's IPv4 or IPv6 address. It is usually used to limit
- access to certain resources such as statistics. Note that it is the TCP-level
- source address which is used, and not the address of a client behind a proxy.
+src : ip
+ This is the source IPv4 address of the client of the session. It is of type
+ IP and works on both IPv4 and IPv6 tables. On IPv6 tables, IPv4 addresses are
+ mapped to their IPv6 equivalent, according to RFC 4291. Note that it is the
+ TCP-level source address which is used, and not the address of a client
+ behind a proxy. However if the "accept-proxy" bind directive is used, it can
+ be the address of a client behind another PROXY-protocol compatible component
+ for all rule sets except "tcp-request connection" which sees the real address.
-src_bytes_in_rate <integer>
-src_bytes_in_rate(<table>) <integer>
- Returns the average bytes rate from the connection's source IPv4 address in
- the current proxy's stick-table or in the designated stick-table, measured in
- amount of bytes over the period configured in the table. If the address is
- not found, zero is returned. See also sc1/sc2_bytes_in_rate.
+src_bytes_in_rate([<table>]) : integer
+ Returns the average bytes rate from the incoming connection's source address
+ in the current proxy's stick-table or in the designated stick-table, measured
+ in amount of bytes over the period configured in the table. If the address is
+ not found, zero is returned. See also sc1/sc2/sc3_bytes_in_rate.
-src_bytes_out_rate <integer>
-src_bytes_out_rate(<table>) <integer>
- Returns the average bytes rate to the connection's source IPv4 address in the
- current proxy's stick-table or in the designated stick-table, measured in
+src_bytes_out_rate([<table>]) : integer
+ Returns the average bytes rate to the incoming connection's source address in
+ the current proxy's stick-table or in the designated stick-table, measured in
amount of bytes over the period configured in the table. If the address is
- not found, zero is returned. See also sc1/sc2_bytes_out_rate.
+ not found, zero is returned. See also sc1/sc2/sc3_bytes_out_rate.
-src_clr_gpc0 <integer>
-src_clr_gpc0(<table>) <integer>
- Clears the first General Purpose Counter associated to the connection's
- source IPv4 address in the current proxy's stick-table or in the designated
- stick-table, and returns its previous value. If the address is not found, an
- entry is created and 0 is returned. This is typically used as a second ACL in
- an expression in order to mark a connection when a first ACL was verified :
+src_clr_gpc0([<table>]) : integer
+ Clears the first General Purpose Counter associated to the incoming
+ connection's source address in the current proxy's stick-table or in the
+ designated stick-table, and returns its previous value. If the address is not
+ found, an entry is created and 0 is returned. This is typically used as a
+ second ACL in an expression in order to mark a connection when a first ACL
+ was verified :
# block if 5 consecutive requests continue to come faster than 10 sess
# per second, and reset the counter as soon as the traffic slows down.
@@ -8812,130 +9141,121 @@
tcp-request connection accept if !abuse save
tcp-request connection reject if abuse kill
-src_conn_cnt <integer>
-src_conn_cnt(<table>) <integer>
+src_conn_cnt([<table>]) : integer
Returns the cumulated number of connections initiated from the current
- connection's source IPv4 address in the current proxy's stick-table or in
+ incoming connection's source address in the current proxy's stick-table or in
the designated stick-table. If the address is not found, zero is returned.
- See also sc1/sc2_conn_cnt.
+ See also sc1/sc2/sc3_conn_cnt.
-src_conn_cur <integer>
-src_conn_cur(<table>) <integer>
+src_conn_cur([<table>]) : integer
Returns the current amount of concurrent connections initiated from the
- current connection's source IPv4 address in the current proxy's stick-table
- or in the designated stick-table. If the address is not found, zero is
- returned. See also sc1/sc2_conn_cur.
+ current incoming connection's source address in the current proxy's
+ stick-table or in the designated stick-table. If the address is not found,
+ zero is returned. See also sc1/sc2/sc3_conn_cur.
-src_conn_rate <integer>
-src_conn_rate(<table>) <integer>
- Returns the average connection rate from the connection's source IPv4 address
- in the current proxy's stick-table or in the designated stick-table, measured
- in amount of connections over the period configured in the table. If the
- address is not found, zero is returned. See also sc1/sc2_conn_rate.
+src_conn_rate([<table>]) : integer
+ Returns the average connection rate from the incoming connection's source
+ address in the current proxy's stick-table or in the designated stick-table,
+ measured in amount of connections over the period configured in the table. If
+ the address is not found, zero is returned. See also sc1/sc2/sc3_conn_rate.
-src_get_gpc0 <integer>
-src_get_gpc0(<table>) <integer>
+src_get_gpc0([<table>]) : integer
Returns the value of the first General Purpose Counter associated to the
- connection's source IPv4 address in the current proxy's stick-table or in
+ incoming connection's source address in the current proxy's stick-table or in
the designated stick-table. If the address is not found, zero is returned.
- See also sc1/sc2_get_gpc0 and src_inc_gpc0.
+ See also sc1/sc2/sc3_get_gpc0 and src_inc_gpc0.
-src_gpc0_rate <integer>
-src_gpc0_rate(<table>) <integer>
+src_gpc0_rate([<table>]) : integer
Returns the average increment rate of the first General Purpose Counter
- associated to the connection's source IPv4 address in the current proxy's
+ associated to the incoming connection's source address in the current proxy's
stick-table or in the designated stick-table. It reports the frequency
which the gpc0 counter was incremented over the configured period. See also
sc1/sc2/sc3_gpc0_rate, src_get_gpc0, and sc1/sc2/sc3_inc_gpc0. Note that the
"gpc0_rate" counter must be stored in the stick-table for a value to be
returned, as "gpc0" only holds the event count.
-src_http_err_cnt <integer>
-src_http_err_cnt(<table>) <integer>
- Returns the cumulated number of HTTP errors from the current connection's
- source IPv4 address in the current proxy's stick-table or in the designated
+src_http_err_cnt([<table>]) : integer
+ Returns the cumulated number of HTTP errors from the incoming connection's
+ source address in the current proxy's stick-table or in the designated
stick-table. This includes the both request errors and 4xx error responses.
- If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt.
+ See also sc1/sc2/sc3_http_err_cnt. If the address is not found, zero is
+ returned.
-src_http_err_rate <integer>
-src_http_err_rate(<table>) <integer>
- Returns the average rate of HTTP errors from the current connection's source
- IPv4 address in the current proxy's stick-table or in the designated stick-
- table, measured in amount of errors over the period configured in the table.
- This includes the both request errors and 4xx error responses. If the address
- is not found, zero is returned. See also sc1/sc2_http_err_rate.
+src_http_err_rate([<table>]) : integer
+ Returns the average rate of HTTP errors from the incoming connection's source
+ address in the current proxy's stick-table or in the designated stick-table,
+ measured in amount of errors over the period configured in the table. This
+ includes the both request errors and 4xx error responses. If the address is
+ not found, zero is returned. See also sc1/sc2/sc3_http_err_rate.
-src_http_req_cnt <integer>
-src_http_req_cnt(<table>) <integer>
- Returns the cumulated number of HTTP requests from the current connection's
- source IPv4 address in the current proxy's stick-table or in the designated
- stick-table. This includes every started request, valid or not. If the
- address is not found, zero is returned. See also sc1/sc2_http_req_cnt.
+src_http_req_cnt([<table>]) : integer
+ Returns the cumulated number of HTTP requests from the incoming connection's
+ source address in the current proxy's stick-table or in the designated stick-
+ table. This includes every started request, valid or not. If the address is
+ not found, zero is returned. See also sc1/sc2/sc3_http_req_cnt.
-src_http_req_rate <integer>
-src_http_req_rate(<table>) <integer>
- Returns the average rate of HTTP requests from the current connection's
- source IPv4 address in the current proxy's stick-table or in the designated
- stick-table, measured in amount of requests over the period configured in the
+src_http_req_rate([<table>]) : integer
+ Returns the average rate of HTTP requests from the incoming connection's
+ source address in the current proxy's stick-table or in the designated stick-
+ table, measured in amount of requests over the period configured in the
table. This includes every started request, valid or not. If the address is
- not found, zero is returned. See also sc1/sc2_http_req_rate.
+ not found, zero is returned. See also sc1/sc2/sc3_http_req_rate.
-src_inc_gpc0 <integer>
-src_inc_gpc0(<table>) <integer>
- Increments the first General Purpose Counter associated to the connection's
- source IPv4 address in the current proxy's stick-table or in the designated
- stick-table, and returns its new value. If the address is not found, an entry
- is created and 1 is returned. This is typically used as a second ACL in an
- expression in order to mark a connection when a first ACL was verified :
+src_inc_gpc0([<table>]) : integer
+ Increments the first General Purpose Counter associated to the incoming
+ connection's source address in the current proxy's stick-table or in the
+ designated stick-table, and returns its new value. If the address is not
+ found, an entry is created and 1 is returned. See also sc1/sc3/sc3_inc_gpc0.
+ This is typically used as a second ACL in an expression in order to mark a
+ connection when a first ACL was verified :
acl abuse src_http_req_rate gt 10
acl kill src_inc_gpc0 gt 0
tcp-request connection reject if abuse kill
-src_kbytes_in <integer>
-src_kbytes_in(<table>) <integer>
- Returns the amount of data received from the connection's source IPv4 address
- in the current proxy's stick-table or in the designated stick-table, measured
- in kilobytes over the period configured in the table. If the address is not
- found, zero is returned. The test is currently performed on 32-bit integers,
- which limits values to 4 terabytes. See also sc1/sc2_kbytes_in.
+src_kbytes_in([<table>]) : integer
+ Returns the amount of data received from the incoming connection's source
+ address in the current proxy's stick-table or in the designated stick-table,
+ measured in kilobytes over the period configured in the table. If the address
+ is not found, zero is returned. The test is currently performed on 32-bit
+ integers, which limits values to 4 terabytes. See also sc1/sc2/sc3_kbytes_in.
-src_kbytes_out <integer>
-src_kbytes_out(<table>) <integer>
- Returns the amount of data sent to the connection's source IPv4 address in
- the current proxy's stick-table or in the designated stick-table, measured
+src_kbytes_out([<table>]) : integer
+ Returns the amount of data sent to the incoming connection's source address
+ in the current proxy's stick-table or in the designated stick-table, measured
in kilobytes over the period configured in the table. If the address is not
found, zero is returned. The test is currently performed on 32-bit integers,
- which limits values to 4 terabytes. See also sc1/sc2_kbytes_out.
+ which limits values to 4 terabytes. See also sc1/sc2/sc3_kbytes_out.
-src_port <integer>
- Applies to the client's TCP source port. This has a very limited usage.
+src_port : integer
+ Returns an integer value corresponding to the TCP source port of the
+ connection on the client side, which is the port the client connected from.
+ Usage of this function is very limited as modern protocols do not care much
+ about source ports nowadays.
-src_sess_cnt <integer>
-src_sess_cnt(<table>) <integer>
- Returns the cumulated number of connections initiated from the current
+src_sess_cnt([<table>]) : integer
+ Returns the cumulated number of connections initiated from the incoming
connection's source IPv4 address in the current proxy's stick-table or in the
designated stick-table, that were transformed into sessions, which means that
they were accepted by "tcp-request" rules. If the address is not found, zero
- is returned. See also sc1/sc2_sess_cnt.
+ is returned. See also sc1/sc2/sc3_sess_cnt.
-src_sess_rate <integer>
-src_sess_rate(<table>) <integer>
- Returns the average session rate from the connection's source IPv4 address in
- the current proxy's stick-table or in the designated stick-table, measured in
- amount of sessions over the period configured in the table. A session is a
- connection that got past the early "tcp-request" rules. If the address is not
- found, zero is returned. See also sc1/sc2_sess_rate.
+src_sess_rate([<table>]) : integer
+ Returns the average session rate from the incoming connection's source
+ address in the current proxy's stick-table or in the designated stick-table,
+ measured in amount of sessions over the period configured in the table. A
+ session is a connection that went past the early "tcp-request" rules. If the
+ address is not found, zero is returned. See also sc1/sc2/sc3_sess_rate.
-src_updt_conn_cnt <integer>
-src_updt_conn_cnt(<table>) <integer>
- Creates or updates the entry associated to the source IPv4 address in the
- current proxy's stick-table or in the designated stick-table. This table
- must be configured to store the "conn_cnt" data type, otherwise the match
- will be ignored. The current count is incremented by one, and the expiration
- timer refreshed. The updated count is returned, so this match can't return
- zero. This is used to reject service abusers based on their source address.
- Note: it is recommended to use the more complete "track-counters" instead.
+src_updt_conn_cnt([<table>]) : integer
+ Creates or updates the entry associated to the incoming connection's source
+ address in the current proxy's stick-table or in the designated stick-table.
+ This table must be configured to store the "conn_cnt" data type, otherwise
+ the match will be ignored. The current count is incremented by one, and the
+ expiration timer refreshed. The updated count is returned, so this match
+ can't return zero. This was used to reject service abusers based on their
+ source address. Note: it is recommended to use the more complete "track-sc*"
+ actions in "tcp-request" rules instead.
Example :
# This frontend limits incoming SSH connections to 3 per 10 second for
@@ -8946,288 +9266,237 @@
mode tcp
maxconn 100
stick-table type ip size 20 expire 10s store conn_cnt
- tcp-request content reject if { src_update_count gt 3 }
+ tcp-request content reject if { src_updt_conn_cnt gt 3 }
server local 127.0.0.1:22
-srv_conn(<backend>/<server>) <integer>
- Applies to the number of currently established connections on the server,
- possibly including the connection being evaluated.
- It can be used to use a specific farm when one server is full.
- See also the "fe_conn", "be_conn" and "queue" criteria.
+srv_id : integer
+ Returns an integer containing the server's id when processing the response.
+ While it's almost only used with ACLs, it may be used for logging or
+ debugging.
-srv_id <integer>
- Applies to the server's id. Can be used in frontends or backends.
-srv_is_up(<server>)
-srv_is_up(<backend>/<server>)
- Returns true when the designated server is UP, and false when it is either
- DOWN or in maintenance mode. If <backend> is omitted, then the server is
- looked up in the current backend. The function takes no arguments since it
- is used as a boolean. It is mainly used to take action based on an external
- status reported via a health check (eg: a geographical site's availability).
- Another possible use which is more of a hack consists in using dummy servers
- as boolean variables that can be enabled or disabled from the CLI, so that
- rules depending on those ACLs can be tweaked in realtime.
+7.3.3. Fetching samples at Layer 5
+----------------------------------
-table_avl <integer>
-table_avl(<table>) <integer>
- Returns the total number of available entries in the current proxy's
- stick-table or in the designated stick-table. See also table_cnt.
+The layer 5 usually describes just the session layer which in haproxy is
+closest to the session once all the connection handshakes are finished, but
+when no content is yet made available. The fetch methods described here are
+usable as low as the "tcp-request content" rule sets unless they require some
+future information. Those generally include the results of SSL negociations.
-table_cnt <integer>
-table_cnt(<table>) <integer>
- Returns the total number of entries currently in use in the current proxy's
- stick-table or in the designated stick-table. See also src_conn_cnt and
- table_avl for other entry counting methods.
+ssl_c_ca_err : integer
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the ID of the first error detected during verification of the client
+ certificate at depth > 0, or 0 if no error was encountered during this
+ verification process. Please refer to your SSL library's documentation to
+ find the exhaustive list of error codes.
+ssl_c_ca_err_depth : integer
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the depth in the CA chain of the first error detected during the
+ verification of the client certificate. If no error is encountered, 0 is
+ returned.
-7.5.2. Matching contents at Layer 4 (also called Layer 6)
----------------------------------------------------------
+ssl_c_err : integer
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the ID of the first error detected during verification at depth 0, or
+ 0 if no error was encountered during this verification process. Please refer
+ to your SSL library's documentation to find the exhaustive list of error
+ codes.
-A second set of criteria depends on data found in buffers, but which can change
-during analysis. This requires that some data has been buffered, for instance
-through TCP request content inspection. Please see the "tcp-request content"
-keyword for more detailed information on the subject.
+ssl_c_i_dn([<entry>[,<occ>]]) : string
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the full distinguished name of the issuer of the certificate
+ presented by the client when no <entry> is specified, or the value of the
+ first given entry found from the beginning of the DN. If a positive/negative
+ occurrence number is specified as the optional second argument, it returns
+ the value of the nth given entry value from the beginning/end of the DN.
+ For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
+ "ssl_c_i_dn(CN)" retrieves the common name.
-rep_ssl_hello_type <integer>
- Returns true when data in the response buffer looks like a complete SSL (v3
- or superior) hello message and handshake type is equal to <integer>.
- This test was designed to be used with TCP response content inspection: a
- SSL session ID may be fetched. Note that this only applies to raw contents
- found in the response buffer and not to contents deciphered via an SSL data
- layer, so this will not work with "server" lines having the "ssl" option.
+ ACL derivatives :
+ ssl_c_i_dn([<entry>[,<occ>]]) : exact string match
-req_len <integer>
- Returns true when the length of the data in the request buffer matches the
- specified range. It is important to understand that this test does not
- return false as long as the buffer is changing. This means that a check with
- equality to zero will almost always immediately match at the beginning of the
- session, while a test for more data will wait for that data to come in and
- return false only when haproxy is certain that no more data will come in.
- This test was designed to be used with TCP request content inspection.
+ssl_c_key_alg : string
+ Returns the name of the algorithm used to generate the key of the certificate
+ presented by the client when the incoming connection was made over an SSL/TLS
+ transport layer.
-req_proto_http
- Returns true when data in the request buffer look like HTTP and correctly
- parses as such. It is the same parser as the common HTTP request parser which
- is used so there should be no surprises. This test can be used for instance
- to direct HTTP traffic to a given port and HTTPS traffic to another one
- using TCP request content inspection rules.
+ ACL derivatives :
+ ssl_c_key_alg : exact string match
-req_rdp_cookie <string>
-req_rdp_cookie(<name>) <string>
- Returns true when data in the request buffer look like the RDP protocol, and
- a cookie is present and equal to <string>. By default, any cookie name is
- checked, but a specific cookie name can be specified in parenthesis. The
- parser only checks for the first cookie, as illustrated in the RDP protocol
- specification. The cookie name is case insensitive. This ACL can be useful
- with the "MSTS" cookie, as it can contain the user name of the client
- connecting to the server if properly configured on the client. This can be
- used to restrict access to certain servers to certain users.
+ssl_c_notafter : string
+ Returns the end date presented by the client as a formatted string
+ YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
+ transport layer.
-req_rdp_cookie_cnt <integer>
-req_rdp_cookie_cnt(<name>) <integer>
- Returns true when the data in the request buffer look like the RDP protocol
- and the number of RDP cookies matches the specified range (typically zero or
- one). Optionally a specific cookie name can be checked. This is a simple way
- of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH
- cookies.
+ ACL derivatives :
+ ssl_c_notafter : exact string match
-req_ssl_hello_type <integer>
- Returns true when data in the request buffer looks like a complete SSL (v3
- or superior) hello message and handshake type is equal to <integer>.
- This test was designed to be used with TCP request content inspection: an
- SSL session ID may be fetched. Note that this only applies to raw contents
- found in the request buffer and not to contents deciphered via an SSL data
- layer, so this will not work with "bind" lines having the "ssl" option.
+ssl_c_notbefore : string
+ Returns the start date presented by the client as a formatted string
+ YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
+ transport layer.
-req_ssl_sni <string>
- Returns true when data in the request buffer looks like a complete SSL (v3
- or superior) client hello message with a Server Name Indication TLS extension
- (SNI) matching <string>. SNI normally contains the name of the host the
- client tries to connect to (for recent browsers). SNI is useful for allowing
- or denying access to certain hosts when SSL/TLS is used by the client. This
- test was designed to be used with TCP request content inspection. If content
- switching is needed, it is recommended to first wait for a complete client
- hello (type 1), like in the example below. Note that this only applies to raw
- contents found in the request buffer and not to contents deciphered via an
- SSL transport layer, so this will not work with "bind" lines having the "ssl"
- option. See also "ssl_sni" below.
+ ACL derivatives :
+ ssl_c_notbefore : exact string match
- Examples :
- # Wait for a client hello for at most 5 seconds
- tcp-request inspect-delay 5s
- tcp-request content accept if { req_ssl_hello_type 1 }
- use_backend bk_allow if { req_ssl_sni -f allowed_sites }
- default_backend bk_sorry_page
+ssl_c_s_dn([<entry>[,<occ>]]) : string
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the full distinguished name of the subject of the certificate
+ presented by the client when no <entry> is specified, or the value of the
+ first given entry found from the beginning of the DN. If a positive/negative
+ occurrence number is specified as the optional second argument, it returns
+ the value of the nth given entry value from the beginning/end of the DN.
+ For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
+ "ssl_c_s_dn(CN)" retrieves the common name.
-req_ssl_ver <decimal>
- Returns true when data in the request buffer look like SSL, with a protocol
- version matching the specified range. Both SSLv2 hello messages and SSLv3
- messages are supported. The test tries to be strict enough to avoid being
- easily fooled. In particular, it waits for as many bytes as announced in the
- message header if this header looks valid (bound to the buffer size). Note
- that TLSv1 is announced as SSL version 3.1. This test was designed to be used
- with TCP request content inspection. Note that this only applies to raw
- contents found in the request buffer and not to contents deciphered via an
- SSL transport layer, so this will not work with "bind" lines having the "ssl"
- option.
+ ACL derivatives :
+ ssl_c_s_dn([<entry>[,<occ>]]) : exact string match
-ssl_c_ca_err <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the ID of the first error detected during verification of the
- client certificate at depth > 0 matches the specified value (check man verify
- for possible values). Note that error zero means no error was encountered
- during this verification process.
+ssl_c_serial : binary
+ Returns the serial of the certificate presented by the client when the
+ incoming connection was made over an SSL/TLS transport layer. When used for
+ an ACL, the value(s) to match against can be passed in hexadecimal form.
-ssl_c_ca_err_depth <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the depth in the CA chain of the first error detected during the
- verification of the client certificate matches the specified value. When no
- error is found, depth 0 is returned.
+ ACL derivatives :
+ ssl_c_serial : hex block match
-ssl_c_err <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the ID of the first error detected during verification at depth==0
- matches the specified value (check man verify for possible values). Note that
- error zero means no error was encountered during this verification process.
+ssl_c_sha1 : binary
+ Returns the SHA-1 fingerprint of the certificate presented by the client when
+ the incoming connection was made over an SSL/TLS transport layer. This can be
+ used to stick a client to a server, or to pass this information to a server.
-ssl_c_i_dn <string>
-ssl_c_i_dn(entry[,occ]) <string>
- If no entry specified, returns true when the incoming connection was made
- over an SSL/TLS transport layer, and the full distinguished name of the
- issuer of the certificate presented by the client matches the specified
- string. Otherwise returns true if the value of the first given entry from
- the beginning of the DN matches the specified string. If a positive/negative
- occurrence number is specified as the optional second argument, it returns
- true if the value of the nth given entry value from the beginning/end of the
- DN matches the specified string.
+ssl_c_sig_alg : string
+ Returns the name of the algorithm used to sign the certificate presented by
+ the client when the incoming connection was made over an SSL/TLS transport
+ layer.
-ssl_c_key_alg <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the name of the algorithm used to generate the key of the
- certificate presented by the client matches the string.
+ ACL derivatives :
+ ssl_c_sig_alg : exact string match
+
+ssl_c_used : boolean
+ Returns true if current SSL session uses a client certificate even if current
+ connection uses SSL session resumption. See also "ssl_fc_has_crt".
-ssl_c_notafter <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the end date of the certificate presented by the client matches
- the string formatted as YYMMDDhhmmss[Z].
+ssl_c_verify : integer
+ Returns the verify result error ID when the incoming connection was made over
+ an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
+ refer to your SSL library's documentation for an exhaustive list of error
+ codes.
-ssl_c_notbefore <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the start date of the certificate presented by the client matches
- the string formatted as YYMMDDhhmmss[Z].
+ssl_c_version : integer
+ Returns the version of the certificate presented by the client when the
+ incoming connection was made over an SSL/TLS transport layer.
-ssl_c_s_dn <string>
-ssl_c_s_dn(entry[,occ]) <string>
- If no entry specified, returns true when the incoming connection was made
- over an SSL/TLS transport layer, and the full distinguished name of the
- subject of the certificate presented by the client matches the specified
- string. Otherwise returns true if the value of the first given entry from
- the beginning of the DN matches the specified string. If a positive/negative
+ssl_f_i_dn([<entry>[,<occ>]]) : string
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the full distinguished name of the issuer of the certificate
+ presented by the frontend when no <entry> is specified, or the value of the
+ first given entry found from the beginning of the DN. If a positive/negative
occurrence number is specified as the optional second argument, it returns
- true if the value of the nth given entry value from the beginning/end of the
- DN matches the specified string.
+ the value of the nth given entry value from the beginning/end of the DN.
+ For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
+ "ssl_f_i_dn(CN)" retrieves the common name.
-ssl_c_serial <hexa>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the serial of the certificate presented by the client matches
- the value written in hexa.
+ ACL derivatives :
+ ssl_f_i_dn([<entry>[,<occ>]]) : exact string match
-ssl_c_sig_alg <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the name of the algorithm used to sign the certificate presented
- by the client matches the string.
+ssl_f_key_alg : string
+ Returns the name of the algorithm used to generate the key of the certificate
+ presented by the frontend when the incoming connection was made over an
+ SSL/TLS transport layer.
-ssl_c_used
- Returns true if current SSL session uses a client certificate even if current
- connection uses SSL session resumption. See also "ssl_fc_has_crt".
+ ACL derivatives :
+ ssl_f_key_alg : exact string match
-ssl_c_verify <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the verify result matches the specified value (check man verify
- for possible values). Zero indicates no error was detected.
+ssl_f_notafter : string
+ Returns the end date presented by the frontend as a formatted string
+ YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
+ transport layer.
-ssl_c_version <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the version of the certificate presented by the client matches
- the value.
+ ACL derivatives :
+ ssl_f_notafter : exact string match
-ssl_f_i_dn <string>
-ssl_f_i_dn(entry[,occ]) <string>
- If no entry specified, returns true when the incoming connection was made
- over an SSL/TLS transport layer, and the full distinguished name of the
- issuer of the certificate presented by the frontend matches the specified
- string. Otherwise returns true if the value of the first given entry from
- the beginning of the DN matches the specified string. If a positive/negative
- occurrence number is specified as the optional second argument, it returns
- true if the value of the nth given entry value from the beginning/end of the
- DN matches the specified string.
+ssl_f_notbefore : string
+ Returns the start date presented by the frontend as a formatted string
+ YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
+ transport layer.
-ssl_c_key_alg <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the name of the algorithm used to generate the key of the
- certificate presented by the frontend matches the string.
+ ACL derivatives :
+ ssl_f_notbefore : exact string match
-ssl_f_notafter <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the end date of the certificate presented by the frontend matches
- the string formatted as YYMMDDhhmmss[Z].
+ssl_f_s_dn([<entry>[,<occ>]]) : string
+ When the incoming connection was made over an SSL/TLS transport layer,
+ returns the full distinguished name of the subject of the certificate
+ presented by the frontend when no <entry> is specified, or the value of the
+ first given entry found from the beginning of the DN. If a positive/negative
+ occurrence number is specified as the optional second argument, it returns
+ the value of the nth given entry value from the beginning/end of the DN.
+ For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
+ "ssl_f_s_dn(CN)" retrieves the common name.
-ssl_f_notbefore <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the start date of the certificate presented by the frontend matches
- the string formatted as YYMMDDhhmmss[Z].
+ ACL derivatives :
+ ssl_f_s_dn([<entry>[,<occ>]]) : exact string match
-ssl_f_s_dn <string>
-ssl_f_s_dn(entry[,occ]) <string>
- If no entry specified, returns true when the incoming connection was made
- over an SSL/TLS transport layer, and the full distinguished name of the
- subject of the certificate presented by the frontend matches the specified
- string. Otherwise returns true if the value of the first given entry from
- the beginning of the DN matches the specified string. If a positive/negative
- occurrence number is specified as the optional second argument, it returns
- true if the value of the nth given entry value from the beginning/end of the
- DN matches the specified string.
+ssl_f_serial : binary
+ Returns the serial of the certificate presented by the frontend when the
+ incoming connection was made over an SSL/TLS transport layer. When used for
+ an ACL, the value(s) to match against can be passed in hexadecimal form.
-ssl_f_serial <hexa>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the serial of the certificate presented by the frontend matches
- the value written in hexa.
+ ACL derivatives :
+ ssl_f_serial : hex block match
-ssl_f_sig_alg <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the name of the algorithm used to sign the certificate presented
- by the frontend matches the string.
+ssl_f_sig_alg : string
+ Returns the name of the algorithm used to sign the certificate presented by
+ the frontend when the incoming connection was made over an SSL/TLS transport
+ layer.
-ssl_f_version <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer, and the version of the certificate presented by the frontend matches
- the value.
+ ACL derivatives :
+ ssl_f_sig_alg : exact string match
-ssl_fc
+ssl_f_version : integer
+ Returns the version of the certificate presented by the frontend when the
+ incoming connection was made over an SSL/TLS transport layer.
+
+ssl_fc : boolean
Returns true when the front connection was made via an SSL/TLS transport
layer and is locally deciphered. This means it has matched a socket declared
with a "bind" line having the "ssl" option.
+ Example :
+ # This passes "X-Proto: https" to servers when client connects over SSL
+ listen http-https
+ bind :80
+ bind :443 ssl crt /etc/haproxy.pem
+ http-request add-header X-Proto https if { ssl_fc }
+
+ssl_fc_alg_keysize : integer
+ Returns the symmetric cipher key size supported in bits when the incoming
+ connection was made over an SSL/TLS transport layer.
+
+ssl_fc_alpn : string
+ This extracts the Application Layer Protocol Negociation field from an
+ incoming connection made via a TLS transport layer and locally deciphered by
+ haproxy. The result is a string containing the protocol name advertised by
+ the client. The SSL library must have been built with support for TLS
+ extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
+ not advertised unless the "alpn" keyword on the "bind" line specifies a
+ protocol list. Also, nothing forces the client to pick a protocol from this
+ list, any other one may be requested. The TLS ALPN extension is meant to
+ replace the TLS NPN extension. See also "ssl_fc_npn".
+
-ssl_fc_alg_keysize <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer and the symmetric cipher key size supported in bits matches the value.
+ ACL derivatives :
+ ssl_fc_alpn : exact string match
-ssl_fc_alpn <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer which deciphered it and found a Next Protocol Negociation TLS extension
- sent by the client, matching the specified string. This requires that the SSL
- library is build with support for TLS extensions enabled (check haproxy -vv).
- Note that the TLS ALPN extension is not advertised unless the "alpn" keyword
- on the "bind" line specifies a protocol list. Also, nothing forces the client
- to pick a protocol from this list, any other one may be requested. The TLS
- ALPN extension is meant to replace the TLS NPN extension.
+ssl_fc_cipher : string
+ Returns the name of the used cipher when the incoming connection was made
+ over an SSL/TLS transport layer.
-ssl_fc_cipher <string>
- returns true when the incoming connection was made over an ssl/tls transport
- layer and the name of the used cipher matches the string.
+ ACL derivatives :
+ ssl_fc_cipher : exact string match
-ssl_fc_has_crt
+ssl_fc_has_crt : boolean
Returns true if a client certificate is present in an incoming connection over
SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
Note: on SSL session resumption with Session ID or TLS ticket, client
@@ -9235,476 +9504,701 @@
from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
current SSL session uses a client certificate.
-ssl_fc_has_sni
- This is used to check for presence of a Server Name Indication TLS extension
+ssl_fc_has_sni : boolean
+ This checks for the presence of a Server Name Indication TLS extension (SNI)
in an incoming connection was made over an SSL/TLS transport layer. Returns
true when the incoming connection presents a TLS SNI field. This requires
that the SSL library is build with support for TLS extensions enabled (check
haproxy -vv).
-ssl_fc_npn <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer which deciphered it and found a Next Protocol Negociation TLS extension
- sent by the client, matching the specified string. This requires that the SSL
- library is build with support for TLS extensions enabled (check haproxy -vv).
- Note that the TLS NPN extension is not advertised unless the "npn" keyword on
- the "bind" line specifies a protocol list. Also, nothing forces the client to
- pick a protocol from this list, any other one may be requested. Please note
- that the TLS NPN extension was replaced with ALPN.
+ssl_fc_npn : string
+ This extracts the Next Protocol Negociation field from an incoming connection
+ made via a TLS transport layer and locally deciphered by haproxy. The result
+ is a string containing the protocol name advertised by the client. The SSL
+ library must have been built with support for TLS extensions enabled (check
+ haproxy -vv). Note that the TLS NPN extension is not advertised unless the
+ "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
+ forces the client to pick a protocol from this list, any other one may be
+ requested. Please note that the TLS NPN extension was replaced with ALPN.
-ssl_fc_protocol <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer and the name of the used protocol matches the string.
+ ACL derivatives :
+ ssl_fc_npn : exact string match
-ssl_fc_sni <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer which deciphered it and found a Server Name Indication TLS extension
- sent by the client, matching the specified string. In HTTPS, the SNI field
- (when present) is equal to the requested host name. This match is different
- from "req_ssl_sni" above in that it applies to the connection being
- deciphered by haproxy and not to SSL contents being blindly forwarded.
- See also "ssl_fc_sni_end" and "ssl_fc_sni_req" below. This requires that the
- SSL library is build with support for TLS extensions enabled (check
- haproxy -vv).
+ssl_fc_protocol : string
+ Returns the name of the used protocol when the incoming connection was made
+ over an SSL/TLS transport layer.
-ssl_fc_sni_end <string>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer which deciphered it and found a Server Name Indication TLS extension
- sent by the client, ending like the specified string. In HTTPS, the SNI field
- (when present) is equal to the requested host name. This match is different
- from "req_ssl_sni" above in that it applies to the connection being
- deciphered by haproxy and not to SSL contents being blindly forwarded. This
- requires that the SSL library is build with support for TLS extensions
- enabled (check haproxy -vv).
+ ACL derivatives :
+ ssl_fc_protocol : exact string match
+
+ssl_fc_session_id : binary
+ Returns the SSL ID of the front connection when the incoming connection was
+ made over an SSL/TLS transport layer. It is useful to stick a given client to
+ a server. It is important to note that some browsers refresh their session ID
+ every few minutes.
-ssl_fc_sni_reg <regex>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer which deciphered it and found a Server Name Indication TLS extension
- sent by the client, matching the specified regex. In HTTPS, the SNI field
- (when present) is equal to the requested host name. This match is different
- from "req_ssl_sni" above in that it applies to the connection being
- deciphered by haproxy and not to SSL contents being blindly forwarded. This
+ssl_fc_sni : string
+ This extracts the Server Name Indication TLS extension (SNI) field from an
+ incoming connection made via an SSL/TLS transport layer and locally
+ deciphered by haproxy. The result (when present) typically is a string
+ matching the HTTPS host name (253 chars or less). The SSL library must have
+ been built with support for TLS extensions enabled (check haproxy -vv).
+
+ This fetch is different from "req_ssl_sni" above in that it applies to the
+ connection being deciphered by haproxy and not to SSL contents being blindly
+ forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
requires that the SSL library is build with support for TLS extensions
enabled (check haproxy -vv).
-ssl_fc_use_keysize <integer>
- Returns true when the incoming connection was made over an SSL/TLS transport
- layer and the symmetric cipher key size used in bits matches the value.
+ ACL derivatives :
+ ssl_fc_sni : exact string match
+ ssl_fc_sni_end : suffix match
+ ssl_fc_sni_reg : regex match
-wait_end
- Waits for the end of the analysis period to return true. This may be used in
- conjunction with content analysis to avoid returning a wrong verdict early.
- It may also be used to delay some actions, such as a delayed reject for some
- special addresses. Since it either stops the rules evaluation or immediately
- returns true, it is recommended to use this acl as the last one in a rule.
- Please note that the default ACL "WAIT_END" is always usable without prior
- declaration. This test was designed to be used with TCP request content
- inspection.
+ssl_fc_use_keysize : integer
+ Returns the symmetric cipher key size used in bits when the incoming
+ connection was made over an SSL/TLS transport layer.
- Examples :
- # delay every incoming request by 2 seconds
- tcp-request inspect-delay 2s
- tcp-request content accept if WAIT_END
- # don't immediately tell bad guys they are rejected
- tcp-request inspect-delay 10s
- acl goodguys src 10.0.0.0/24
- acl badguys src 10.0.1.0/24
- tcp-request content accept if goodguys
- tcp-request content reject if badguys WAIT_END
- tcp-request content reject
+7.3.4. Fetching samples from buffer contents (Layer 6)
+------------------------------------------------------
+Fetching samples from buffer contents is a bit different from the previous
+sample fetches above because the sampled data are ephemeral. These data can
+only be used when they're available and will be lost when they're forwarded.
+For this reason, samples fetched from buffer contents during a request cannot
+be used in a response for example. Even while the data are being fetched, they
+can change. Sometimes it is necessary to set some delays or combine multiple
+sample fetch methods to ensure that the expected data are complete and usable,
+for example through TCP request content inspection. Please see the "tcp-request
+content" keyword for more detailed information on the subject.
-7.5.3. Matching at Layer 7
---------------------------
+payload(<offset>,<length>) : binary (deprecated)
+ This is an alias for "req.payload" when used in the context of a request (eg:
+ "stick on", "stick match"), and for "res.payload" when used in the context of
+ a response such as in "stick store response".
-A third set of criteria applies to information which can be found at the
-application layer (layer 7). Those require that a full HTTP request has been
-read, and are only evaluated then. They may require slightly more CPU resources
-than the layer 4 ones, but not much since the request and response are indexed.
+payload_lv(<offset1>,<length>[,<offset2>]) : binary (deprecated)
+ This is an alias for "req.payload_lv" when used in the context of a request
+ (eg: "stick on", "stick match"), and for "res.payload_lv" when used in the
+ context of a response such as in "stick store response".
-base <string>
- Returns true when the concatenation of the first Host header and the path
- part of the request, which starts at the first slash and ends before the
- question mark, equals one of the strings. It may be used to match known
- files in virtual hosting environments, such as "www.example.com/favicon.ico".
- See also "path" and "uri".
+req.len : integer
+req_len : integer (deprecated)
+ Returns an integer value corresponding to the number of bytes present in the
+ request buffer. This is mostly used in ACL. It is important to understand
+ that this test does not return false as long as the buffer is changing. This
+ means that a check with equality to zero will almost always immediately match
+ at the beginning of the session, while a test for more data will wait for
+ that data to come in and return false only when haproxy is certain that no
+ more data will come in. This test was designed to be used with TCP request
+ content inspection.
-base_beg <string>
- Returns true when the base (see above) begins with one of the strings. This
- can be used to send certain directory names to alternative backends. See also
- "path_beg".
+req.payload(<offset>,<length>) : binary
+ This extracts a binary block of <length> bytes and starting at byte <offset>
+ in the request buffer.
-base_dir <string>
- Returns true when one of the strings is found isolated or delimited with
- slashes in the base (see above). Probably of little use, see "url_dir" and
- "path_dir" instead.
+ ACL alternatives :
+ payload(<offset>,<length>) : hex binary match
-base_dom <string>
- Returns true when one of the strings is found isolated or delimited with dots
- in the base (see above). Probably of little use, see "path_dom" and "url_dom"
- instead.
+req.payload_lv(<offset1>,<length>[,<offset2>]) : binary
+ This extracts a binary block whose size is specified at <offset1> for <length>
+ bytes, and which starts at <offset2> if specified or just after the length in
+ the request buffer. The <offset2> parameter also supports relative offsets if
+ prepended with a '+' or '-' sign.
-base_end <string>
- Returns true when the base (see above) ends with one of the strings. This may
- be used to control file name extension, though "path_end" is cheaper.
+ ACL alternatives :
+ payload_lv(<offset1>,<length>[,<offset2>]) : hex binary match
-base_len <integer>
- Returns true when the base (see above) length matches the values or ranges
- specified. This may be used to detect abusive requests for instance.
+ Example : please consult the example from the "stick store-response" keyword.
-base_reg <regex>
- Returns true when the base (see above) matches one of the regular
- expressions. It can be used any time, but it is important to remember that
- regex matching is slower than other methods. See also "path_reg", "url_reg"
- and all "base_" criteria.
+req.proto_http : boolean
+req_proto_http : boolean (deprecated)
+ Returns true when data in the request buffer look like HTTP and correctly
+ parses as such. It is the same parser as the common HTTP request parser which
+ is used so there should be no surprises. The test does not match until the
+ request is complete, failed or timed out. This test may be used to report the
+ protocol in TCP logs, but the biggest use is to block TCP request analysis
+ until a complete HTTP request is present in the buffer, for example to track
+ a header.
-base_sub <string>
- Returns true when the base (see above) contains one of the strings. It can be
- used to detect particular patterns in paths, such as "../" for example. See
- also "base_dir".
+ Example:
+ # track request counts per "base" (concatenation of Host+URL)
+ tcp-request inspect-delay 10s
+ tcp-request content reject if !HTTP
+ tcp-request content track-sc1 base table req-rate
-cook(<name>) <string>
- All "cook*" matching criteria inspect all "Cookie" headers to find a cookie
- with the name between parenthesis. If multiple occurrences of the cookie are
- found in the request, they will all be evaluated. Spaces around the name and
- the value are ignored as requested by the Cookie specification (RFC6265). The
- cookie name is case-sensitive. Use the scook() variant for response cookies
- sent by the server.
+req.rdp_cookie([<name>]) : string
+rdp_cookie([<name>]) : string (deprecated)
+ When the request buffer looks like the RDP protocol, extracts the RDP cookie
+ <name>, or any cookie if unspecified. The parser only checks for the first
+ cookie, as illustrated in the RDP protocol specification. The cookie name is
+ case insensitive. Generally the "MSTS" cookie name will be used, as it can
+ contain the user name of the client connecting to the server if properly
+ configured on the client. The "MSTSHASH" cookie is often used as well for
+ session stickiness to servers.
- The "cook" criteria returns true if any of the request cookies <name> match
- any of the strings. This can be used to check exact for values. For instance,
- checking that the "profile" cookie is set to either "silver" or "gold" :
+ This differs from "balance rdp-cookie" in that any balancing algorithm may be
+ used and thus the distribution of clients to backend servers is not linked to
+ a hash of the RDP cookie. It is envisaged that using a balancing algorithm
+ such as "balance roundrobin" or "balance leastconn" will lead to a more even
+ distribution of clients to backend servers than the hash used by "balance
+ rdp-cookie".
- cook(profile) silver gold
+ ACL derivatives :
+ req_rdp_cookie([<name>]) : exact string match
-cook_beg(<name>) <string>
- Returns true if any of the request cookies <name> begins with one of the
- strings. See "cook" for more information on cookie matching. Use the
- scook_beg() variant for response cookies sent by the server.
+ Example :
+ listen tse-farm
+ bind 0.0.0.0:3389
+ # wait up to 5s for an RDP cookie in the request
+ tcp-request inspect-delay 5s
+ tcp-request content accept if RDP_COOKIE
+ # apply RDP cookie persistence
+ persist rdp-cookie
+ # Persist based on the mstshash cookie
+ # This is only useful makes sense if
+ # balance rdp-cookie is not used
+ stick-table type string size 204800
+ stick on req.rdp_cookie(mstshash)
+ server srv1 1.1.1.1:3389
+ server srv1 1.1.1.2:3389
-cook_cnt(<name>) <integer>
- Returns true when the number of occurrences of the specified cookie matches
- the values or ranges specified. This is used to detect presence, absence or
- abuse of a specific cookie. See "cook" for more information on header
- matching. Use the scook_cnt() variant for response cookies sent by the
- server.
+ See also : "balance rdp-cookie", "persist rdp-cookie", "tcp-request" and the
+ "req_rdp_cookie" ACL.
-cook_dir(<name>) <string>
- Returns true if any of the request cookies <name> contains one of the strings
- either isolated or delimited by slashes. This is used to perform filename or
- directory name matching, though it generally is of limited use with cookies.
- See "cook" for more information on cookie matching. Use the scook_dir()
- variant for response cookies sent by the server.
+req.rdp_cookie_cnt([name]) : integer
+rdp_cookie_cnt([name]) : integer (deprecated)
+ Tries to parse the request buffer as RDP protocol, then returns an integer
+ corresponding to the number of RDP cookies found. If an optional cookie name
+ is passed, only cookies matching this name are considered. This is mostly
+ used in ACL.
-cook_dom(<name>) <string>
- Returns true if any of the request cookies <name> contains one of the strings
- either isolated or delimited by dots. This is used to perform domain name
- matching. See "cook" for more information on cookie matching. Use the
- scook_dom() variant for response cookies sent by the server.
+ ACL derivatives :
+ req_rdp_cookie_cnt([<name>]) : integer match
-cook_end(<name>) <string>
- Returns true if any of the request cookies <name> ends with one of the
- strings. See "cook" for more information on cookie matching. Use the
- scook_end() variant for response cookies sent by the server.
+req.ssl_hello_type : integer
+req_ssl_hello_type : integer (deprecated)
+ Returns an integer value containing the type of the SSL hello message found
+ in the request buffer if the buffer contains data that parse as a complete
+ SSL (v3 or superior) client hello message. Note that this only applies to raw
+ contents found in the request buffer and not to contents deciphered via an
+ SSL data layer, so this will not work with "bind" lines having the "ssl"
+ option. This is mostly used in ACL to detect presence of an SSL hello message
+ that is supposed to contain an SSL session ID usable for stickiness.
-cook_len(<name>) <integer>
- Returns true if any of the request cookies <name> has a length which matches
- the values or ranges specified. This may be used to detect empty or too large
- cookie values. Note that an absent cookie does not match a zero-length test.
- See "cook" for more information on cookie matching. Use the scook_len()
- variant for response cookies sent by the server.
+req.ssl_sni : string
+req_ssl_sni : string (deprecated)
+ Returns a string containing the value of the Server Name TLS extension sent
+ by a client in a TLS stream passing through the request buffer if the buffer
+ contains data that parse as a complete SSL (v3 or superior) client hello
+ message. Note that this only applies to raw contents found in the request
+ buffer and not to contents deciphered via an SSL data layer, so this will not
+ work with "bind" lines having the "ssl" option. SNI normally contains the
+ name of the host the client tries to connect to (for recent browsers). SNI is
+ useful for allowing or denying access to certain hosts when SSL/TLS is used
+ by the client. This test was designed to be used with TCP request content
+ inspection. If content switching is needed, it is recommended to first wait
+ for a complete client hello (type 1), like in the example below. See also
+ "ssl_fc_sni".
-cook_reg(<name>) <regex>
- Returns true if any of the request cookies <name> matches any of the regular
- expressions. It can be used at any time, but it is important to remember that
- regex matching is slower than other methods. See also other "cook_" criteria,
- as well as "cook" for more information on cookie matching. Use the
- scook_reg() variant for response cookies sent by the server.
+ ACL derivatives :
+ req_ssl_sni : exact string match
-cook_sub(<name>) <string>
- Returns true if any of the request cookies <name> contains at least one of
- the strings. See "cook" for more information on cookie matching. Use the
- scook_sub() variant for response cookies sent by the server.
+ Examples :
+ # Wait for a client hello for at most 5 seconds
+ tcp-request inspect-delay 5s
+ tcp-request content accept if { req_ssl_hello_type 1 }
+ use_backend bk_allow if { req_ssl_sni -f allowed_sites }
+ default_backend bk_sorry_page
-cook_val(<name>) <integer>
- Returns true if any of the request cookies <name> starts with a number which
- matches the values or ranges specified. This may be used to select a server
- based on application-specific cookies. Note that an absent cookie does not
- match any value. See "cook" for more information on cookie matching. Use the
- scook_val() variant for response cookies sent by the server.
+res.ssl_hello_type : integer
+rep_ssl_hello_type : integer (deprecated)
+ Returns an integer value containing the type of the SSL hello message found
+ in the response buffer if the buffer contains data that parses as a complete
+ SSL (v3 or superior) hello message. Note that this only applies to raw
+ contents found in the response buffer and not to contents deciphered via an
+ SSL data layer, so this will not work with "server" lines having the "ssl"
+ option. This is mostly used in ACL to detect presence of an SSL hello message
+ that is supposed to contain an SSL session ID usable for stickiness.
-hdr <string>
-hdr(<header>[,<occ>]) <string>
- Note: all the "hdr*" matching criteria either apply to all headers, or to a
- particular header whose name is passed between parenthesis and without any
- space. The header name is not case-sensitive. The header matching complies
- with RFC2616, and treats as separate headers all values delimited by commas.
- If an occurrence number is specified as the optional second argument, only
- this occurrence will be considered. Positive values indicate a position from
- the first occurrence, 1 being the first one. Negative values indicate
- positions relative to the last one, -1 being the last one. Use the shdr()
- variant for response headers sent by the server.
+req.ssl_ver : integer
+req_ssl_ver : integer (deprecated)
+ Returns an integer value containing the version of the SSL/TLS protocol of a
+ stream present in the request buffer. Both SSLv2 hello messages and SSLv3
+ messages are supported. TLSv1 is announced as SSL version 3.1. The value is
+ composed of the major version multiplied by 65536, added to the minor
+ version. Note that this only applies to raw contents found in the request
+ buffer and not to contents deciphered via an SSL data layer, so this will not
+ work with "bind" lines having the "ssl" option. The ACL version of the test
+ matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). This
+ fetch is mostly used in ACL.
- The "hdr" criteria returns true if any of the headers matching the criteria
- match any of the strings. This can be used to check for exact values. For
- instance, checking that "connection: close" is set :
+ ACL derivatives :
+ req_ssl_ver : decimal match
- hdr(Connection) -i close
+res.payload(<offset>,<length>) : binary
+ This extracts a binary block of <length> bytes and starting at byte <offset>
+ in the response buffer.
-hdr_beg <string>
-hdr_beg(<header>[,<occ>]) <string>
- Returns true when one of the headers begins with one of the strings. See
- "hdr" for more information on header matching. Use the shdr_beg() variant for
- response headers sent by the server.
+res.payload_lv(<offset1>,<length>[,<offset2>]) : binary
+ This extracts a binary block whose size is specified at <offset1> for <length>
+ bytes, and which starts at <offset2> if specified or just after the length in
+ the response buffer. The <offset2> parameter also supports relative offsets
+ if prepended with a '+' or '-' sign.
-hdr_cnt <integer>
-hdr_cnt(<header>) <integer>
- Returns true when the number of occurrence of the specified header matches
- the values or ranges specified. It is important to remember that one header
- line may count as several headers if it has several values. This is used to
- detect presence, absence or abuse of a specific header, as well as to block
- request smuggling attacks by rejecting requests which contain more than one
- of certain headers. See "hdr" for more information on header matching. Use
- the shdr_cnt() variant for response headers sent by the server.
+ Example : please consult the example from the "stick store-response" keyword.
-hdr_dir <string>
-hdr_dir(<header>[,<occ>]) <string>
- Returns true when one of the headers contains one of the strings either
- isolated or delimited by slashes. This is used to perform filename or
- directory name matching, and may be used with Referer. See "hdr" for more
- information on header matching. Use the shdr_dir() variant for response
- headers sent by the server.
+wait_end : boolean
+ This fetch either returns true when the inspection period is over, or does
+ not fetch. It is only used in ACLs, in conjunction with content analysis to
+ avoid returning a wrong verdict early. It may also be used to delay some
+ actions, such as a delayed reject for some special addresses. Since it either
+ stops the rules evaluation or immediately returns true, it is recommended to
+ use this acl as the last one in a rule. Please note that the default ACL
+ "WAIT_END" is always usable without prior declaration. This test was designed
+ to be used with TCP request content inspection.
-hdr_dom <string>
-hdr_dom(<header>[,<occ>]) <string>
- Returns true when one of the headers contains one of the strings either
- isolated or delimited by dots. This is used to perform domain name matching,
- and may be used with the Host header. See "hdr" for more information on
- header matching. Use the shdr_dom() variant for response headers sent by the
- server.
+ Examples :
+ # delay every incoming request by 2 seconds
+ tcp-request inspect-delay 2s
+ tcp-request content accept if WAIT_END
-hdr_end <string>
-hdr_end(<header>[,<occ>]) <string>
- Returns true when one of the headers ends with one of the strings. See "hdr"
- for more information on header matching. Use the shdr_end() variant for
- response headers sent by the server.
+ # don't immediately tell bad guys they are rejected
+ tcp-request inspect-delay 10s
+ acl goodguys src 10.0.0.0/24
+ acl badguys src 10.0.1.0/24
+ tcp-request content accept if goodguys
+ tcp-request content reject if badguys WAIT_END
+ tcp-request content reject
+
+
+7.3.5. Fetching HTTP samples (Layer 7)
+--------------------------------------
+
+It is possible to fetch samples from HTTP contents, requests and responses.
+This application layer is also called layer 7. It is only possible to fetch the
+data in this section when a full HTTP request or response has been parsed from
+its respective request or response buffer. This is always the case with all
+HTTP specific rules and for sections running with "mode http". When using TCP
+content inspection, it may be necessary to support an inspection delay in order
+to let the request or response come in first. These fetches may require a bit
+more CPU resources than the layer 4 ones, but not much since the request and
+response are indexed.
+
+base : string
+ This returns the concatenation of the first Host header and the path part of
+ the request, which starts at the first slash and ends before the question
+ mark. It can be useful in virtual hosted environments to detect URL abuses as
+ well as to improve shared caches efficiency. Using this with a limited size
+ stick table also allows one to collect statistics about most commonly
+ requested objects by host/path. With ACLs it can allow simple content
+ switching rules involving the host and the path at the same time, such as
+ "www.example.com/favicon.ico". See also "path" and "uri".
+
+ ACL derivatives :
+ base : exact string match
+ base_beg : prefix match
+ base_dir : subdir match
+ base_dom : domain match
+ base_end : suffix match
+ base_len : length match
+ base_reg : regex match
+ base_sub : substring match
+
+base32 : integer
+ This returns a 32-bit hash of the value returned by the "base" fetch method
+ above. This is useful to track per-URL activity on high traffic sites without
+ having to store all URLs. Instead a shorter hash is stored, saving a lot of
+ memory. The output type is an unsigned integer.
+
+base32+src : binary
+ This returns the concatenation of the base32 fetch above and the src fetch
+ below. The resulting type is of type binary, with a size of 8 or 20 bytes
+ depending on the source address family. This can be used to track per-IP,
+ per-URL counters.
+
+req.cook([<name>]) : string
+cook([<name>]) : string (deprecated)
+ This extracts the last occurrence of the cookie name <name> on a "Cookie"
+ header line from the request, and returns its value as string. If no name is
+ specified, the first cookie value is returned. When used with ACLs, all
+ matching cookies are evaluated. Spaces around the name and the value are
+ ignored as requested by the Cookie header specification (RFC6265). The cookie
+ name is case-sensitive. Empty cookies are valid, so an empty cookie may very
+ well return an empty value if it is present. Use the "found" match to detect
+ presence. Use the res.cook() variant for response cookies sent by the server.
+
+ ACL derivatives :
+ cook([<name>]) : exact string match
+ cook_beg([<name>]) : prefix match
+ cook_dir([<name>]) : subdir match
+ cook_dom([<name>]) : domain match
+ cook_end([<name>]) : suffix match
+ cook_len([<name>]) : length match
+ cook_reg([<name>]) : regex match
+ cook_sub([<name>]) : substring match
-hdr_ip <ip_address>
-hdr_ip(<header>[,<occ>]) <address>
- Returns true when one of the headers' values contains an IPv4 or IPv6 address
- matching <address>. This is mainly used with headers such as X-Forwarded-For
- or X-Client-IP. See "hdr" for more information on header matching. Use the
- shdr_ip() variant for response headers sent by the server.
+req.cook_cnt([<name>]) : integer
+cook_cnt([<name>]) : integer (deprecated)
+ Returns an integer value representing the number of occurrences of the cookie
+ <name> in the request, or all cookies if <name> is not specified.
-hdr_len <integer>
-hdr_len(<header>[,<occ>]) <integer>
- Returns true when at least one of the headers has a length which matches the
- values or ranges specified. This may be used to detect empty or too large
- headers. See "hdr" for more information on header matching. Use the
- shdr_len() variant for response headers sent by the server.
+req.cook_val([<name>]) : integer
+cook_val([<name>]) : integer (deprecated)
+ This extracts the last occurrence of the cookie name <name> on a "Cookie"
+ header line from the request, and converts its value to an integer which is
+ returned. If no name is specified, the first cookie value is returned. When
+ used in ACLs, all matching names are iterated over until a value matches.
-hdr_reg <regex>
-hdr_reg(<header>[,<occ>]) <regex>
- Returns true it one of the headers matches one of the regular expressions. It
- can be used at any time, but it is important to remember that regex matching
- is slower than other methods. See also other "hdr_" criteria, as well as
- "hdr" for more information on header matching. Use the shdr_reg() variant for
- response headers sent by the server.
+cookie([<name>]) : string (deprecated)
+ This extracts the last occurrence of the cookie name <name> on a "Cookie"
+ header line from the request, or a "Set-Cookie" header from the response, and
+ returns its value as a string. A typical use is to get multiple clients
+ sharing a same profile use the same server. This can be similar to what
+ "appsession" does with the "request-learn" statement, but with support for
+ multi-peer synchronization and state keeping across restarts. If no name is
+ specified, the first cookie value is returned. This fetch should not be used
+ anymore and should be replaced by req.cook() or res.cook() instead as it
+ ambiguously uses the direction based on the context where it is used.
+ See also : "appsession".
-hdr_sub <string>
-hdr_sub(<header>[,<occ>]) <string>
- Returns true when one of the headers contains one of the strings. See "hdr"
- for more information on header matching. Use the shdr_sub() variant for
- response headers sent by the server.
+hdr([<name>[,<occ>]]) : string
+ This is equivalent to req.hdr() when used on requests, and to res.hdr() when
+ used on responses. Please refer to these respective fetches for more details.
+ In case of doubt about the fetch direction, please use the explicit ones.
+ Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords
+ unambiguouslly apply to the request headers.
-hdr_val <integer>
-hdr_val(<header>[,<occ>]) <integer>
- Returns true when one of the headers starts with a number which matches the
- values or ranges specified. This may be used to limit content-length to
- acceptable values for example. See "hdr" for more information on header
- matching. Use the shdr_val() variant for response headers sent by the server.
+req.fhdr(<name>[,<occ>]) : string
+ This extracts the last occurrence of header <name> in an HTTP request. When
+ used from an ACL, all occurrences are iterated over until a match is found.
+ Optionally, a specific occurrence might be specified as a position number.
+ Positive values indicate a position from the first occurrence, with 1 being
+ the first one. Negative values indicate positions relative to the last one,
+ with -1 being the last one. It differs from req.hdr() in that any commas
+ present in the value are returned and are not used as delimiters. This is
+ sometimes useful with headers such as User-Agent.
-http_auth(<userlist>)
-http_auth_group(<userlist>) <group> [<group>]*
- Returns true when authentication data received from the client matches
- username & password stored on the userlist. It is also possible to
- use http_auth_group to check if the user is assigned to at least one
- of specified groups.
+req.fhdr_cnt([<name>]) : integer
+ Returns an integer value representing the number of occurrences of request
+ header field name <name>, or the total number of header fields if <name> is
+ not specified. Contrary to its req.hdr_cnt() cousin, this function returns
+ the number of full line headers and does not stop on commas.
- Currently only http basic auth is supported.
+req.hdr([<name>[,<occ>]]) : string
+ This extracts the last occurrence of header <name> in an HTTP request. When
+ used from an ACL, all occurrences are iterated over until a match is found.
+ Optionally, a specific occurrence might be specified as a position number.
+ Positive values indicate a position from the first occurrence, with 1 being
+ the first one. Negative values indicate positions relative to the last one,
+ with -1 being the last one. A typical use is with the X-Forwarded-For header
+ once converted to IP, associated with an IP stick-table. The function
+ considers any comma as a delimiter for distinct values. If full-line headers
+ are desired instead, use req.fhdr(). Please carefully check RFC2616 to know
+ how certain headers are supposed to be parsed. Also, some of them are case
+ insensitive (eg: Connection).
-http_first_req
+ ACL derivatives :
+ hdr([<name>[,<occ>]]) : exact string match
+ hdr_beg([<name>[,<occ>]]) : prefix match
+ hdr_dir([<name>[,<occ>]]) : subdir match
+ hdr_dom([<name>[,<occ>]]) : domain match
+ hdr_end([<name>[,<occ>]]) : suffix match
+ hdr_len([<name>[,<occ>]]) : length match
+ hdr_reg([<name>[,<occ>]]) : regex match
+ hdr_sub([<name>[,<occ>]]) : substring match
+
+req.hdr_cnt([<name>]) : integer
+hdr_cnt([<header>]) : integer (deprecated)
+ Returns an integer value representing the number of occurrences of request
+ header field name <name>, or the total number of header field values if
+ <name> is not specified. It is important to remember that one header line may
+ count as several headers if it has several values. The function considers any
+ comma as a delimiter for distinct values. If full-line headers are desired
+ instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
+ detect presence, absence or abuse of a specific header, as well as to block
+ request smuggling attacks by rejecting requests which contain more than one
+ of certain headers. See "req.hdr" for more information on header matching.
+
+req.hdr_ip([<name>[,<occ>]]) : ip
+hdr_ip([<name>[,<occ>]]) : ip (deprecated)
+ This extracts the last occurrence of header <name> in an HTTP request,
+ converts it to an IPv4 or IPv6 address and returns this address. When used
+ with ACLs, all occurrences are checked, and if <name> is omitted, every value
+ of every header is checked. Optionally, a specific occurrence might be
+ specified as a position number. Positive values indicate a position from the
+ first occurrence, with 1 being the first one. Negative values indicate
+ positions relative to the last one, with -1 being the last one. A typical use
+ is with the X-Forwarded-For and X-Client-IP headers.
+
+req.hdr_val([<name>[,<occ>]]) : integer
+hdr_val([<name>[,<occ>]]) : integer (deprecated)
+ This extracts the last occurrence of header <name> in an HTTP request, and
+ converts it to an integer value. When used with ACLs, all occurrences are
+ checked, and if <name> is omitted, every value of every header is checked.
+ Optionally, a specific occurrence might be specified as a position number.
+ Positive values indicate a position from the first occurrence, with 1 being
+ the first one. Negative values indicate positions relative to the last one,
+ with -1 being the last one. A typical use is with the X-Forwarded-For header.
+
+http_auth(<userlist>) : boolean
+ Returns a boolean indicating whether the authentication data received from
+ the client match a username & password stored in the specified userlist. This
+ fetch function is not really useful outside of ACLs. Currently only http
+ basic auth is supported.
+
+http_auth_group(<userlist>) : group
+ Returns a boolean indicating whether the authentication data received from
+ the client match a username & password stored in the specified userlist, and
+ whether that username belongs to one of the groups supplied in ACL patterns.
+ This fetch function is not really useful outside of ACLs. Currently only http
+ basic auth is supported.
+
+ ACL derivatives :
+ http_auth_group(<userlist>) : user group match
+
+http_first_req : boolean
Returns true when the request being processed is the first one of the
connection. This can be used to add or remove headers that may be missing
- from some requests when a request is not the first one, or even to perform
- some specific ACL checks only on the first request.
+ from some requests when a request is not the first one, or to help grouping
+ requests in the logs.
-method <string>
- Applies to the method in the HTTP request, eg: "GET". Some predefined ACL
- already check for most common methods.
+method : integer + string
+ Returns an integer value corresponding to the method in the HTTP request. For
+ example, "GET" equals 1 (check sources to establish the matching). Value 9
+ means "other method" and may be converted to a string extracted from the
+ stream. This should not be used directly as a sample, this is only meant to
+ be used from ACLs, which transparently convert methods from patterns to these
+ integer + string values. Some predefined ACL already check for most common
+ methods.
-path <string>
- Returns true when the path part of the request, which starts at the first
- slash and ends before the question mark, equals one of the strings. It may be
- used to match known files, such as /favicon.ico.
+ ACL derivatives :
+ method : case insensitive method match
-path_beg <string>
- Returns true when the path begins with one of the strings. This can be used
- to send certain directory names to alternative backends.
+ Example :
+ # only accept GET and HEAD requests
+ acl valid_method method GET HEAD
+ http-request deny if ! valid_method
-path_dir <string>
- Returns true when one of the strings is found isolated or delimited with
- slashes in the path. This is used to perform filename or directory name
- matching without the risk of wrong match due to colliding prefixes. See also
- "url_dir" and "path_sub".
+path : string
+ This extracts the request's URL path, which starts at the first slash and
+ ends before the question mark (without the host part). A typical use is with
+ prefetch-capable caches, and with portals which need to aggregate multiple
+ information from databases and keep them in caches. Note that with outgoing
+ caches, it would be wiser to use "url" instead. With ACLs, it's typically
+ used to match exact file names (eg: "/login.php"), or directory parts using
+ the derivative forms. See also the "url" and "base" fetch methods.
-path_dom <string>
- Returns true when one of the strings is found isolated or delimited with dots
- in the path. This may be used to perform domain name matching in proxy
- requests. See also "path_sub" and "url_dom".
+ ACL derivatives :
+ path : exact string match
+ path_beg : prefix match
+ path_dir : subdir match
+ path_dom : domain match
+ path_end : suffix match
+ path_len : length match
+ path_reg : regex match
+ path_sub : substring match
-path_end <string>
- Returns true when the path ends with one of the strings. This may be used to
- control file name extension.
+req.ver : string
+req_ver : string (deprecated)
+ Returns the version string from the HTTP request, for example "1.1". This can
+ be useful for logs, but is mostly there for ACL. Some predefined ACL already
+ check for versions 1.0 and 1.1.
-path_len <integer>
- Returns true when the path length matches the values or ranges specified.
- This may be used to detect abusive requests for instance.
+ ACL derivatives :
+ req_ver : exact string match
-path_reg <regex>
- Returns true when the path matches one of the regular expressions. It can be
- used any time, but it is important to remember that regex matching is slower
- than other methods. See also "url_reg" and all "path_" criteria.
+res.comp : boolean
+ Returns the boolean "true" value if the response has been compressed by
+ HAProxy, otherwise returns boolean "false". This may be used to add
+ information in the logs.
-path_sub <string>
- Returns true when the path contains one of the strings. It can be used to
- detect particular patterns in paths, such as "../" for example. See also
- "path_dir".
+res.comp_algo : string
+ Returns a string containing the name of the algorithm used if the response
+ was compressed by HAProxy, for example : "deflate". This may be used to add
+ some information in the logs.
-payload(<offset>,<length>) <string>
- Returns true if the block of <length> bytes, starting at byte <offset> in the
- request or response buffer (depending on the rule) exactly matches one of the
- strings.
+res.cook([<name>]) : string
+scook([<name>]) : string (deprecated)
+ This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
+ header line from the response, and returns its value as string. If no name is
+ specified, the first cookie value is returned.
-payload_lv(<offset1>,<length>[,<offset2>])
- Returns true if the block whose size is specified at <offset1> for <length>
- bytes, and which starts at <offset2> if specified or just after the length in
- the request or response buffer (depending on the rule) exactly matches one of
- the strings. The <offset2> parameter also supports relative offsets if
- prepended with a '+' or '-' sign.
+ ACL derivatives :
+ scook([<name>] : exact string match
-req_ver <string>
- Applies to the version string in the HTTP request, eg: "1.0". Some predefined
- ACL already check for versions 1.0 and 1.1.
+res.cook_cnt([<name>]) : integer
+scook_cnt([<name>]) : integer (deprecated)
+ Returns an integer value representing the number of occurrences of the cookie
+ <name> in the response, or all cookies if <name> is not specified. This is
+ mostly useful when combined with ACLs to detect suspicious responses.
-status <integer>
- Applies to the HTTP status code in the HTTP response, eg: "302". It can be
- used to act on responses depending on status ranges, for instance, remove
- any Location header if the response is not a 3xx.
+res.cook_val([<name>]) : integer
+scook_val([<name>]) : integer (deprecated)
+ This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
+ header line from the response, and converts its value to an integer which is
+ returned. If no name is specified, the first cookie value is returned.
-url <string>
- Applies to the whole URL passed in the request. The only real use is to match
- "*", for which there already is a predefined ACL. See also "base".
+res.fhdr([<name>[,<occ>]]) : string
+ This extracts the last occurrence of header <name> in an HTTP response, or of
+ the last header if no <name> is specified. Optionally, a specific occurrence
+ might be specified as a position number. Positive values indicate a position
+ from the first occurrence, with 1 being the first one. Negative values
+ indicate positions relative to the last one, with -1 being the last one. It
+ differs from res.hdr() in that any commas present in the value are returned
+ and are not used as delimiters. If this is not desired, the res.hdr() fetch
+ should be used instead. This is sometimes useful with headers such as Date or
+ Expires.
-url_beg <string>
- Returns true when the URL begins with one of the strings. This can be used to
- check whether a URL begins with a slash or with a protocol scheme. See also
- "base_beg".
+res.fhdr_cnt([<name>]) : integer
+ Returns an integer value representing the number of occurrences of response
+ header field name <name>, or the total number of header fields if <name> is
+ not specified. Contrary to its res.hdr_cnt() cousin, this function returns
+ the number of full line headers and does not stop on commas. If this is not
+ desired, the res.hdr_cnt() fetch should be used instead.
-url_dir <string>
- Returns true when one of the strings is found isolated or delimited with
- slashes in the URL. This is used to perform filename or directory name
- matching without the risk of wrong match due to colliding prefixes. See also
- "path_dir" and "url_sub".
+res.hdr([<name>[,<occ>]]) : string
+shdr([<name>[,<occ>]]) : string (deprecated)
+ This extracts the last occurrence of header <name> in an HTTP response, or of
+ the last header if no <name> is specified. Optionally, a specific occurrence
+ might be specified as a position number. Positive values indicate a position
+ from the first occurrence, with 1 being the first one. Negative values
+ indicate positions relative to the last one, with -1 being the last one. This
+ can be useful to learn some data into a stick-table. The function considers
+ any comma as a delimiter for distinct values. If this is not desired, the
+ res.fhdr() fetch should be used instead.
-url_dom <string>
- Returns true when one of the strings is found isolated or delimited with dots
- in the URL. This is used to perform domain name matching without the risk of
- wrong match due to colliding prefixes. See also "url_sub".
+ ACL derivatives :
+ shdr([<name>[,<occ>]]) : exact string match
+ shdr_beg([<name>[,<occ>]]) : prefix match
+ shdr_dir([<name>[,<occ>]]) : subdir match
+ shdr_dom([<name>[,<occ>]]) : domain match
+ shdr_end([<name>[,<occ>]]) : suffix match
+ shdr_len([<name>[,<occ>]]) : length match
+ shdr_reg([<name>[,<occ>]]) : regex match
+ shdr_sub([<name>[,<occ>]]) : substring match
+
+res.hdr_cnt([<name>]) : integer
+shdr_cnt([<name>]) : integer (deprecated)
+ Returns an integer value representing the number of occurrences of response
+ header field name <name>, or the total number of header fields if <name> is
+ not specified. The function considers any comma as a delimiter for distinct
+ values. If this is not desired, the res.fhdr_cnt() fetch should be used
+ instead.
-url_end <string>
- Returns true when the URL ends with one of the strings. It has very limited
- use. "path_end" should be used instead for filename matching.
+res.hdr_ip([<name>[,<occ>]]) : ip
+shdr_ip([<name>[,<occ>]]) : ip (deprecated)
+ This extracts the last occurrence of header <name> in an HTTP response,
+ convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
+ specific occurrence might be specified as a position number. Positive values
+ indicate a position from the first occurrence, with 1 being the first one.
+ Negative values indicate positions relative to the last one, with -1 being
+ the last one. This can be useful to learn some data into a stick table.
-url_ip <address>
- Applies to the IPv4 or IPv6 address specified in the absolute URI in an HTTP
- request. It can be used to prevent access to certain resources such as local
- network. It is useful with option "http_proxy".
+res.hdr_val([<name>[,<occ>]]) : integer
+shdr_val([<name>[,<occ>]]) : integer (deprecated)
+ This extracts the last occurrence of header <name> in an HTTP response, and
+ converts it to an integer value. Optionally, a specific occurrence might be
+ specified as a position number. Positive values indicate a position from the
+ first occurrence, with 1 being the first one. Negative values indicate
+ positions relative to the last one, with -1 being the last one. This can be
+ useful to learn some data into a stick table.
-url_len <integer>
- Returns true when the url length matches the values or ranges specified. This
- may be used to detect abusive requests for instance.
+res.ver : string
+resp_ver : string (deprecated)
+ Returns the version string from the HTTP response, for example "1.1". This
+ can be useful for logs, but is mostly there for ACL.
-url_port <integer>
- Applies to the port specified in the absolute URI in an HTTP request. It can
- be used to prevent access to certain resources. It is useful with option
- "http_proxy". Note that if the port is not specified in the request, port 80
- is assumed.
+ ACL derivatives :
+ resp_ver : exact string match
-url_reg <regex>
- Returns true when the URL matches one of the regular expressions. It can be
- used any time, but it is important to remember that regex matching is slower
- than other methods. See also "base_reg", "path_reg" and all "url_" criteria.
+set-cookie([<name>]) : string (deprecated)
+ This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
+ header line from the response and uses the corresponding value to match. This
+ can be comparable to what "appsession" does with default options, but with
+ support for multi-peer synchronization and state keeping across restarts.
-url_sub <string>
- Returns true when the URL contains one of the strings. It can be used to
- detect particular patterns in query strings for example. See also "path_sub".
+ This fetch function is deprecated and has been superseded by the "res.cook"
+ fetch. This keyword will disappear soon.
-urlp(<name>) <string>
- Note: all "urlp*" matching criteria apply to the first occurrence of the
- parameter <name> in the query string. The parameter name is case-sensitive.
+ See also : "appsession"
- The "urlp" matching criteria returns true if the designated URL parameter
- matches any of the strings. This can be used to check for exact values.
+status : integer
+ Returns an integer containing the HTTP status code in the HTTP response, for
+ example, 302. It is mostly used within ACLs and integer ranges, for example,
+ to remove any Location header if the response is not a 3xx.
-urlp_beg(<name>) <string>
- Returns true when the URL parameter "<name>" begins with one of the strings.
- This can be used to check whether a URL begins with a slash or with a
- protocol scheme.
+url : string
+ This extracts the request's URL as presented in the request. A typical use is
+ with prefetch-capable caches, and with portals which need to aggregate
+ multiple information from databases and keep them in caches. With ACLs, using
+ "path" is preferred over using "url", because clients may send a full URL as
+ is normally done with proxies. The only real use is to match "*" which does
+ not match in "path", and for which there is already a predefined ACL. See
+ also "path" and "base".
-urlp_dir(<name>) <string>
- Returns true when the URL parameter "<name>" contains one of the strings
- either isolated or delimited with slashes. This is used to perform filename
- or directory name matching in a specific URL parameter without the risk of
- wrong match due to colliding prefixes. See also "path_dir" and "urlp_sub".
+ ACL derivatives :
+ url : exact string match
+ url_beg : prefix match
+ url_dir : subdir match
+ url_dom : domain match
+ url_end : suffix match
+ url_len : length match
+ url_reg : regex match
+ url_sub : substring match
-urlp_dom(<name>) <string>
- Returns true when one of the strings is found isolated or delimited with dots
- in the URL parameter "<name>". This is used to perform domain name matching
- in a specific URL parameter without the risk of wrong match due to colliding
- prefixes. See also "urlp_sub".
+url_ip : ip
+ This extracts the IP address from the request's URL when the host part is
+ presented as an IP address. Its use is very limited. For instance, a
+ monitoring system might use this field as an alternative for the source IP in
+ order to test what path a given source address would follow, or to force an
+ entry in a table for a given source address. With ACLs it can be used to
+ restrict access to certain systems through a proxy, for example when combined
+ with option "http_proxy".
-urlp_end(<name>) <string>
- Returns true when the URL parameter "<name>" ends with one of the strings.
+url_port : integer
+ This extracts the port part from the request's URL. Note that if the port is
+ not specified in the request, port 80 is assumed. With ACLs it can be used to
+ restrict access to certain systems through a proxy, for example when combined
+ with option "http_proxy".
-urlp_ip(<name>) <ip_address>
- Returns true when the URL parameter "<name>" contains an IPv4 or IPv6 address
- which matches one of the specified addresses.
+urlp(<name>[,<delim>]) : string
+url_param(<name>[,<delim>]) : string
+ This extracts the first occurrence of the parameter <name> in the query
+ string, which begins after either '?' or <delim>, and which ends before '&',
+ ';' or <delim>. The parameter name is case-sensitive. The result is a string
+ corresponding to the value of the parameter <name> as presented in the
+ request (no URL decoding is performed). This can be used for session
+ stickiness based on a client ID, to extract an application cookie passed as a
+ URL parameter, or in ACLs to apply some checks. Note that the ACL version of
+ this fetch do not iterate over multiple parameters and stop at the first one
+ as well.
-urlp_len(<name>) <integer>
- Returns true when the URL parameter "<name>" has a length matching the values
- or ranges specified. This is used to detect abusive requests for instance.
+ ACL derivatives :
+ urlp(<name>[,<delim>]) : exact string match
+ urlp_beg(<name>[,<delim>]) : prefix match
+ urlp_dir(<name>[,<delim>]) : subdir match
+ urlp_dom(<name>[,<delim>]) : domain match
+ urlp_end(<name>[,<delim>]) : suffix match
+ urlp_len(<name>[,<delim>]) : length match
+ urlp_reg(<name>[,<delim>]) : regex match
+ urlp_sub(<name>[,<delim>]) : substring match
-urlp_reg(<name>) <regex>
- Returns true when the URL parameter "<name>" matches one of the regular
- expressions. It can be used any time, but it is important to remember that
- regex matching is slower than other methods. See also "path_reg" and all
- "urlp_" criteria.
-urlp_sub(<name>) <string>
- Returns true when the URL parameter "<name>" contains one of the strings. It
- can be used to detect particular patterns in query strings for example. See
- also "path_sub" and other "urlp_" criteria.
+ Example :
+ # match http://example.com/foo?PHPSESSIONID=some_id
+ stick on urlp(PHPSESSIONID)
+ # match http://example.com/foo;JSESSIONID=some_id
+ stick on urlp(JSESSIONID,;)
-urlp_val(<name>) <integer>
- Returns true when the URL parameter "<name>" starts with a number matching
- the values or ranges specified. Note that the absence of the parameter does
- not match anything. Integers are unsigned so it is not possible to match
- negative data.
+urlp_val(<name>[,<delim>]) : integer
+ See "urlp" above. This one extracts the URL parameter <name> in the request
+ and converts it to an integer value. This can be used for session stickiness
+ based on a user ID for example, or with ACLs to match a page number or price.
-7.6. Pre-defined ACLs
+7.4. Pre-defined ACLs
---------------------
Some predefined ACLs are hard-coded so that they do not have to be declared in
@@ -9734,1191 +10228,6 @@
WAIT_END wait_end wait for end of content analysis
---------------+-----------------------------+---------------------------------
-
-7.7. Using ACLs to form conditions
-----------------------------------
-
-Some actions are only performed upon a valid condition. A condition is a
-combination of ACLs with operators. 3 operators are supported :
-
- - AND (implicit)
- - OR (explicit with the "or" keyword or the "||" operator)
- - Negation with the exclamation mark ("!")
-
-A condition is formed as a disjunctive form:
-
- [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ...
-
-Such conditions are generally used after an "if" or "unless" statement,
-indicating when the condition will trigger the action.
-
-For instance, to block HTTP requests to the "*" URL with methods other than
-"OPTIONS", as well as POST requests without content-length, and GET or HEAD
-requests with a content-length greater than 0, and finally every request which
-is not either GET/HEAD/POST/OPTIONS !
-
- acl missing_cl hdr_cnt(Content-length) eq 0
- block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl
- block if METH_GET HTTP_CONTENT
- block unless METH_GET or METH_POST or METH_OPTIONS
-
-To select a different backend for requests to static contents on the "www" site
-and to every request on the "img", "video", "download" and "ftp" hosts :
-
- acl url_static path_beg /static /images /img /css
- acl url_static path_end .gif .png .jpg .css .js
- acl host_www hdr_beg(host) -i www
- acl host_static hdr_beg(host) -i img. video. download. ftp.
-
- # now use backend "static" for all static-only hosts, and for static urls
- # of host "www". Use backend "www" for the rest.
- use_backend static if host_static or host_www url_static
- use_backend www if host_www
-
-It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL
-expressions that are built on the fly without needing to be declared. They must
-be enclosed between braces, with a space before and after each brace (because
-the braces must be seen as independent words). Example :
-
- The following rule :
-
- acl missing_cl hdr_cnt(Content-length) eq 0
- block if METH_POST missing_cl
-
- Can also be written that way :
-
- block if METH_POST { hdr_cnt(Content-length) eq 0 }
-
-It is generally not recommended to use this construct because it's a lot easier
-to leave errors in the configuration when written that way. However, for very
-simple rules matching only one source IP address for instance, it can make more
-sense to use them than to declare ACLs with random names. Another example of
-good use is the following :
-
- With named ACLs :
-
- acl site_dead nbsrv(dynamic) lt 2
- acl site_dead nbsrv(static) lt 2
- monitor fail if site_dead
-
- With anonymous ACLs :
-
- monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 }
-
-See section 4.2 for detailed help on the "block" and "use_backend" keywords.
-
-
-7.8. Pattern extraction
------------------------
-
-The stickiness features relies on pattern extraction in the request and
-response. Sometimes the data needs to be converted first before being stored,
-for instance converted from ASCII to IP or upper case to lower case.
-
-All these operations of data extraction and conversion are defined as
-"pattern extraction rules". A pattern rule always has the same format. It
-begins with a single pattern fetch word, potentially followed by a list of
-arguments within parenthesis then an optional list of transformations. As
-much as possible, the pattern fetch functions use the same name as their
-equivalent used in ACLs.
-
-The list of currently supported pattern fetch functions is the following :
-
- always_false
- Always returns the boolean "false" value.
-
- always_true
- Always returns the boolean "true" value.
-
- avg_queue([<backend>])
- Returns the total number of queued connections of the designated
- backend divided by the number of active servers. The current
- backend is used if no backend is specified. This is very similar
- to "queue" except that the size of the farm is considered, in
- order to give a more accurate measurement of the time it may
- take for a new connection to be processed. The main usage is
- with ACL to return a sorry page to new users when it becomes
- certain they will get a degraded service, or to pass to the
- backend servers in a header so that they decide to work in
- degraded mode or to disable some functions to speed up the
- processing a bit. Note that in the event there would not be
- any active server anymore, we would consider twice the number
- of queued connections as the measured value. This is a fair
- estimate, as we expect one server to get back soon anyway, but
- we still prefer to send new traffic to another backend if in
- better shape. See also the "queue", "be_conn", and
- "be_sess_rate" sample fetches.
-
- base This returns the concatenation of the first Host header and the
- path part of the request, which starts at the first slash and
- ends before the question mark. It can be useful in virtual
- hosted environments to detect URL abuses as well as to improve
- shared caches efficiency. Using this with a limited size stick
- table also allows one to collect statistics about most commonly
- requested objects by host/path.
-
- base32 This returns a 32-bit hash of the value returned by the "base"
- fetch method above. This is useful to track per-URL activity on
- high traffic sites without having to store all URLs. Instead a
- shorter hash is stored, saving a lot of memory. The output type
- is an unsigned integer.
-
- base32+src This returns the concatenation of the base32 fetch above and the
- src fetch below. The resulting type is of type binary, with a
- size of 8 or 20 bytes depending on the source address family.
- This can be used to track per-IP, per-URL counters.
-
- be_conn([<backend>])
- Returns the number of currently established connections on the
- the backend, possibly including the connection being evaluated.
- If no backend name is specified, the current one is used. But it
- is also possible to check another backend. It can be used to use
- a specific farm when the nominal one is full. See also the
- "fe_conn", "queue" and "be_sess_rate" criteria.
-
- be_id Returns an integer containing the current backend's id.
-
- be_sess_rate([<backend>])
- Returns an integer value corresponding to the sessions creation
- rate on the backend, in number of new sessions per second. This
- is used with ACLs to switch to an alternate backend when an
- expensive or fragile one reaches too high a session rate, or to
- limit abuse of service (eg. prevent sucking of an online
- dictionary). It can also be useful to add this element to logs
- using a log-format directive.
-
- connslots([<backend>])
- Returns an integer value corresponding to the number of
- connection slots still available in the backend, by totalizing
- the maximum amount of connections on all servers and the maximum
- queue size. This is only used with ACLs. See the ACL "connslots"
- keyword description for more information on possible caveats.
-
- cook([<name>])
- This is an alias for "req.cook".
-
- cookie([<name>])
- This extracts the last occurrence of the cookie name <name> on a
- "Cookie" header line from the request, or a "Set-Cookie" header
- from the response, and returns its value as a string. A typical
- use is to get multiple clients sharing a same profile use the
- same server. This can be similar to what "appsession" does with
- the "request-learn" statement, but with support for multi-peer
- synchronization and state keeping across restarts. If no name is
- specified, the first cookie value is returned.
-
- See also : "appsession"
-
- cook_cnt([<name>])
- This is an alias for "req.cook_cnt".
-
- cook_val([<name>])
- This is an alias for "req.cook_val".
-
- dst This is the destination IPv4 address of the session on the
- client side, which is the address the client connected to.
- It can be useful when running in transparent mode. It is of
- type IPv4 and works on both IPv4 and IPv6 tables.
- On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
- according to RFC 4291.
-
- dst_conn
- Returns an integer value corresponding to the number of
- currently established connections on the same socket including
- the one being evaluated. It is normally used with ACLs but can
- as well be used to pass the information to servers in an HTTP
- header or in logs. See also "fe_conn" and "dst_conn".
-
- dst_port This is the destination TCP port of the session on the client
- side, which is the port the client connected to. This might be
- used when running in transparent mode or when assigning dynamic
- ports to some clients for a whole application session. It is of
- type integer and only works with such tables.
-
- fe_conn([<frontend>])
- Returns the number of currently established connections on the
- the frontend, possibly including the connection being evaluated.
- If no frontend name is specified, the current one is used. But
- it is also possible to check another frontend. It can be used to
- return a sorry page before hard-blocking, or to use a specific
- backend to drain new requests when the farm is considered full.
- This is mostly used with ACLs but can also be used to pass some
- statistics to servers in HTTP headers. See also the "dst_conn",
- "be_conn", "fe_sess_rate" criteria.
-
- fe_id Returns an integer containing the current frontend's id.
-
- fe_sess_rate([<frontend>])
- Returns an integer value corresponding to the sessions creation
- rate on the frontend, in number of new sessions per second. This
- is used with ACLs to limit the incoming session rate to an
- acceptable range in order to prevent abuse of service at the
- earliest moment. It can also be useful to add this element to
- logs using a log-format directive.
-
- hdr(<name>[,<occ>])
- This is an alias for "req.hdr" or "res.hdr" depending whether it
- is used on the request path or the response path. Since it is
- ambiguous, it is recommended not to use this form.
-
- hdr_cnt([<name>])
- This is an alias for "req.hdr_cnt".
-
- hdr_ip([<name>[,<occ>]])
- This is an alias for "req.hdr_ip".
-
- hdr_val([<name>[,<occ>]])
- This is an alias for "req.hdr_val".
-
- http_auth(<userlist>)
- http_auth_group(<userlist>)
- Returns a boolean indicating whether the authentication data
- received from the client match a username & password stored in
- the specified userlist. These fetch functions are not really
- useful outside of ACLs.
-
- http_first_req
- Returns true when the request being processed is the first one
- of the connection. This can be used to add or remove headers
- that may be missing from some requests when a request is not the
- first one, or to help grouping requests in the logs.
-
- method
- Returns an integer value corresponding to the to the method in
- the HTTP request. For example, "GET" equals 1 (check sources to
- establish the matching). Value 9 means "other method" and may be
- converted to a string extracted from the stream. This should not
- be used directly, this is only meant to be used from ACLs.
-
- nbsrv([<backend>])
- Returns an integer value corresponding to the number of usable
- servers of either the current backend or the named backend. This
- is mostly used with ACLs but can also be useful when added to
- logs.
-
- path This extracts the request's URL path (without the host part). A
- typical use is with prefetch-capable caches, and with portals
- which need to aggregate multiple information from databases and
- keep them in caches. Note that with outgoing caches, it would be
- wiser to use "url" instead.
-
- payload(<offset>,<length>)
- This is an alias for "req.payload" when used in the context of a
- request (eg: "stick on", "stick match"), and for "res.payload"
- when used in the context of a response such as in
- "stick store response".
-
- payload_lv(<offset1>,<length>[,<offset2>])
- This is an alias for "req.payload_lv" when used in the context
- of a request (eg: "stick on" or "stick match"), and for
- "res.payload_lv" when used in the context of a response such as
- in "stick store response".
-
- queue([<backend>])
- Returns the total number of queued connections of the designated
- backend, including all the connections in server queues. If no
- backend name is specified, the current one is used, but it is
- also possible to check another one. This is useful with ACLs
- or to pass statistics to backend servers.
-
- rdp_cookie(<name>)
- This is an alias for "req.rdp_cookie".
-
- rdp_cookie_cnt([name])
- This is an alias for "req.rdp_cookie_cnt".
-
- rep_ssl_hello_type
- This is an alias for "res.ssl_hello_type".
-
- req.cook([<name>])
- This extracts the last occurrence of the cookie name <name> on a
- "Cookie" header line from the request, and returns its value as
- string. If no name is specified, the first cookie value is
- returned.
-
- req.cook_cnt([<name>])
- Returns an integer value representing the number of occurrences of
- the cookie <name> in the request, or all cookies if <name> is not
- specified.
-
- req.cook_val([<name>])
- This extracts the last occurrence of the cookie name <name> on a
- "Cookie" header line from the request, and converts its value to
- an integer which is returned. If no name is specified, the first
- cookie value is returned.
-
- req.fhdr(<name>[,<occ>])
- This extracts the last occurrence of header <name> in an HTTP
- request. Optionally, a specific occurrence might be specified as
- a position number. Positive values indicate a position from the
- first occurrence, with 1 being the first one. Negative values
- indicate positions relative to the last one, with -1 being the
- last one. It differs from req.hdr() in that any commas present
- in the value are returned and are not used as delimiters. This
- is sometimes useful with headers such as User-Agent.
-
- req.fhdr_cnt([<name>])
- Returns an integer value representing the number of occurrences
- of request header field name <name>, or the total number of
- header fields if <name> is not specified. Contrary to its
- req.hdr_cnt() cousin, this function returns the number of full
- line headers and does not stop on commas.
-
- req.hdr(<name>[,<occ>])
- This extracts the last occurrence of header <name> in an HTTP
- request. Optionally, a specific occurrence might be specified as
- a position number. Positive values indicate a position from the
- first occurrence, with 1 being the first one. Negative values
- indicate positions relative to the last one, with -1 being the
- last one. A typical use is with the X-Forwarded-For header once
- converted to IP, associated with an IP stick-table. The function
- considers any comma as a delimiter for distinct values.
-
- req.hdr_cnt([<name>])
- Returns an integer value representing the number of occurrences
- of request header field name <name>, or the total number of
- header field values if <name> is not specified. The function
- considers any comma as a delimiter for distinct values.
-
- req.hdr_ip([<name>[,<occ>]])
- This extracts the last occurrence of header <name> in an HTTP
- request, converts it to an IPv4 or IPv6 address and returns this
- address. Optionally, a specific occurrence might be specified as
- a position number. Positive values indicate a position from the
- first occurrence, with 1 being the first one. Negative values
- indicate positions relative to the last one, with -1 being the
- last one. A typical use is with the X-Forwarded-For header.
-
- req.hdr_val([<name>[,<occ>]])
- This extracts the last occurrence of header <name> in an HTTP
- request, and converts it to an integer value. Optionally, a
- specific occurrence might be specified as a position number.
- Positive values indicate a position from the first occurrence,
- with 1 being the first one. Negative values indicate positions
- relative to the last one, with -1 being the last one. A typical
- use is with the X-Forwarded-For header.
-
- req.len Returns an integer value corresponding to the number of bytes
- present in the request buffer. This is mostly used in ACL.
-
- req.payload(<offset>,<length>)
- This extracts a binary block of <length> bytes and starting at
- bytes <offset> in the request buffer.
-
- req.payload_lv(<offset1>,<length>[,<offset2>])
- This extracts a binary block. In a first step the size of the
- block is read from the request request buffer at <offset> bytes
- and considered coded on <length> bytes. In a second step data of
- the block are read from buffer at <offset2> bytes (by default
- <lengthoffset> + <lengthsize>). If <offset2> is prefixed by '+'
- or '-', it is relative to <lengthoffset> + <lengthsize> else it
- is absolute. Ex: see SSL session id example in "stick table"
- chapter.
-
- req.proto_http
- Returns true when data in the request buffer look like HTTP and
- correctly parses as such. It is the same parser as the common
- HTTP request parser which is used so there should be no
- surprises. This test may be used to report the protocol in TCP
- logs.
-
- req.rdp_cookie(<name>)
- This extracts the value of the rdp cookie <name> as a string
- and uses this value to match. This enables implementation of
- persistence based on the mstshash cookie. This is typically
- done if there is no msts cookie present.
-
- This differs from "balance rdp-cookie" in that any balancing
- algorithm may be used and thus the distribution of clients
- to backend servers is not linked to a hash of the RDP
- cookie. It is envisaged that using a balancing algorithm
- such as "balance roundrobin" or "balance leastconn" will
- lead to a more even distribution of clients to backend
- servers than the hash used by "balance rdp-cookie".
-
- Example :
- listen tse-farm
- bind 0.0.0.0:3389
- # wait up to 5s for an RDP cookie in the request
- tcp-request inspect-delay 5s
- tcp-request content accept if RDP_COOKIE
- # apply RDP cookie persistence
- persist rdp-cookie
- # Persist based on the mstshash cookie
- # This is only useful makes sense if
- # balance rdp-cookie is not used
- stick-table type string size 204800
- stick on req.rdp_cookie(mstshash)
- server srv1 1.1.1.1:3389
- server srv1 1.1.1.2:3389
-
- See also : "balance rdp-cookie", "persist rdp-cookie",
- "tcp-request" and the "req_rdp_cookie" ACL.
-
- req.rdp_cookie_cnt([name])
- Tries to parse the request buffer as RDP protocol, then returns
- an integer corresponding to the number of RDP cookies found. If
- an optional cookie name is passed, only cookies matching this
- name are considered. This is mostly used in ACL.
-
- req.ssl_hello_type
- Returns an integer value containing the type of the SSL hello
- message found in the request buffer. Note that this only applies
- to raw contents found in the request buffer and not to contents
- deciphered via an SSL data layer, so this will not work with
- "bind" lines having the "ssl" option. This is mostly used in
- ACL.
-
- req.ssl_sni Returns a string containing the value of the Server Name TLS
- extension sent by a client in a TLS stream passing through the
- request buffer. Note that this only applies to raw contents
- found in the request buffer and not to contents deciphered via
- an SSL data layer, so this will not work with "bind" lines
- having the "ssl" option. This is mostly used in ACL.
-
- req.ssl_ver Returns an integer value containing the version of the SSL/TLS
- protocol of a stream present in the request buffer. The value is
- composed of the major version multiplied by 65536, added to the
- minor version. Note that this only applies to raw contents found
- in the request buffer and not to contents deciphered via an SSL
- data layer, so this will not work with "bind" lines having the
- "ssl" option. This is mostly used in ACL.
-
- req.ver Returns the version string from the HTTP request, for example
- "1.1". This can be useful for logs, but is mostly there for ACL.
-
- req_len This is an alias for "req.len".
-
- req_proto_http
- This is an alias for "req_proto_http".
-
- req_ssl_hello_type
- This is an alias for "req.ssl_hello_type".
-
- req_ssl_sni This is an alias for "req.ssl_sni".
-
- req_ssl_ver This is an alias for "req.ssl_ver".
-
- req_ver This is an alias for "req.ver".
-
- res.comp Returns the boolean "true" value if the response has been
- compressed by HAProxy, otherwise returns boolean "false".
-
- res.comp_algo
- Returns a string containing the name of the algorithm used if
- the response was compressed by HAProxy.
-
- res.cook([<name>])
- This extracts the last occurrence of the cookie name <name> on a
- "Set-Cookie" header line from the response, and returns its
- value as string. If no name is specified, the first cookie value
- is returned.
-
- res.cook_cnt([<name>])
- Returns an integer value representing the number of occurrences of
- the cookie <name> in the response, or all cookies if <name> is not
- specified.
-
- res.cook_val([<name>])
- This extracts the last occurrence of the cookie name <name> on a
- "Set-Cookie" header line from the response, and converts its
- value to an integer which is returned. If no name is specified,
- the first cookie value is returned.
-
- res.fhdr(<name>[,<occ>])
- This extracts the last occurrence of header <name> in an HTTP
- response. Optionally, a specific occurrence might be specified
- as a position number. Positive values indicate a position from
- the first occurrence, with 1 being the first one. Negative
- values indicate positions relative to the last one, with -1
- being the last one. It differs from res.hdr() in that any commas
- present in the value are returned and are not used as delimiters.
- This is sometimes useful with headers such as Date or Expires.
-
- res.fhdr_cnt([<name>])
- Returns an integer value representing the number of occurrences
- of response header field name <name>, or the total number of
- header fields if <name> is not specified. Contrary to its
- res.hdr_cnt() cousin, this function returns the number of full
- line headers and does not stop on commas.
-
- res.hdr(<name>[,<occ>])
- This extracts the last occurrence of header <name> in an HTTP
- response. Optionally, a specific occurrence might be specified
- as a position number. Positive values indicate a position from
- the first occurrence, with 1 being the first one. Negative
- values indicate positions relative to the last one, with -1
- being the last one. This can be useful to learn some data into
- a stick-table. The function considers any comma as a delimiter
- for distinct values.
-
- res.hdr_cnt([<name>])
- Returns an integer value representing the number of occurrences
- of response header field name <name>, or the total number of
- header fields if <name> is not specified. The function considers
- any comma as a delimiter for distinct values.
-
- res.hdr_ip([<name>[,<occ>]])
- This extracts the last occurrence of header <name> in an HTTP
- response, convert it to an IPv4 or IPv6 address and returns this
- address. Optionally, a specific occurrence might be specified as
- a position number. Positive values indicate a position from the
- first occurrence, with 1 being the first one. Negative values
- indicate positions relative to the last one, with -1 being the
- last one. This can be useful to learn some data into a stick
- table.
-
- res.hdr_val([<name>[,<occ>]])
- This extracts the last occurrence of header <name> in an HTTP
- response, and converts it to an integer value. Optionally, a
- specific occurrence might be specified as a position number.
- Positive values indicate a position from the first occurrence,
- with 1 being the first one. Negative values indicate positions
- relative to the last one, with -1 being the last one. This can
- be useful to learn some data into a stick table.
-
- res.payload(<offset>,<length>)
- This extracts a binary block of <length> bytes and starting at
- bytes <offset> in the response buffer.
-
- res.payload_lv(<offset1>,<length>[,<offset2>])
- This extracts a binary block. In a first step the size of the
- block is read from the response request buffer at <offset> bytes
- and considered coded on <length> bytes. In a second step data of
- the block are read from buffer at <offset2> bytes (by default
- <lengthoffset> + <lengthsize>). If <offset2> is prefixed by '+'
- or '-', it is relative to <lengthoffset> + <lengthsize> else it
- is absolute. Ex: see SSL session id example in "stick table"
- chapter.
-
- res.ssl_hello_type
- Returns an integer value containing the type of the SSL hello
- message found in the response buffer. Note that this only
- applies to raw contents found in the response buffer and not to
- contents deciphered via an SSL data layer, so this will not work
- with "server" lines having the "ssl" option. This is mostly used
- in ACL.
-
- res.ver Returns the version string from the HTTP response, for example
- "1.1". This can be useful for logs, but is mostly there for ACL.
-
- resp_ver This is an alias for "res.ver".
-
- sc1_bytes_in_rate
- sc2_bytes_in_rate
- sc3_bytes_in_rate
- Returns the average client-to-server bytes rate from the
- currently tracked counters, measured in amount of bytes over the
- period configured in the table. See also src_bytes_in_rate.
-
- sc1_bytes_out_rate
- sc2_bytes_out_rate
- sc3_bytes_out_rate
- Returns the average server-to-client bytes rate from the
- currently tracked counters, measured in amount of bytes over the
- period configured in the table. See also src_bytes_out_rate.
-
- sc1_clr_gpc0
- sc2_clr_gpc0
- sc3_clr_gpc0
- Clears the first General Purpose Counter associated to the
- currently tracked counters, and returns its previous value.
- This is only useful when used by ACLs.
-
- sc1_conn_cnt
- sc2_conn_cnt
- sc3_conn_cnt
- Returns the cumulated number of incoming connections from
- currently tracked counters. See also src_conn_cnt.
-
- sc1_conn_cur
- sc2_conn_cur
- sc3_conn_cur
- Returns the current amount of concurrent connections tracking
- the same tracked counters. This number is automatically
- incremented when tracking begins and decremented when tracking
- stops. See also src_conn_cur.
-
- sc1_conn_rate
- sc2_conn_rate
- sc3_conn_rate
- Returns the average connection rate from the currently tracked
- counters, measured in amount of connections over the period
- configured in the table. See also src_conn_rate.
-
- sc1_get_gpc0
- sc2_get_gpc0
- sc3_get_gpc0
- Returns the value of the first General Purpose Counter
- associated to the currently tracked counters. See also
- src_get_gpc0 and sc1/sc2_inc_gpc0.
-
- sc1_gpc0_rate
- sc2_gpc0_rate
- sc3_gpc0_rate
- Returns the average increment rate of the first General Purpose
- Counter associated to the currently tracked counters. It reports
- the frequency which the gpc0 counter was incremented over the
- configured period. See also src_gpc0_rate, sc1/sc2/sc3_get_gpc0,
- and sc1/sc2/sc3_inc_gpc0. Note that the "gpc0_rate" counter must
- be stored in the stick-table for a value to be returned, as
- "gpc0" only holds the event count.
-
- sc1_http_err_cnt
- sc2_http_err_cnt
- sc3_http_err_cnt
- Returns the cumulated number of HTTP errors from the currently
- tracked counters. This includes the both request errors and 4xx
- error responses. See also src_http_err_cnt.
-
- sc1_http_err_rate
- sc2_http_err_rate
- sc3_http_err_rate
- Returns the average rate of HTTP errors from the currently
- tracked counters, measured in amount of errors over the period
- configured in the table. This includes the both request errors
- and 4xx error responses. See also src_http_err_rate.
-
- sc1_http_req_cnt
- sc2_http_req_cnt
- sc3_http_req_cnt
- Returns the cumulated number of HTTP requests from the currently
- tracked counters. This includes every started request, valid or
- not. See also src_http_req_cnt.
-
- sc1_http_req_rate
- sc2_http_req_rate
- sc3_http_req_rate
- Returns the average rate of HTTP requests from the currently
- tracked counters, measured in amount of requests over the period
- configured in the table. This includes every started request,
- valid or not. See also src_http_req_rate.
-
- sc1_inc_gpc0
- sc2_inc_gpc0
- sc3_inc_gpc0
- Increments the first General Purpose Counter associated to the
- currently tracked counters, and returns its new value. This is
- only useful when used by ACLs.
-
- sc1_kbytes_in
- sc2_kbytes_in
- sc3_kbytes_in
- Returns the amount of client-to-server data from the currently
- tracked counters, measured in kilobytes over the period
- configured in the table. The value being stored as a 32-bit
- integer, it wraps at 4 terabytes. See also src_kbytes_in.
-
- sc1_kbytes_out
- sc2_kbytes_out
- sc3_kbytes_out
- Returns the amount of server-to-client data from the currently
- tracked counters, measured in kilobytes over the period
- configured in the table. The value being stored as a 32-bit
- integer, it wraps at 4 terabytes. See also src_kbytes_out.
-
- sc1_sess_cnt
- sc2_sess_cnt
- sc3_sess_cnt
- Returns the cumulated number of incoming connections that were
- transformed into sessions, which means that they were accepted
- by a "tcp-request connection" rule, from the currently tracked
- counters. A backend may count more sessions than connections
- because each connection could result in many backend sessions if
- some HTTP keep-alive is performed over the connection with the
- client. See also src_sess_cnt.
-
- sc1_sess_rate
- sc2_sess_rate
- sc3_sess_rate
- Returns the average session rate from the currently tracked
- counters, measured in amount of sessions over the period
- configured in the table. A session is a connection that got past
- the early "tcp-request connection" rules. A backend may count
- more sessions than connections because each connection could
- result in many backend sessions if some HTTP keep-alive is
- performed over the connection with the client. See also
- src_sess_rate.
-
- sc1_tracked
- sc2_tracked
- sc3_tracked
- Returns true if the designated session counter is currently
- being tracked by the current session. This can be useful when
- deciding whether or not we want to set some values in a header
- passed to the server.
-
- sc1_trackers
- sc2_trackers
- sc3_trackers
- Returns the current amount of concurrent connections tracking
- the same tracked counters. This number is automatically
- incremented when tracking begins and decremented when tracking
- stops. It differs from sc1_conn_cur in that it does not rely on
- any stored information but on the table's reference count (the
- "use" value which is returned by "show table" on the CLI). This
- may sometimes be more suited for layer7 tracking. It can be used
- to tell a server how many concurrent connections there are from
- a given address for example.
-
- scook([<name>])
- This is an alias for "res.cook".
-
- scook_cnt([<name>])
- This is an alias for "res.cook_cnt".
-
- scook_val([<name>])
- This is an alias for "res.cook_val".
-
- set-cookie(<name>)
- This fetch function is deprecated and has been superseded by the
- "cookie" fetch which is capable of handling both requests and
- responses. This keyword will disappear soon.
-
- This extracts the last occurrence of the cookie name <name> on a
- "Set-Cookie" header line from the response and uses the
- corresponding value to match. This can be comparable to what
- "appsession" does with default options, but with support for
- multi-peer synchronization and state keeping across restarts.
-
- See also : "appsession"
-
- shdr(<name>[,<occ>])
- This is an alias for "res.hdr".
-
- shdr_cnt([<name>])
- This is an alias for "res.hdr_cnt".
-
- shdr_ip([<name>[,<occ>]])
- This is an alias for "res.hdr_ip".
-
- shdr_val([<name>[,<occ>]])
- This is an alias for "res.hdr_val".
-
- so_id Returns an integer containing the listening socket's id.
-
- src This is the source IPv4 address of the client of the session.
- It is of type IPv4 and works on both IPv4 and IPv6 tables.
- On IPv6 tables, IPv4 address is mapped to its IPv6 equivalent,
- according to RFC 4291.
-
- src_bytes_in_rate([<table>])
- Returns the average bytes rate from the connection's source IPv4
- address in the current proxy's stick-table or in the designated
- stick-table, measured in amount of bytes over the period
- configured in the table. If the address is not found, zero is
- returned. See also sc1/sc2_bytes_in_rate.
-
- src_bytes_out_rate([<table>])
- Returns the average bytes rate to the connection's source IPv4
- address in the current proxy's stick-table or in the designated
- stick-table, measured in amount of bytes over the period
- configured in the table. If the address is not found, zero is
- returned. See also sc1/sc2_bytes_out_rate.
-
- src_clr_gpc0([<table>])
- Clears the first General Purpose Counter associated to the
- connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table, and returns its
- previous value. This is only useful when used by ACLs.
-
- src_conn_cnt([<table>])
- Returns the cumulated number of connections initiated from the
- current connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table. If the address is
- not found, zero is returned. See also sc1/sc2_conn_cnt.
-
- src_conn_cur([<table>])
- Returns the current amount of concurrent connections initiated
- from the current connection's source IPv4 address in the current
- proxy's stick-table or in the designated stick-table. If the
- address is not found, zero is returned. See also
- sc1/sc2_conn_cur.
-
- src_conn_rate([<table>])
- Returns the average connection rate from the connection's source
- IPv4 address in the current proxy's stick-table or in the
- designated stick-table, measured in amount of connections over
- the period configured in the table. If the address is not found,
- zero is returned. See also sc1/sc2_conn_rate.
-
- src_get_gpc0([<table>])
- Returns the value of the first General Purpose Counter
- associated to the connection's source IPv4 address in the
- current proxy's stick-table or in the designated stick-table. If
- the address is not found, zero is returned. See also
- sc1/sc2_get_gpc0 and src_inc_gpc0.
-
- src_gpc0_rate([<table>])
- Returns the average increment rate of the first General Purpose
- Counter associated to the connection's source IPv4 address in
- the current proxy's stick-table or in the designated stick-
- table. It reports the frequency which the gpc0 counter was
- incremented over the configured period. See also src_gpc0_rate,
- sc1/sc2/sc3_get_gpc0, and sc1/sc2/sc3_inc_gpc0. Note that the
- "gpc0_rate" counter must be stored in the stick-table for a
- value to be returned, as "gpc0" only holds the event count.
-
- src_http_err_cnt([<table>])
- Returns the cumulated number of HTTP errors from the current
- connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table. This includes the
- both request errors and 4xx error responses. If the address is
- not found, zero is returned. See also sc1/sc2_http_err_cnt.
-
- src_http_err_rate([<table>])
- Returns the average rate of HTTP errors from the current
- connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick- table, measured in
- amount of errors over the period configured in the table. This
- includes the both request errors and 4xx error responses. If the
- address is not found, zero is returned. See also
- sc1/sc2_http_err_rate.
-
- src_http_req_cnt([<table>])
- Returns the cumulated number of HTTP requests from the current
- connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table. This includes
- every started request, valid or not. If the address is not
- found, zero is returned. See also sc1/sc2_http_req_cnt.
-
- src_http_req_rate([<table>])
- Returns the average rate of HTTP requests from the current
- connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table, measured in amount
- of requests over the period configured in the table. This
- includes every started request, valid or not. If the address is
- not found, zero is returned. See also sc1/sc2_http_req_rate.
-
- src_inc_gpc0([<table>])
- Increments the first General Purpose Counter associated to the
- connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table, and returns its
- new value. This is only useful when used by ACLs.
-
- src_kbytes_in([<table>])
- Returns the amount of data received from the connection's source
- IPv4 address in the current proxy's stick-table or in the
- designated stick-table, measured in kilobytes over the period
- configured in the table. If the address is not found, zero is
- returned. The value being stored as a 32-bit integer, it wraps
- at 4 terabytes. See also sc1/sc2_kbytes_in.
-
- src_kbytes_out([<table>])
- Returns the amount of data sent to the connection's source IPv4
- address in the current proxy's stick-table or in the designated
- stick-table, measured in kilobytes over the period configured in
- the table. If the address is not found, zero is returned. The
- value being stored as a 32-bit integer, it wraps at 4 terabytes.
- See also sc1/sc2_kbytes_out.
-
- src_port This is the source TCP port of the session on the client side,
- which is the port the client connected from. It is very unlikely
- that this function will be useful but it's available at no cost.
- It is of type integer and only works with such tables.
-
- src_sess_cnt([<table>])
- Returns the cumulated number of connections initiated from the
- current connection's source IPv4 address in the current proxy's
- stick-table or in the designated stick-table, that were
- transformed into sessions, which means that they were accepted
- by "tcp-request" rules. If the address is not found, zero is
- returned. See also sc1/sc2_sess_cnt.
-
- src_sess_rate([<table>])
- Returns the average session rate from the connection's source
- IPv4 address in the current proxy's stick-table or in the
- designated stick-table, measured in amount of sessions over the
- period configured in the table. A session is a connection that
- got past the early "tcp-request" rules. If the address is not
- found, zero is returned. See also sc1/sc2_sess_rate.
-
- src_updt_conn_cnt([<table>])
- Creates or updates the entry associated to the source IPv4
- address in the current proxy's stick-table or in the designated
- stick-table. This is only useful when used by ACLs.
-
- srv_conn(<backend>/<server>)
- Returns an integer value corresponding to the number of
- currently established connections on this server, possibly
- including the connection being evaluated. It is only used with
- ACLs.
-
- srv_id Returns an integer containing the server's id when processing
- the response. While it's almost only used with ACLs, it may be
- used for logging or debugging.
-
- srv_is_up([<backend>/]<server>)
- Returns a the boolean TRUE value when the designated server is
- UP, and false when it is either DOWN or in maintenance mode. If
- <backend> is omitted, then the server is looked up in the
- current backend. It is almost only used with ACLs.
-
- srv_sess_rate(<backend>/<server>)
- Returns an integer corresponding to the sessions creation rate
- on the server, in number of new sessions per second. This is
- used with ACLs but may make sense with logs too.
-
- ssl_c_ca_err Returns the ID of the first error detected during verify of the
- client certificate at depth > 0, or 0 if no error was detected.
-
- ssl_c_ca_err_depth
- Returns the depth of the first error detected during verify. If
- no error is encountered in the CA chain, zero is returned.
-
- ssl_c_err Returns the ID of the first error detected during verify of the
- client certificate at depth == 0, or 0 if no errors.
-
- ssl_c_i_dn[(entry[,occ])]
- If no entry specified, returns the full distinguished name of
- the issuer of the certificate presented by the client when
- the incoming connection was made over an SSL/TLS transport
- layer. Otherwise returns the value of the first given entry
- found from the beginning of the DN. If a positive/negative
- occurrence number is specified as the optional second argument,
- it returns the value of the nth given entry found from the
- beginning/end of the DN. For instance to retrieve the common
- name ssl_c_i_dn(CN) and the second organization unit
- ssl_c_i_dn(OU,2).
-
- ssl_c_key_alg
- Returns the name of the algorithm used to generate the key of
- the certificate presented by the client when the incoming
- connection was made over an SSL/TLS transport layer.
-
- ssl_c_notafter
- Returns the end date presented by the client as a formatted
- string YYMMDDhhmmss[Z] when the incoming connection was made
- over an SSL/TLS transport layer.
-
- ssl_c_notbefore
- Returns the start date presented by the client as a formatted
- string YYMMDDhhmmss[Z] when the incoming connection was made
- over an SSL/TLS transport layer.
-
- ssl_c_s_dn[(entry[,occ])]
- If no entry specified, returns the full distinguished name of
- the subject of the certificate presented by the client when
- the incoming connection was made over an SSL/TLS transport
- layer. Otherwise returns the value of the first given entry
- found from the beginning of the DN. If a positive/negative
- occurrence number is specified as the optional second argument,
- it returns the value of the nth given entry found from the
- beginning/end of the DN. For instance to retrieve the common
- name ssl_c_s_dn(CN) and the second organization unit
- ssl_c_s_dn(OU,2).
-
- ssl_c_serial Returns the serial of the certificate presented by the client
- when the incoming connection was made over an SSL/TLS transport
- layer.
-
- ssl_c_sha1 Returns the SHA-1 fingerprint of the certificate presented by
- the client when the incoming connection was made over an SSL/TLS
- transport layer. This can be used to stick a client to a server,
- or to pass this information to a server.
-
- ssl_c_sig_alg
- Returns the name of the algorithm used to sign the certificate
- presented by the client when the incoming connection was made
- over an SSL/TLS transport layer.
-
- ssl_c_used
- Returns 1 if current SSL session use a client certificate,
- otherwise 0. See also "ssl_fc_has_crt".
-
- ssl_c_verify Returns the verify result errorID when the incoming connection
- was made over an SSL/TLS transport layer, otherwise zero if no
- error is encountered.
-
- ssl_c_version
- Returns the version of the certificate presented by the client
- when the incoming connection was made over an SSL/TLS transport
- layer.
-
- ssl_f_i_dn[(entry[,occ])]
- If no entry specified, returns the full distinguished name of
- the issuer of the certificate presented by the frontend when
- the incoming connection was made over an SSL/TLS transport
- layer. Otherwise returns the value of the first given entry
- found from the beginning of the DN. If a positive/negative
- occurrence number is specified as the optional second argument,
- it returns the value of the nth given entry found from the
- beginning/end of the DN. For instance to retrieve the common
- name ssl_f_i_dn(CN) and the second organization unit
- ssl_f_i_dn(OU,2).
-
- ssl_f_key_alg
- Returns the name of the algorithm used to generate the key of
- the certificate presented by the frontend when the incoming
- connection was made over an SSL/TLS transport layer.
-
- ssl_f_notafter
- Returns the end date presented by the frontend as a formatted
- string YYMMDDhhmmss[Z] when the incoming connection was made
- over an SSL/TLS transport layer.
-
- ssl_f_notbefore
- Returns the start date presented by the frontend as a formatted
- string YYMMDDhhmmss[Z] when the incoming connection was made
- over an SSL/TLS transport layer.
-
- ssl_f_s_dn[(entry[,occ])]
- If no entry specified, returns the full distinguished name of
- the subject of the certificate presented by the frontend when
- the incoming connection was made over an SSL/TLS transport
- layer. Otherwise returns the value of the first given entry
- found from the beginning of the DN. If a positive/negative
- occurrence number is specified as the optional second argument,
- it returns the value of the nth given entry found from the
- beginning/end of the DN. For instance to retrieve the common
- name ssl_f_s_dn(CN) and the second organization unit
- ssl_f_s_dn(OU,2).
-
- ssl_f_serial Returns the serial of the certificate presented by the frontend
- when the incoming connection was made over an SSL/TLS transport
- layer.
-
- ssl_f_sig_alg
- Returns the name of the algorithm used to sign the certificate
- presented by the frontend when the incoming connection was made
- over an SSL/TLS transport layer.
-
- ssl_f_version
- Returns the version of the certificate presented by the frontend
- when the incoming connection was made over an SSL/TLS transport
- layer.
-
- ssl_fc This checks the transport layer used on the front connection,
- and returns 1 if it was made via an SSL/TLS transport layer,
- otherwise zero.
-
- ssl_fc_alg_keysize
- Returns the symmetric cipher key size support d in bits when the
- incoming connection was made over an SSL/TLS transport layer.
-
- ssl_fc_cipher
- Returns the name of the used cipher when the incoming connection
- was made over an SSL/TLS transport layer.
-
- ssl_fc_has_crt
- Returns 1 if a client certificate is present in the front
- connection over SSL/TLS transport layer, otherwise 0.
- Note: on SSL session resumption with Session ID or TLS ticket,
- client certificate is not present in the current connection but
- may be retrieved from the cache or the ticket. So prefer
- "ssl_c_used" if you want to check if current SSL session uses
- a client certificate.
-
- ssl_fc_has_sni
- This checks the transport layer used by the front connection, and
- returns 1 if the connection was made via an SSL/TLS transport
- layer and the client sent a Server Name Indication TLS extension,
- otherwise zero. This requires that the SSL library is build with
- support for TLS extensions enabled (check haproxy -vv).
-
- ssl_fc_npn This extracts the Next Protocol Negociation field from an
- incoming connection made via an SSL/TLS transport layer and
- locally deciphered by haproxy. The result is a string containing
- the protocol name advertised by the client. The SSL library must
- have been built with support for TLS extensions enabled (check
- haproxy -vv). See also the "npn" bind keyword.
-
- ssl_fc_protocol
- Returns the name of the used protocol when the incoming
- connection was made over an SSL/TLS transport layer.
-
- ssl_fc_session_id
- Returns the SSL ID of the front connection when the incoming
- connection was made over an SSL/TLS transport layer. Useful to
- stick on a given client.
-
- ssl_fc_sni This extracts the Server Name Indication field from an incoming
- connection made via an SSL/TLS transport layer and locally
- deciphered by haproxy. The result typically is a string matching
- the HTTPS host name (253 chars or less). The SSL library must
- have been built with support for TLS extensions enabled (check
- haproxy -vv).
-
- ssl_fc_use_keysize
- Returns the symmetric cipher key size used in bits when the
- incoming connection was made over an SSL/TLS transport layer.
-
- status Returns an integer containing the HTTP status code in the HTTP
- response, for example, 302. It is mostly used within ACLs.
-
- table_avl([<table>])
- Returns the total number of available entries in the current
- proxy's stick-table or in the designated stick-table. See also
- table_cnt.
-
- table_cnt([<table>])
- Returns the total number of entries currently in use in the
- current proxy's stick-table or in the designated stick-table.
- See also src_conn_cnt and table_avl for other entry counting
- methods.
-
- url This extracts the request's URL as presented in the request. A
- typical use is with prefetch-capable caches, and with portals
- which need to aggregate multiple information from databases and
- keep them in caches. See also "path".
-
- urlp(<name>[,<delim>])
- Note: all "urlp*" sample fetch methods apply only to the first
- occurrence of the parameter <name> in the query string, which
- is delimited by character <delim> if specified, otherwise '&'.
- The parameter name is case-sensitive. This one extracts a string
- corresponding to the value of the parameter <name>. This can be
- used for session stickiness.
-
- urlp_val(<name>[,<delim>])
- See "urlp" above. This one extracts the URL parameter <name> in
- the request and converts it ao an integer value. This can be
- used for session stickiness.
-
- url_ip This extracts the IP address from the request's URL when the
- host part is presented as an IP address. Its use is very
- limited. For instance, a monitoring system might use this field
- as an alternative for the source IP in order to test what path a
- given source address would follow, or to force an entry in a
- table for a given source address.
-
- url_port This extracts the port part from the request's URL. It probably
- is totally useless but it was available at no cost.
-
- url_param(<name>[,<delim>])
- This extracts the first occurrence of the parameter <name> in
- the parameter string of the request and uses the corresponding
- value to match. Optionally, a delimiter can be provided. If not
- then the question mark '?' is used by default.
- A typical use is to get sticky session through url for cases
- where cookies cannot be used.
-
- Example :
- # match http://example.com/foo?PHPSESSIONID=some_id
- stick on url_param(PHPSESSIONID)
- # match http://example.com/foo;JSESSIONID=some_id
- stick on url_param(JSESSIONID,;)
-
- wait_end Always returns true or does not fetch. This is only used for ACL
- compatibility.
-
-
-The currently available list of transformations include :
-
- lower Convert a string pattern to lower case. This can only be placed
- after a string pattern fetch function or after a conversion
- function returning a string type. The result is of type string.
-
- upper Convert a string pattern to upper case. This can only be placed
- after a string pattern fetch function or after a conversion
- function returning a string type. The result is of type string.
-
- ipmask(<mask>) Apply a mask to an IPv4 address, and use the result for lookups
- and storage. This can be used to make all hosts within a
- certain mask to share the same table entries and as such use
- the same server. The mask can be passed in dotted form (eg:
- 255.255.255.0) or in CIDR form (eg: 24).
-
8. Logging
----------
@@ -11484,7 +10793,7 @@
string formats ("Q").
If a variable is named between square brackets ('[' .. ']') then it is used
-as a pattern extraction rule (see section 7.8). This it useful to add some
+as a pattern extraction rule (see section 7.3). This it useful to add some
less common information such as the client's SSL certificate's DN, or to log
the key that would be used to store an entry into a stick table.