mirror of
http://git.haproxy.org/git/haproxy.git/
synced 2024-12-29 16:12:10 +00:00
DOC: Full section dedicated to the converters
This commit is contained in:
Thierry FOURNIER
Willy Tarreau
parent
8317b283fb
commit
060762e67d
@ -69,11 +69,12 @@ Summary
|
||||
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 @@ Thus, the syntax of a standard sample fetch method is one of the following :
|
||||
- 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 @@ support some arguments (eg: a netmask) which must be passed in parenthesis.
|
||||
|
||||
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 :
|
||||
|
||||
7.3.1. Fetching samples from internal states
|
||||
# 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.2. Fetching samples from internal states
|
||||
--------------------------------------------
|
||||
|
||||
A first set of sample fetch methods applies to internal information which does
|
||||
@ -9692,7 +9699,7 @@ table_cnt([<table>]) : integer
|
||||
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 @@ srv_id : integer
|
||||
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 @@ ssl_fc_use_keysize : integer
|
||||
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 @@ wait_end : boolean
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user