DOC: Full section dedicated to the converters
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 347505c..3c34349 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -69,11 +69,12 @@
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.3.1. Converters
+7.3.2. Fetching samples from internal states
+7.3.3. Fetching samples at Layer 4
+7.3.4. Fetching samples at Layer 5
+7.3.5. Fetching samples from buffer contents (Layer 6)
+7.3.6. Fetching HTTP samples (Layer 7)
7.4. Pre-defined ACLs
8. Logging
@@ -9359,6 +9360,10 @@
- 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
@@ -9373,118 +9378,120 @@
The currently available list of transformation keywords include :
- 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.
+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.
- 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.
+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.
- hex 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).
+hex
+ 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).
- 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).
+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).
- http_date([<offset>])
- 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.
+http_date([<offset>])
+ 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.
- language(<value[;value[;value[;...]]]>[,<default>])
- 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. 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.
+language(<value>[,<default>])
+ 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 :
+ Example :
- # this configuration switches to the backend matching a
- # given language based on the request :
+ # 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
+ 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
- map(<map_file>[,<default_value>])
- 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. The following array contains contains the list of all
- the map* converters.
+map(<map_file>[,<default_value>])
+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.
+ 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.
- +----+----------+---------+-------------+------------+
- | `-_ out | | | |
- | input `-_ | str | int | ip |
- | / match `-_ | | | |
- +---------------+---------+-------------+------------+
- | str / str | map_str | map_str_int | map_str_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 following array contains the list of all map functions avalaible sorted by
+ input type, match type and output type.
- 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.
+ input type | match method | output type str | output type int | output type ip
+ -----------+--------------+-----------------+-----------------+---------------
+ str | str | map_str | map_str_int | map_str_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
+ -----------+--------------+-----------------+-----------------+---------------
- Example :
+ 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
- 2.22.246.0/23 United Kingdom \n
- <-><-----------><--><------------><---->
- | | | | `- trailing spaces ignored
- | | | `----------- value
- | | `--------------------- middle spaces ignored
- | `---------------------------- key
- `------------------------------------ leading spaces ignored
+ 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
+
-7.3.1. Fetching samples from internal states
+7.3.2. Fetching samples from internal states
--------------------------------------------
A first set of sample fetch methods applies to internal information which does
@@ -9692,7 +9699,7 @@
table_avl for other entry counting methods.
-7.3.2. Fetching samples at Layer 4
+7.3.3. Fetching samples at Layer 4
----------------------------------
The layer 4 usually describes just the transport layer which in haproxy is
@@ -10106,7 +10113,7 @@
debugging.
-7.3.3. Fetching samples at Layer 5
+7.3.4. Fetching samples at Layer 5
----------------------------------
The layer 5 usually describes just the session layer which in haproxy is
@@ -10396,7 +10403,7 @@
connection was made over an SSL/TLS transport layer.
-7.3.4. Fetching samples from buffer contents (Layer 6)
+7.3.5. Fetching samples from buffer contents (Layer 6)
------------------------------------------------------
Fetching samples from buffer contents is a bit different from the previous
@@ -10625,7 +10632,7 @@
tcp-request content reject
-7.3.5. Fetching HTTP samples (Layer 7)
+7.3.6. Fetching HTTP samples (Layer 7)
--------------------------------------
It is possible to fetch samples from HTTP contents, requests and responses.