Tag Archives: Converters

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 (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: 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.

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

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
str str map_str map_str_int map_str_ip
str beg map_beg map_beg_int map_end_ip
str sub map_sub map_sub_int map_sub_ip
str dir map_dir map_dir_int map_dir_ip
str dom map_dom map_dom_int map_dom_ip
str end map_end map_end_int map_end_ip
str reg map_reg map_reg_int map_reg_ip
int int map_int map_int_int map_int_ip
ip ip map_ip map_ip_int map_ip_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.

Example :

# this is a comment and is ignored    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.

Share Button