capture.req.ver string
capture.res.hdr(<idx>) string
capture.res.ver string
-req.body binary
-req.body_param([<name>[,i]]) string
-req.body_len integer
-req.body_size integer
-req.cook([<name>]) string
cook([<name>]) string
-req.cook_cnt([<name>]) integer
cook_cnt([<name>]) integer
-req.cook_val([<name>]) integer
cook_val([<name>]) integer
-req.cook_names([<delim>]) string
cookie([<name>]) string
hdr([<name>[,<occ>]]) string
-request_date([<unit>]) integer
-req.fhdr(<name>[,<occ>]) string
-req.fhdr_cnt([<name>]) integer
-req.hdr([<name>[,<occ>]]) string
-req.hdr_cnt([<name>]) integer
hdr_cnt([<header>]) integer
-req.hdr_ip([<name>[,<occ>]]) ip
hdr_ip([<name>[,<occ>]]) ip
-req.hdr_val([<name>[,<occ>]]) integer
hdr_val([<name>[,<occ>]]) integer
-req.hdrs string
-req.hdrs_bin binary
-req.timer.hdr integer
-req.timer.idle integer
-req.timer.queue integer
-req.timer.tq integer
-res.timer.hdr integer
http_auth(<userlist>) boolean
http_auth_bearer([<header>]) string
http_auth_group(<userlist>) string
path string
pathq string
query([<options>]) string
+req.body binary
+req.body_len integer
+req.body_param([<name>[,i]]) string
+req.body_size integer
+req.cook([<name>]) string
+req.cook_cnt([<name>]) integer
+req.cook_names([<delim>]) string
+req.cook_val([<name>]) integer
+req.fhdr(<name>[,<occ>]) string
+req.fhdr_cnt([<name>]) integer
+req.hdr([<name>[,<occ>]]) string
+req.hdr_cnt([<name>]) integer
+req.hdr_ip([<name>[,<occ>]]) ip
req.hdr_names([<delim>]) string
+req.hdr_val([<name>[,<occ>]]) integer
+req.hdrs string
+req.hdrs_bin binary
+req.timer.hdr integer
+req.timer.idle integer
+req.timer.queue integer
+req.timer.tq integer
req.ver string
req_ver string
+request_date([<unit>]) integer
res.body binary
res.body_len integer
res.body_size integer
res.comp boolean
res.comp_algo string
res.cook([<name>]) string
-scook([<name>]) string
res.cook_cnt([<name>]) integer
-scook_cnt([<name>]) integer
-res.cook_val([<name>]) integer
-scook_val([<name>]) integer
res.cook_names([<delim>]) string
+res.cook_val([<name>]) integer
res.fhdr([<name>[,<occ>]]) string
res.fhdr_cnt([<name>]) integer
res.hdr([<name>[,<occ>]]) string
-shdr([<name>[,<occ>]]) string
res.hdr_cnt([<name>]) integer
-shdr_cnt([<name>]) integer
res.hdr_ip([<name>[,<occ>]]) ip
-shdr_ip([<name>[,<occ>]]) ip
res.hdr_names([<delim>]) string
res.hdr_val([<name>[,<occ>]]) integer
-shdr_val([<name>[,<occ>]]) integer
res.hdrs string
res.hdrs_bin binary
+res.timer.hdr integer
res.ver string
resp_ver string
+scook([<name>]) string
+scook_cnt([<name>]) integer
+scook_val([<name>]) integer
server_status integer
set-cookie([<name>]) string
+shdr([<name>[,<occ>]]) string
+shdr_cnt([<name>]) integer
+shdr_ip([<name>[,<occ>]]) ip
+shdr_val([<name>[,<occ>]]) integer
status integer
txn.status integer
txn.timer.total integer
unique-id string
url string
+url32 integer
+url32+src binary
url_ip ip
+url_param([<name>[,<delim>[,i]]]) string
url_port integer
urlp([<name>[,<delim>[,i]]]) string
-url_param([<name>[,<delim>[,i]]]) string
urlp_val([<name>[,<delim>[,i]]]) integer
-url32 integer
-url32+src binary
-------------------------------------------------+-------------
Detailed list:
"HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a
persistent flag.
+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" did 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.
+
+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
+ unambiguously apply to the request headers.
+
+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_bearer([<header>]) : string
+ Returns the client-provided token found in the authorization data when the
+ Bearer scheme is used (to send JSON Web Tokens for instance). No check is
+ performed on the data sent by the client.
+ If a specific <header> is supplied, it will parse this header instead of the
+ Authorization one.
+
+http_auth_group(<userlist>) : string
+ Returns a string corresponding to the user name found in the authentication
+ data received from the client if both the user name and password are valid
+ according to the specified userlist. The main purpose is to use it in ACLs
+ where it is then checked whether the user belongs to any group within a list.
+ This fetch function is not really useful outside of ACLs. Currently only http
+ basic auth is supported.
+
+ ACL derivatives :
+ http_auth_group(<userlist>) : group ...
+ Returns true when the user extracted from the request and whose password is
+ valid according to the specified userlist belongs to at least one of the
+ groups.
+
+http_auth_pass : string
+ Returns the user's password found in the authentication data received from
+ the client, as supplied in the Authorization header. Not checks are
+ performed by this sample fetch. Only Basic authentication is supported.
+
+http_auth_type : string
+ Returns the authentication method found in the authentication data received from
+ the client, as supplied in the Authorization header. Not checks are
+ performed by this sample fetch. Only Basic authentication is supported.
+
+http_auth_user : string
+ Returns the user name found in the authentication data received from the
+ client, as supplied in the Authorization header. Not checks are performed by
+ this sample fetch. Only Basic authentication is supported.
+
+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 to help grouping
+ requests in the logs.
+
+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.
+
+ ACL derivatives :
+ method : case insensitive method match
+
+ Example :
+ # only accept GET and HEAD requests
+ acl valid_method method GET HEAD
+ http-request deny if ! valid_method
+
+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 (e.g. "/login.php"), or directory parts using
+ the derivative forms. See also the "url" and "base" fetch methods. Please
+ note that any fragment reference in the URI ('#' after the path) is strictly
+ forbidden by the HTTP standard and will be rejected. However, if the frontend
+ receiving the request has "option accept-unsafe-violations-in-http-request",
+ then this fragment part will be accepted and will also appear in the path.
+
+ 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
+
+pathq : string
+ This extracts the request's URL path with the query-string, which starts at
+ the first slash. This sample fetch is pretty handy to always retrieve a
+ relative URI, excluding the scheme and the authority part, if any. Indeed,
+ while it is the common representation for an HTTP/1.1 request target, in
+ HTTP/2, an absolute URI is often used. This sample fetch will return the same
+ result in both cases. Please note that any fragment reference in the URI ('#'
+ after the path) is strictly forbidden by the HTTP standard and will be
+ rejected. However, if the frontend receiving the request has "option
+ accept-unsafe-violations-in-http-request", then this fragment part will be
+ accepted and will also appear in the path.
+
+query([<options>]) : string
+ This extracts the request's query string, which starts after the first
+ question mark. If no question mark is present, this fetch returns nothing. If
+ a question mark is present but nothing follows, it returns an empty string.
+ This means it's possible to easily know whether a query string is present
+ using the "found" matching method. This fetch is the complement of "path"
+ which stops before the question mark and of "query_string", which include the
+ question mark.
+
+ An optional parameter may be used to customize the return value. Following
+ options are supported:
+
+ - with_qm : Include the question mark at the beginning ot the query string,
+ if not empty.
+
req.body : binary
This returns the HTTP request's available body as a block of data. It is
recommended to use "option http-buffer-request" to be sure to wait, as much
as possible, for the request's body.
+req.body_len : integer
+ This returns the length of the HTTP request's available body in bytes. It may
+ be lower than the advertised length if the body is larger than the buffer. It
+ is recommended to use "option http-buffer-request" to be sure to wait, as
+ much as possible, for the request's body.
+
req.body_param([<name>[,i]]) : string
This fetch assumes that the body of the POST request is url-encoded. The user
can check if the "content-type" contains the value
ACL version of this fetch iterates over multiple parameters and will
iteratively report all parameters values if no name is given.
-req.body_len : integer
- This returns the length of the HTTP request's available body in bytes. It may
- be lower than the advertised length if the body is larger than the buffer. It
- is recommended to use "option http-buffer-request" to be sure to wait, as
- much as possible, for the request's body.
-
req.body_size : integer
This returns the advertised length of the HTTP request's body in bytes. It
will represent the advertised Content-Length header, or the size of the
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>]) : 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.
-
req.cook_names([<delim>]) : string
This builds a string made from the concatenation of all cookie names as they
appear in the request (Cookie header) when the rule is evaluated. The default
delimiter is the comma (',') but it may be overridden as an optional argument
<delim>. In this case, only the first character of <delim> is considered.
-cookie([<name>]) : string (deprecated)
+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, 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" did 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.
-
-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
- unambiguously apply to the request headers.
-
-request_date([<unit>]) : integer
- This is the exact date when the first byte of the HTTP request was received
- by HAProxy (log-format alias %tr). This is computed from accept_date +
- handshake time (%Th) + idle time (%Ti).
-
- Returns a value in number of seconds since epoch.
-
- <unit> is facultative, and can be set to "s" for seconds (default behavior),
- "ms" for milliseconds or "us" for microseconds.
- If unit is set, return value is an integer reflecting either seconds,
- milliseconds or microseconds since epoch.
- It is useful when a time resolution of less than a second is needed.
+ 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.
req.fhdr(<name>[,<occ>]) : string
This returns the full value of the last occurrence of header <name> in an
A typical use is with the X-Forwarded-For and X-Client-IP headers.
+req.hdr_names([<delim>]) : string
+ This builds a string made from the concatenation of all header names as they
+ appear in the request when the rule is evaluated. The default delimiter is
+ the comma (',') but it may be overridden as an optional argument <delim>. In
+ this case, only the first character of <delim> is considered.
+
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
This is reported in milliseconds and is equivalent to %Tq in
log-format. See section 8.4 "Timing events" for more details.
-res.timer.hdr : integer
- It's the time elapsed between the moment the TCP connection was established
- to the server and the moment the server sent its complete response headers.
- This is reported in milliseconds and is equivalent to %Tr in log-format. See
- section 8.4 "Timing events" for more details.
-
-
-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_bearer([<header>]) : string
- Returns the client-provided token found in the authorization data when the
- Bearer scheme is used (to send JSON Web Tokens for instance). No check is
- performed on the data sent by the client.
- If a specific <header> is supplied, it will parse this header instead of the
- Authorization one.
-
-http_auth_group(<userlist>) : string
- Returns a string corresponding to the user name found in the authentication
- data received from the client if both the user name and password are valid
- according to the specified userlist. The main purpose is to use it in ACLs
- where it is then checked whether the user belongs to any group within a list.
- This fetch function is not really useful outside of ACLs. Currently only http
- basic auth is supported.
-
- ACL derivatives :
- http_auth_group(<userlist>) : group ...
- Returns true when the user extracted from the request and whose password is
- valid according to the specified userlist belongs to at least one of the
- groups.
-
-http_auth_pass : string
- Returns the user's password found in the authentication data received from
- the client, as supplied in the Authorization header. Not checks are
- performed by this sample fetch. Only Basic authentication is supported.
-
-http_auth_type : string
- Returns the authentication method found in the authentication data received from
- the client, as supplied in the Authorization header. Not checks are
- performed by this sample fetch. Only Basic authentication is supported.
-
-http_auth_user : string
- Returns the user name found in the authentication data received from the
- client, as supplied in the Authorization header. Not checks are performed by
- this sample fetch. Only Basic authentication is supported.
-
-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 to help grouping
- requests in the logs.
-
-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.
-
- ACL derivatives :
- method : case insensitive method match
-
- Example :
- # only accept GET and HEAD requests
- acl valid_method method GET HEAD
- http-request deny if ! valid_method
-
-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 (e.g. "/login.php"), or directory parts using
- the derivative forms. See also the "url" and "base" fetch methods. Please
- note that any fragment reference in the URI ('#' after the path) is strictly
- forbidden by the HTTP standard and will be rejected. However, if the frontend
- receiving the request has "option accept-unsafe-violations-in-http-request",
- then this fragment part will be accepted and will also appear in the path.
-
- 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
-
-pathq : string
- This extracts the request's URL path with the query-string, which starts at
- the first slash. This sample fetch is pretty handy to always retrieve a
- relative URI, excluding the scheme and the authority part, if any. Indeed,
- while it is the common representation for an HTTP/1.1 request target, in
- HTTP/2, an absolute URI is often used. This sample fetch will return the same
- result in both cases. Please note that any fragment reference in the URI ('#'
- after the path) is strictly forbidden by the HTTP standard and will be
- rejected. However, if the frontend receiving the request has "option
- accept-unsafe-violations-in-http-request", then this fragment part will be
- accepted and will also appear in the path.
-
-query([<options>]) : string
- This extracts the request's query string, which starts after the first
- question mark. If no question mark is present, this fetch returns nothing. If
- a question mark is present but nothing follows, it returns an empty string.
- This means it's possible to easily know whether a query string is present
- using the "found" matching method. This fetch is the complement of "path"
- which stops before the question mark and of "query_string", which include the
- question mark.
-
- An optional parameter may be used to customize the return value. Following
- options are supported:
-
- - with_qm : Include the question mark at the beginning ot the query string,
- if not empty.
-
-req.hdr_names([<delim>]) : string
- This builds a string made from the concatenation of all header names as they
- appear in the request when the rule is evaluated. The default delimiter is
- the comma (',') but it may be overridden as an optional argument <delim>. In
- this case, only the first character of <delim> is considered.
-
req.ver : string
req_ver : string (deprecated)
Returns the version string from the HTTP request, for example "1.1". This can
ACL derivatives :
req.ver : exact string match
+request_date([<unit>]) : integer
+ This is the exact date when the first byte of the HTTP request was received
+ by HAProxy (log-format alias %tr). This is computed from accept_date +
+ handshake time (%Th) + idle time (%Ti).
+
+ Returns a value in number of seconds since epoch.
+
+ <unit> is facultative, and can be set to "s" for seconds (default behavior),
+ "ms" for milliseconds or "us" for microseconds.
+ If unit is set, return value is an integer reflecting either seconds,
+ milliseconds or microseconds since epoch.
+ It is useful when a time resolution of less than a second is needed.
+
res.body : binary
This returns the HTTP response's available body as a block of data. Unlike
the request side, there is no directive to wait for the response's body. This
It may be used in tcp-check based expect rules.
-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.
-
- It may be used in tcp-check based expect rules.
-
res.cook_names([<delim>]) : string
This builds a string made from the concatenation of all cookie names as they
appear in the response (Set-Cookie headers) when the rule is evaluated. The
It may be used in tcp-check based expect rules.
+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.
+
+ It may be used in tcp-check based expect rules.
+
res.fhdr([<name>[,<occ>]]) : string
This fetch works like the req.fhdr() fetch with the difference that it acts
on the headers within an HTTP response.
int: refer to the SPOE documentation for the encoding
str: <int:length><bytes>
+res.timer.hdr : integer
+ It's the time elapsed between the moment the TCP connection was established
+ to the server and the moment the server sent its complete response headers.
+ This is reported in milliseconds and is equivalent to %Tr in log-format. See
+ section 8.4 "Timing events" for more details.
+
res.ver : string
resp_ver : string (deprecated)
Returns the version string from the HTTP response, for example "1.1". This
url_reg : regex match
url_sub : substring match
+url32 : integer
+ This returns a 32-bit hash of the value obtained by concatenating the first
+ Host header and the whole URL including parameters (not only the path part of
+ the request, as in the "base32" fetch above). This is useful to track per-URL
+ activity. A shorter hash is stored, saving a lot of memory. The output type
+ is an unsigned integer.
+
+url32+src : binary
+ This returns the concatenation of the "url32" fetch and the "src" fetch. 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.
+
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
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.
-url32 : integer
- This returns a 32-bit hash of the value obtained by concatenating the first
- Host header and the whole URL including parameters (not only the path part of
- the request, as in the "base32" fetch above). This is useful to track per-URL
- activity. A shorter hash is stored, saving a lot of memory. The output type
- is an unsigned integer.
-
-url32+src : binary
- This returns the concatenation of the "url32" fetch and the "src" fetch. 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.
-
7.3.7. Fetching samples for developers
---------------------------------------
projects / thirdparty / haproxy.git / commitdiff
