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 (e.g. 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)

7.3.1. Converters

Sample fetch methods may be combined with transformations to be applied on top
of the fetched sample (also called "converters"). These combinations form what
is called "sample expressions" and the result is a "sample". Initially this
was only supported by "stick on" and "stick store-request" directives but this
has now be extended to all places where samples may be used (ACLs, log-format,
unique-id-format, add-header, ...).
 
These transformations are enumerated as a series of specific keywords after the
sample fetch method. These keywords may equally be appended immediately after
the fetch keyword's argument, delimited by a comma. These keywords can also
support some arguments (e.g. a netmask) which must be passed in parenthesis.
 
A certain category of converters are bitwise and arithmetic operators which
support performing basic operations on integers. Some bitwise operations are
supported (and, or, xor, cpl) and some arithmetic operations are supported
(add, sub, mul, div, mod, neg). Some comparators are provided (odd, even, not,
bool) which make it possible to report a match without having to write an ACL.
 
The currently available list of transformation keywords include :

51d.single([,*])

Returns values for the properties requested as a string, where values are
separated by the delimiter specified with "51degrees-property-separator".
The device is identified using the User-Agent header passed to the
converter. The function can be passed up to five property names, and if a
property name can't be found, the value "NoData" is returned.

Example :

# Here the header "X-51D-DeviceTypeMobileTablet" is added to the request,
# containing values for the three properties requested by using the
# User-Agent passed to the converter.
frontend http-in
  bind *:8081
  default_backend servers
  http-request set-header X-51D-DeviceTypeMobileTablet \
    %[req.fhdr(User-Agent),51d.single(DeviceType,IsMobile,IsTablet)]

add()

Adds <value> to the input value of type signed integer, and returns the
result as a signed integer. <value> can be a numeric value or a variable
name. The name of the variable starts with an indication about its scope. The
scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and response)
  "req"  : the variable is shared only during request processing
  "res"  : the variable is shared only during response processing
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

aes_gcm_dec(,,,)

Decrypts the raw byte input using the AES128-GCM, AES192-GCM or
AES256-GCM algorithm, depending on the <bits> parameter. All other parameters
need to be base64 encoded and the returned result is in raw byte format.
If the <aead_tag> validation fails, the converter doesn't return any data.
The <nonce>, <key> and <aead_tag> can either be strings or variables. This
converter requires at least OpenSSL 1.0.1.

Example:

http-response set-header X-Decrypted-Text %[var(txn.enc),\
  aes_gcm_dec(128,txn.nonce,Zm9vb2Zvb29mb29wZm9vbw==,txn.aead_tag)]

and()

Performs a bitwise "AND" between <value> and the input value of type signed
integer, and returns the result as an signed integer. <value> can be a
numeric value or a variable name. The name of the variable starts with an
indication about its scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and response)
  "req"  : the variable is shared only during request processing
  "res"  : the variable is shared only during response processing
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

b64dec

Converts (decodes) a base64 encoded input string to its binary
representation. It performs the inverse operation of base64().

base64

Converts a binary input sample to a base64 string. It is used to log or
transfer binary content in a way that can be reliably transferred (e.g.
an SSL ID can be copied in a header).

bool

Returns a boolean TRUE if the input value of type signed integer is
non-null, otherwise returns FALSE. Used in conjunction with and(), it can be
used to report true/false for bit testing on input values (e.g. verify the
presence of a flag).

bytes([,])

Extracts some bytes from an input binary sample. The result is a binary
sample starting at an offset (in bytes) of the original sample and
optionally truncated at the given length.

concat([],[],[])

Concatenates up to 3 fields after the current sample which is then turned to
a string. The first one, <start>, is a constant string, that will be appended
immediately after the existing sample. It may be omitted if not used. The
second one, <var>, is a variable name. The variable will be looked up, its
contents converted to a string, and it will be appended immediately after the
<first> part. If the variable is not found, nothing is appended. It may be
omitted as well. The third field, <end> is a constant string that will be
appended after the variable. It may also be omitted. Together, these elements
allow to concatenate variables with delimiters to an existing set of
variables. This can be used to build new variables made of a succession of
other variables, such as colon-delimited values. Note that due to the config
parser, it is not possible to use a comma nor a closing parenthesis as
delimiters.

Example:

tcp-request session set-var(sess.src) src
tcp-request session set-var(sess.dn)  ssl_c_s_dn
tcp-request session set-var(txn.sig) str(),concat(<ip=,sess.ip,>),concat(<dn=,sess.dn,>)
http-request set-header x-hap-sig %[var(txn.sig)]

cpl

Takes the input value of type signed integer, applies a ones-complement
(flips all bits) and returns the result as an signed integer.

crc32([])

Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32
hash function. Optionally, it is possible to apply a full avalanche hash
function to the output if the optional <avalanche> argument equals 1. This
converter uses the same functions as used by the various hash-based load
balancing algorithms, so it will provide exactly the same results. It is
provided for compatibility with other software which want a CRC32 to be
computed on some input keys, so it follows the most common implementation as
found in Ethernet, Gzip, PNG, etc... It is slower than the other algorithms
but may provide a better or at least less predictable distribution. It must
not be used for security purposes as a 32-bit hash is trivial to break. See
also "djb2", "sdbm", "wt6", "crc32c" and the "hash-type" directive.

crc32c([])

Hashes a binary input sample into an unsigned 32-bit quantity using the CRC32C
hash function. Optionally, it is possible to apply a full avalanche hash
function to the output if the optional <avalanche> argument equals 1. This
converter uses the same functions as described in RFC4960, Appendix B [8].
It is provided for compatibility with other software which want a CRC32C to be
computed on some input keys. It is slower than the other algorithms and it must
not be used for security purposes as a 32-bit hash is trivial to break. See
also "djb2", "sdbm", "wt6", "crc32" and the "hash-type" directive.

da-csv-conv([,*])

Asks the DeviceAtlas converter to identify the User Agent string passed on
input, and to emit a string made of the concatenation of the properties
enumerated in argument, delimited by the separator defined by the global
keyword "deviceatlas-property-separator", or by default the pipe character
('|'). There's a limit of 12 different properties imposed by the haproxy
configuration language.

Example:

frontend www
  bind *:8881
  default_backend servers
  http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]

debug

This converter is used as debug tool. It dumps on screen the content and the
type of the input sample. The sample is returned as is on its output. This
converter only exists when haproxy was built with debugging enabled.

div()

Divides the input value of type signed integer by <value>, and returns the
result as an signed integer. If <value> is null, the largest unsigned
integer is returned (typically 2^63-1). <value> can be a numeric value or a
variable name. The name of the variable starts with an indication about its
scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and response)
  "req"  : the variable is shared only during request processing
  "res"  : the variable is shared only during response processing
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

djb2([])

Hashes a binary input sample into an unsigned 32-bit quantity using the DJB2
hash function. Optionally, it is possible to apply a full avalanche hash
function to the output if the optional <avalanche> argument equals 1. This
converter uses the same functions as used by the various hash-based load
balancing algorithms, so it will provide exactly the same results. It is
mostly intended for debugging, but can be used as a stick-table entry to
collect rough statistics. It must not be used for security purposes as a
32-bit hash is trivial to break. See also "crc32", "sdbm", "wt6", "crc32c",
and the "hash-type" directive.

even

Returns a boolean TRUE if the input value of type signed integer is even
otherwise returns FALSE. It is functionally equivalent to "not,and(1),bool".

field(,[,])

Extracts the substring at the given index counting from the beginning
(positive index) or from the end (negative index) considering given delimiters
from an input string. Indexes start at 1 or -1 and delimiters are a string
formatted list of chars. Optionally you can specify <count> of fields to
extract (default: 1). Value of 0 indicates extraction of all remaining
fields.

Example :

str(f1_f2_f3__f5),field(5,_)    # f5
str(f1_f2_f3__f5),field(2,_,0)  # f2_f3__f5
str(f1_f2_f3__f5),field(2,_,2)  # f2_f3
str(f1_f2_f3__f5),field(-2,_,3) # f2_f3_
str(f1_f2_f3__f5),field(-3,_,0) # f1_f2_f3

hex

Converts a binary input sample to a hex string containing two hex digits per
input byte. It is used to log or transfer hex dumps of some binary input data
in a way that can be reliably transferred (e.g. an SSL ID can be copied in a
header).

hex2i

Converts a hex string containing two hex digits per input byte to an
integer. If the input value cannot be converted, then zero is returned.

http_date([])

Converts an integer supposed to contain a date since epoch to a string
representing this date in a format suitable for use in HTTP header fields. If
an offset value is specified, then it is a number of seconds that is added to
the date before the conversion is operated. This is particularly useful to
emit Date header fields, Expires values in responses when combined with a
positive offset, or Last-Modified values when the offset is negative.

in_table(

  Uses the string representation of the input sample to perform a look up in
  the specified table. If the key is not found in the table, a boolean false
  is returned. Otherwise a boolean true is returned. This can be used to verify
  the presence of a certain key in a table tracking some elements (e.g. whether
  or not a source IP address or an Authorization header was already seen).
 
ipmask(<mask4>, [<mask6>])
  Apply a mask to an IP 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 mask4 can be passed in
  dotted form (e.g. 255.255.255.0) or in CIDR form (e.g. 24). The mask6 can
  be passed in quadruplet form (e.g. ffff:ffff::) or in CIDR form (e.g. 64).
  If no mask6 is given IPv6 addresses will fail to convert for backwards
  compatibility reasons.

json([])

Escapes the input string and produces an ASCII output string ready to use as a
JSON string. The converter tries to decode the input string according to the
<input-code> parameter. It can be "ascii", "utf8", "utf8s", "utf8p" or
"utf8ps". The "ascii" decoder never fails. The "utf8" decoder detects 3 types
of errors:
 - bad UTF-8 sequence (lone continuation byte, bad number of continuation
   bytes, ...)
 - invalid range (the decoded value is within a UTF-8 prohibited range),
 - code overlong (the value is encoded with more bytes than necessary).
 
The UTF-8 JSON encoding can produce a "too long value" error when the UTF-8
character is greater than 0xffff because the JSON string escape specification
only authorizes 4 hex digits for the value encoding. The UTF-8 decoder exists
in 4 variants designated by a combination of two suffix letters : "p" for
"permissive" and "s" for "silently ignore". The behaviors of the decoders
are :
 - "ascii"  : never fails;
 - "utf8"   : fails on any detected errors;
 - "utf8s"  : never fails, but removes characters corresponding to errors;
 - "utf8p"  : accepts and fixes the overlong errors, but fails on any other
              error;
 - "utf8ps" : never fails, accepts and fixes the overlong errors, but removes
              characters corresponding to the other errors.
 
This converter is particularly useful for building properly escaped JSON for
logging to servers which consume JSON-formatted traffic logs.

Example:

capture request header Host len 15
capture request header user-agent len 150
log-format '{"ip":"%[src]","user-agent":"%[capture.req.hdr(1),json(utf8s)]"}'

Input request from client 127.0.0.1:
   GET / HTTP/1.0
   User-Agent: Very "Ugly" UA 1/2
 
Output log:
   {"ip":"127.0.0.1","user-agent":"Very \"Ugly\" UA 1\/2"}

language([,])

Returns the value with the highest q-factor from a list as extracted from the
"accept-language" header using "req.fhdr". Values with no q-factor have a
q-factor of 1. Values with a q-factor of 0 are dropped. Only values which
belong to the list of semi-colon delimited <values> will be considered. The
argument <value> syntax is "lang[;lang[;lang[;...]]]". If no value matches the
given list and a default value is provided, it is returned. Note that language
names may have a variant after a dash ('-'). If this variant is present in the
list, it will be matched, but if it is not, only the base language is checked.
The match is case-sensitive, and the output string is always one of those
provided in arguments. The ordering of arguments is meaningless, only the
ordering of the values in the request counts, as the first value among
multiple sharing the same q-factor is used.

Example :

# this configuration switches to the backend matching a
# given language based on the request :
acl es req.fhdr(accept-language),language(es;fr;en) -m str es
acl fr req.fhdr(accept-language),language(es;fr;en) -m str fr
acl en req.fhdr(accept-language),language(es;fr;en) -m str en
use_backend spanish if es
use_backend french  if fr
use_backend english if en
default_backend choose_your_language

length

Get the length of the string. 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 integer.

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.

ltime([,])

Converts an integer supposed to contain a date since epoch to a string
representing this date in local time using a format defined by the <format>
string using strftime(3). The purpose is to allow any date format to be used
in logs. An optional <offset> in seconds may be applied to the input date
(positive or negative). See the strftime() man page for the format supported
by your operating system. See also the utime converter.

Example :

# Emit two colons, one with the local time and another with ip:port
# e.g.  20140710162350 127.0.0.1:57325
log-format %[date,ltime(%Y%m%d%H%M%S)]\ %ci:%cp

map([,])

map_<match_type>(<map_file>[,<default_value>])
map_<match_type>_<output_type>(<map_file>[,<default_value>])
  Search the input value from <map_file> using the <match_type> matching method,
  and return the associated value converted to the type <output_type>. If the
  input value cannot be found in the <map_file>, the converter returns the
  <default_value>. If the <default_value> is not set, the converter fails and
  acts as if no input value could be fetched. If the <match_type> is not set, it
  defaults to "str". Likewise, if the <output_type> is not set, it defaults to
  "str". For convenience, the "map" keyword is an alias for "map_str" and maps a
  string to another string.
 
  It is important to avoid overlapping between the keys : IP addresses and
  strings are stored in trees, so the first of the finest match will be used.
  Other keys are stored in lists, so the first matching occurrence will be used.
 
  The following array contains the list of all map functions available sorted by
  input type, match type and output type.

The special map called "map_regm" expect matching zone in the regular
expression and modify the output replacing back reference (like "\1") by
the corresponding match text.
 
The file contains one key + value per line. Lines which start with '#' are
ignored, just like empty lines. Leading tabs and spaces are stripped. The key
is then the first "word" (series of non-space/tabs characters), and the value
is what follows this series of space/tab till the end of the line excluding
trailing spaces/tabs.

Example :

# this is a comment and is ignored
   2.22.246.0/23    United Kingdom      \n
<-><-----------><--><------------><---->
 |       |       |         |        `- trailing spaces ignored
 |       |       |         `---------- value
 |       |       `-------------------- middle spaces ignored
 |       `---------------------------- key
 `------------------------------------ leading spaces ignored

mod()

Divides the input value of type signed integer by <value>, and returns the
remainder as an signed integer. If <value> is null, then zero is returned.
<value> can be a numeric value or a variable name. The name of the variable
starts with an indication about its scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and response)
  "req"  : the variable is shared only during request processing
  "res"  : the variable is shared only during response processing
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

mul()

Multiplies the input value of type signed integer by <value>, and returns
the product as an signed integer. In case of overflow, the largest possible
value for the sign is returned so that the operation doesn't wrap around.
<value> can be a numeric value or a variable name. The name of the variable
starts with an indication about its scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and response)
  "req"  : the variable is shared only during request processing
  "res"  : the variable is shared only during response processing
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

nbsrv

Takes an input value of type string, interprets it as a backend name and
returns the number of usable servers in that backend. Can be used in places
where we want to look up a backend from a dynamic name, like a result of a
map lookup.

neg

Takes the input value of type signed integer, computes the opposite value,
and returns the remainder as an signed integer. 0 is identity. This operator
is provided for reversed subtracts : in order to subtract the input from a
constant, simply perform a "neg,add(value)".

not

Returns a boolean FALSE if the input value of type signed integer is
non-null, otherwise returns TRUE. Used in conjunction with and(), it can be
used to report true/false for bit testing on input values (e.g. verify the
absence of a flag).

odd

Returns a boolean TRUE if the input value of type signed integer is odd
otherwise returns FALSE. It is functionally equivalent to "and(1),bool".

or()

Performs a bitwise "OR" between <value> and the input value of type signed
integer, and returns the result as an signed integer. <value> can be a
numeric value or a variable name. The name of the variable starts with an
indication about its scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and response)
  "req"  : the variable is shared only during request processing
  "res"  : the variable is shared only during response processing
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

protobuf(,[])

This extracts the protocol buffers message field in raw mode of an input binary
sample representation of a protocol buffer message with <field_number> as field
number (dotted notation) if <field_type> is not present, or as an integer sample
if this field is present (see also "ungrpc" below).
The list of the authorized types is the following one: "int32", "int64", "uint32",
"uint64", "sint32", "sint64", "bool
This keyword is available in sections :
Converters
Fetching samples from internal states
", "enum" for the "varint" wire type 0
"fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
"float" for the wire type 5. Note that "string" is considered as a length-delimited
type, so it does not require any <field_type> argument to be extracted.
More information may be found here about the protocol buffers message field types:
https://developers.google.com/protocol-buffers/docs/encoding

regsub(,[,])

Applies a regex-based substitution to the input string. It does the same
operation as the well-known "sed" utility with "s/<regex>/<subst>/". By
default it will replace in the input string the first occurrence of the
largest part matching the regular expression <regex> with the substitution
string <subst>. It is possible to replace all occurrences instead by adding
the flag "g" in the third argument <flags>. It is also possible to make the
regex case insensitive by adding the flag "i" in <flags>. Since <flags> is a
string, it is made up from the concatenation of all desired flags. Thus if
both "i" and "g" are desired, using "gi" or "ig" will have the same effect.
It is important to note that due to the current limitations of the
configuration parser, some characters such as closing parenthesis, closing
square brackets or comma are not possible to use in the arguments. The first
use of this converter is to replace certain characters or sequence of
characters with other ones.

Example :

# de-duplicate "/" in header "x-path".
# input:  x-path: /////a///b/c/xzxyz/
# output: x-path: /a/b/c/xzxyz/
http-request set-header x-path %[hdr(x-path),regsub(/+,/,g)]

capture-req()

Capture the string entry in the request slot <id> and returns the entry as
is. If the slot doesn't exist, the capture fails silently.

See also: “declare capture“, “http-request capture“, “http-response capture“, “capture.req.hdr“ and “capture.res.hdr“ (sample fetches).

capture-res()

Capture the string entry in the response slot <id> and returns the entry as
is. If the slot doesn't exist, the capture fails silently.

See also: “declare capture“, “http-request capture“, “http-response capture“, “capture.req.hdr“ and “capture.res.hdr“ (sample fetches).

sdbm([])

  Hashes a binary input sample into an unsigned 32-bit quantity using the SDBM
  hash function. Optionally, it is possible to apply a full avalanche hash
  function to the output if the optional <avalanche> argument equals 1. This
  converter uses the same functions as used by the various hash-based load
  balancing algorithms, so it will provide exactly the same results. It is
  mostly intended for debugging, but can be used as a stick-table entry to
  collect rough statistics. It must not be used for security purposes as a
  32-bit hash is trivial to break. See also "crc32", "djb2", "wt6", "crc32c",
  and the "hash-type" directive.
 
set-var(<var name>)
  Sets a variable with the input content and returns the content on the output
  as-is. The variable keeps the value and the associated input type. The name of
  the variable starts with an indication about its scope. The scopes allowed are:
    "proc" : the variable is shared with the whole process
    "sess" : the variable is shared with the whole session
    "txn"  : the variable is shared with the transaction (request and
             response),
    "req"  : the variable is shared only during request processing,
    "res"  : the variable is shared only during response processing.
  This prefix is followed by a name. The separator is a '.'. The name may only
  contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

sha1

Converts a binary input sample to a SHA1 digest. The result is a binary
sample with length of 20 bytes.

strcmp()

Compares the contents of <var> with the input value of type string. Returns
the result as a signed integer compatible with strcmp(3): 0 if both strings
are identical. A value less than 0 if the left string is lexicographically
smaller than the right string or if the left string is shorter. A value greater
than 0 otherwise (right string greater than left string or the right string is
shorter).

Example :

http-request set-var(txn.host) hdr(host)
# Check whether the client is attempting domain fronting.
acl ssl_sni_http_host_match ssl_fc_sni,strcmp(txn.host) eq 0

sub()

Subtracts <value> from the input value of type signed integer, and returns
the result as an signed integer. Note: in order to subtract the input from
a constant, simply perform a "neg,add(value)". <value> can be a numeric value
or a variable name. The name of the variable starts with an indication about
its scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and
           response),
  "req"  : the variable is shared only during request processing,
  "res"  : the variable is shared only during response processing.
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

table_bytes_in_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the average client-to-server
bytes rate associated with the input sample in the designated table, measured
in amount of bytes over the period configured in the table. See also the
sc_bytes_in_rate sample fetch keyword.

table_bytes_out_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the average server-to-client
bytes rate associated with the input sample in the designated table, measured
in amount of bytes over the period configured in the table. See also the
sc_bytes_out_rate sample fetch keyword.

table_conn_cnt(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the cumulative number of incoming
connections associated with the input sample in the designated table. See
also the sc_conn_cnt sample fetch keyword.

table_conn_cur(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the current amount of concurrent
tracked connections associated with the input sample in the designated table.
See also the sc_conn_cur sample fetch keyword.

table_conn_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the average incoming connection
rate associated with the input sample in the designated table. See also the
sc_conn_rate sample fetch keyword.

table_gpt0(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, boolean value zero
is returned. Otherwise the converter returns the current value of the first
general purpose tag associated with the input sample in the designated table.
See also the sc_get_gpt0 sample fetch keyword.

table_gpc0(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the current value of the first
general purpose counter associated with the input sample in the designated
table. See also the sc_get_gpc0 sample fetch keyword.

table_gpc0_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the frequency which the gpc0
counter was incremented over the configured period in the table, associated
with the input sample in the designated table. See also the sc_get_gpc0_rate
sample fetch keyword.

table_gpc1(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the current value of the second
general purpose counter associated with the input sample in the designated
table. See also the sc_get_gpc1 sample fetch keyword.

table_gpc1_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the frequency which the gpc1
counter was incremented over the configured period in the table, associated
with the input sample in the designated table. See also the sc_get_gpc1_rate
sample fetch keyword.

table_http_err_cnt(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the cumulative number of HTTP
errors associated with the input sample in the designated table. See also the
sc_http_err_cnt sample fetch keyword.

table_http_err_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the average rate of HTTP errors associated with the
input sample in the designated table, measured in amount of errors over the
period configured in the table. See also the sc_http_err_rate sample fetch
keyword.

table_http_req_cnt(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the cumulative number of HTTP
requests associated with the input sample in the designated table. See also
the sc_http_req_cnt sample fetch keyword.

table_http_req_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the average rate of HTTP requests associated with the
input sample in the designated table, measured in amount of requests over the
period configured in the table. See also the sc_http_req_rate sample fetch
keyword.

table_kbytes_in(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the cumulative number of client-
to-server data associated with the input sample in the designated table,
measured in kilobytes. The test is currently performed on 32-bit integers,
which limits values to 4 terabytes. See also the sc_kbytes_in sample fetch
keyword.

table_kbytes_out(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the cumulative number of server-
to-client data associated with the input sample in the designated table,
measured in kilobytes. The test is currently performed on 32-bit integers,
which limits values to 4 terabytes. See also the sc_kbytes_out sample fetch
keyword.

table_server_id(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the server ID associated with
the input sample in the designated table. A server ID is associated to a
sample by a "stick
This keyword is available in sections :
Alphabetically sorted keywords reference
Server and default-server options
" rule when a connection to a server succeeds. A server ID
zero means that no server is associated with this key.

table_sess_cnt(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the cumulative number of incoming
sessions associated with the input sample in the designated table. Note that
a session here refers to an incoming connection being accepted by the
"tcp-request connection" rulesets. See also the sc_sess_cnt sample fetch
keyword.

table_sess_rate(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the average incoming session
rate associated with the input sample in the designated table. Note that a
session here refers to an incoming connection being accepted by the
"tcp-request connection" rulesets. See also the sc_sess_rate sample fetch
keyword.

table_trackers(

Uses the string representation of the input sample to perform a look up in
the specified table. If the key is not found in the table, integer value zero
is returned. Otherwise the converter returns the current amount of concurrent
connections tracking the same key as the input sample in the designated
table. It differs from table_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. See also the
sc_trackers sample fetch keyword.

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.

url_dec

Takes an url-encoded string provided as input and returns the decoded
version as output. The input and the output are of type string.

ungrpc(,[])

This extracts the protocol buffers message field in raw mode of an input binary
sample representation of a gRPC message with <field_number> as field number
(dotted notation) if <field_type> is not present, or as an integer sample if this
field is present.
The list of the authorized types is the following one: "int32", "int64", "uint32",
"uint64", "sint32", "sint64", "bool
This keyword is available in sections :
Converters
Fetching samples from internal states
", "enum" for the "varint" wire type 0
"fixed64", "sfixed64", "double" for the 64bit wire type 1, "fixed32", "sfixed32",
"float" for the wire type 5. Note that "string" is considered as a length-delimited
type, so it does not require any <field_type> argument to be extracted.
More information may be found here about the protocol buffers message field types:
https://developers.google.com/protocol-buffers/docs/encoding

Example:

// with such a protocol buffer .proto file content adapted from
// https://github.com/grpc/grpc/blob/master/examples/protos/route_guide.proto
message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}
message PPoint {
  Point point = 59;
}
message Rectangle {
  // One corner of the rectangle.
  PPoint lo = 48;
  // The other corner of the rectangle.
  PPoint hi = 49;
}
let's say a body request is made of a "Rectangle" object value (two PPoint
protocol buffers messages), the four protocol buffers fields could be
extracted with these "ungrpc" directives:
req.body,ungrpc(48.59.1,int32) # "latitude" of "lo" first PPoint
req.body,ungrpc(48.59.2,int32) # "longitude" of "lo" first PPoint
req.body,ungrpc(49.59.1,int32) # "latitude" of "hi" second PPoint
req.body,ungrpc(49.59.2,int32) # "longitude" of "hi" second PPoint
We could also extract the intermediary 48.59 field as a binary sample as follows:
req.body,ungrpc(48.59)
As a gRPC message is always made of a gRPC header followed by protocol buffers
messages, in the previous example the "latitude" of "lo" first PPoint
could be extracted with these equivalent directives:
req.body,ungrpc(48.59),protobuf(1,int32)
req.body,ungrpc(48),protobuf(59.1,int32)
req.body,ungrpc(48),protobuf(59),protobuf(1,int32)
Note that the first convert must be "ungrpc", the remaining ones must be
"protobuf" and only the last one may have or not a second argument to
interpret the previous binary sample.

unset-var(<var name>)
  Unsets a variable if the input content is defined. The name of the variable
  starts with an indication about its scope. The scopes allowed are:
    "proc" : the variable is shared with the whole process
    "sess" : the variable is shared with the whole session
    "txn"  : the variable is shared with the transaction (request and
             response),
    "req"  : the variable is shared only during request processing,
    "res"  : the variable is shared only during response processing.
  This prefix is followed by a name. The separator is a '.'. The name may only
  contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

utime([,])

Converts an integer supposed to contain a date since epoch to a string
representing this date in UTC time using a format defined by the <format>
string using strftime(3). The purpose is to allow any date format to be used
in logs. An optional <offset> in seconds may be applied to the input date
(positive or negative). See the strftime() man page for the format supported
by your operating system. See also the ltime converter.

Example :

# Emit two colons, one with the UTC time and another with ip:port
# e.g.  20140710162350 127.0.0.1:57325
log-format %[date,utime(%Y%m%d%H%M%S)]\ %ci:%cp

word(,[,])

Extracts the nth word counting from the beginning (positive index) or from
the end (negative index) considering given delimiters from an input string.
Indexes start at 1 or -1 and delimiters are a string formatted list of chars.
Delimiters at the beginning or end of the input string are ignored.
Optionally you can specify <count> of words to extract (default: 1).
Value of 0 indicates extraction of all remaining words.

Example :

str(f1_f2_f3__f5),word(4,_)    # f5
str(f1_f2_f3__f5),word(2,_,0)  # f2_f3__f5
str(f1_f2_f3__f5),word(3,_,2)  # f3__f5
str(f1_f2_f3__f5),word(-2,_,3) # f1_f2_f3
str(f1_f2_f3__f5),word(-3,_,0) # f1_f2
str(/f1/f2/f3/f4),word(1,/)    # f1

wt6([])

Hashes a binary input sample into an unsigned 32-bit quantity using the WT6
hash function. Optionally, it is possible to apply a full avalanche hash
function to the output if the optional <avalanche> argument equals 1. This
converter uses the same functions as used by the various hash-based load
balancing algorithms, so it will provide exactly the same results. It is
mostly intended for debugging, but can be used as a stick-table entry to
collect rough statistics. It must not be used for security purposes as a
32-bit hash is trivial to break. See also "crc32", "djb2", "sdbm", "crc32c",
and the "hash-type" directive.

xor()

Performs a bitwise "XOR" (exclusive OR) between <value> and the input value
of type signed integer, and returns the result as an signed integer.
<value> can be a numeric value or a variable name. The name of the variable
starts with an indication about its scope. The scopes allowed are:
  "proc" : the variable is shared with the whole process
  "sess" : the variable is shared with the whole session
  "txn"  : the variable is shared with the transaction (request and
           response),
  "req"  : the variable is shared only during request processing,
  "res"  : the variable is shared only during response processing.
This prefix is followed by a name. The separator is a '.'. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.

xxh32([])

Hashes a binary input sample into an unsigned 32-bit quantity using the 32-bit
variant of the XXHash hash function. This hash supports a seed which defaults
to zero but a different value maybe passed as the <seed> argument. This hash
is known to be very good and very fast so it can be used to hash URLs and/or
URL parameters for use as stick-table keys to collect statistics with a low
collision rate, though care must be taken as the algorithm is not considered
as cryptographically secure.

xxh64([])

Hashes a binary input sample into a signed 64-bit quantity using the 64-bit
variant of the XXHash hash function. This hash supports a seed which defaults
to zero but a different value maybe passed as the <seed> argument. This hash
is known to be very good and very fast so it can be used to hash URLs and/or
URL parameters for use as stick-table keys to collect statistics with a low
collision rate, though care must be taken as the algorithm is not considered
as cryptographically secure.

7.3.2. 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([]) : integer

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, 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

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", "be_conn_free", and "be_sess_rate" criteria.

be_conn_free([]) : integer

Returns an integer value corresponding to the number of available connections
across available servers in the backend. Queue slots are not included. Backup
servers are also not included, unless all other servers are down. 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 "be_conn", "connslots", and "srv_conn_free"
criteria.
 
OTHER CAVEATS AND NOTES: if any of the server maxconn, or maxqueue is 0
(meaning unlimited), then this fetch clearly does not make sense, in which
case the value returned will be -1.