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 (eg: a netmask) which must be passed in parenthesis.
The currently available list of transformation keywords include :
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 (eg: an SSL ID can be copied in a header).
Converts a binary input sample to an 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 (eg: an SSL ID can be copied in a header).
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.
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).
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.
# 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
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.
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 avalaible sorted by input type, match type and output type.
|input type||match method||output type str||output type int||output type ip|
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.
# this is a comment and is ignored 22.214.171.124/23 United Kingdom \n | | | | '- trailing spaces ignored | | | '---------- value | | '-------------------- middle spaces ignored | '---------------------------- key '------------------------------------ leading spaces ignored
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.