DOC: Improve documentation of the various hdr() fetches
GitHub issue #796 notes that many administrators miss the fact that the `hdr()`
fetch (without the `f`) splits the header value at commas. This is only
mentioned at the end of a long paragraph.
This patch attempts to improve the documentation by:
- Explaning the "comma issue" as early as possible.
- Adding newlines to split the explanation into distinct sections.
- Reducing duplication by making the `res` siblings refer to their `req`
counterparts.
This patch may be backported as long as it applies cleanly. During the
refactoring I needed to adjust several explanations for consistency and not all
of them might be available in older branches.
(cherry picked from commit 27c70ae23c1f5b39c9757387559072a096c8aa8c)
Signed-off-by: Christopher Faulet <cfaulet@haproxy.com>
diff --git a/doc/configuration.txt b/doc/configuration.txt
index a2c72db..44adab0 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -18253,33 +18253,44 @@
unambiguously apply to the request headers.
req.fhdr(<name>[,<occ>]) : string
- This extracts the last occurrence of header <name> in an HTTP request. When
- used from an ACL, all occurrences are iterated over until a match is found.
+ This returns the full value of the last occurrence of header <name> in an
+ HTTP request. It differs from req.hdr() in that any commas present in the
+ value are returned and are not used as delimiters. This is sometimes useful
+ with headers such as User-Agent.
+
+ When used from an ACL, all occurrences are iterated over until a match is
+ found.
+
Optionally, a specific occurrence might be specified as a position number.
Positive values indicate a position from the first occurrence, with 1 being
the first one. Negative values indicate positions relative to the last one,
- with -1 being the last one. It differs from req.hdr() in that any commas
- present in the value are returned and are not used as delimiters. This is
- sometimes useful with headers such as User-Agent.
+ with -1 being the last one.
req.fhdr_cnt([<name>]) : integer
Returns an integer value representing the number of occurrences of request
header field name <name>, or the total number of header fields if <name> is
- not specified. Contrary to its req.hdr_cnt() cousin, this function returns
- the number of full line headers and does not stop on commas.
+ not specified. Like req.fhdr() it differs from res.hdr_cnt() by not splitting
+ headers at commas.
req.hdr([<name>[,<occ>]]) : string
- This extracts the last occurrence of header <name> in an HTTP request. When
- used from an ACL, all occurrences are iterated over until a match is found.
+ This returns the last comma-separated value of the header <name> in an HTTP
+ request. The fetch considers any comma as a delimiter for distinct values.
+ This is useful if you need to process headers that are defined to be a list
+ of values, such as Accept, or X-Forwarded-For. If full-line headers are
+ desired instead, use req.fhdr(). Please carefully check RFC 7231 to know how
+ certain headers are supposed to be parsed. Also, some of them are case
+ insensitive (e.g. Connection).
+
+ When used from an ACL, all occurrences are iterated over until a match is
+ found.
+
Optionally, a specific occurrence might be specified as a position number.
Positive values indicate a position from the first occurrence, with 1 being
the first one. Negative values indicate positions relative to the last one,
- with -1 being the last one. A typical use is with the X-Forwarded-For header
- once converted to IP, associated with an IP stick-table. The function
- considers any comma as a delimiter for distinct values. If full-line headers
- are desired instead, use req.fhdr(). Please carefully check RFC7231 to know
- how certain headers are supposed to be parsed. Also, some of them are case
- insensitive (e.g. Connection).
+ with -1 being the last one.
+
+ A typical use is with the X-Forwarded-For header once converted to IP,
+ associated with an IP stick-table.
ACL derivatives :
hdr([<name>[,<occ>]]) : exact string match
@@ -18295,34 +18306,36 @@
hdr_cnt([<header>]) : integer (deprecated)
Returns an integer value representing the number of occurrences of request
header field name <name>, or the total number of header field values if
- <name> is not specified. It is important to remember that one header line may
- count as several headers if it has several values. The function considers any
- comma as a delimiter for distinct values. If full-line headers are desired
- instead, req.fhdr_cnt() should be used instead. With ACLs, it can be used to
- detect presence, absence or abuse of a specific header, as well as to block
- request smuggling attacks by rejecting requests which contain more than one
- of certain headers. See "req.hdr" for more information on header matching.
+ <name> is not specified. Like req.hdr() it counts each comma separated
+ part of the header's value. If counting of full-line headers is desired,
+ then req.fhdr_cnt() should be used instead.
+
+ With ACLs, it can be used to detect presence, absence or abuse of a specific
+ header, as well as to block request smuggling attacks by rejecting requests
+ which contain more than one of certain headers.
+
+ Refer to req.hdr() for more information on header matching.
req.hdr_ip([<name>[,<occ>]]) : ip
hdr_ip([<name>[,<occ>]]) : ip (deprecated)
This extracts the last occurrence of header <name> in an HTTP request,
converts it to an IPv4 or IPv6 address and returns this address. When used
with ACLs, all occurrences are checked, and if <name> is omitted, every value
- of every header is checked. Optionally, a specific occurrence might be
- specified as a position number. Positive values indicate a position from the
- first occurrence, with 1 being the first one. Negative values indicate
- positions relative to the last one, with -1 being the last one. A typical use
- is with the X-Forwarded-For and X-Client-IP headers.
+ of every header is checked.
+
+ The <occ> parameter is processed as with req.hdr().
+
+ A typical use is with the X-Forwarded-For and X-Client-IP headers.
req.hdr_val([<name>[,<occ>]]) : integer
hdr_val([<name>[,<occ>]]) : integer (deprecated)
This extracts the last occurrence of header <name> in an HTTP request, and
converts it to an integer value. When used with ACLs, all occurrences are
checked, and if <name> is omitted, every value of every header is checked.
- Optionally, a specific occurrence might be specified as a position number.
- Positive values indicate a position from the first occurrence, with 1 being
- the first one. Negative values indicate positions relative to the last one,
- with -1 being the last one. A typical use is with the X-Forwarded-For header.
+
+ The <occ> parameter is processed as with req.hdr().
+
+ A typical use is with the X-Forwarded-For header.
req.hdrs : string
Returns the current request headers as string including the last empty line
@@ -18454,22 +18467,25 @@
res.body : binary
This returns the HTTP response's available body as a block of data. Unlike
the request side, there is no directive to wait for the response's body. This
- sample fetch is really useful (and usable) in the health-check context. It
- may be used in tcp-check based expect rules.
+ sample fetch is really useful (and usable) in the health-check context.
+
+ It may be used in tcp-check based expect rules.
res.body_len : integer
This returns the length of the HTTP response available body in bytes. Unlike
the request side, there is no directive to wait for the response's body. This
- sample fetch is really useful (and usable) in the health-check context. It
- may be used in tcp-check based expect rules.
+ sample fetch is really useful (and usable) in the health-check context.
+
+ It may be used in tcp-check based expect rules.
res.body_size : integer
This returns the advertised length of the HTTP response body in bytes. It
will represent the advertised Content-Length header, or the size of the
available data in case of chunked encoding. Unlike the request side, there is
no directive to wait for the response body. This sample fetch is really
- useful (and usable) in the health-check context. It may be used in tcp-check
- based expect rules.
+ useful (and usable) in the health-check context.
+
+ It may be used in tcp-check based expect rules.
res.cache_hit : boolean
Returns the boolean "true" value if the response has been built out of an
@@ -18494,8 +18510,9 @@
scook([<name>]) : string (deprecated)
This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
header line from the response, and returns its value as string. If no name is
- specified, the first cookie value is returned. It may be used in tcp-check
- based expect rules.
+ specified, the first cookie value is returned.
+
+ It may be used in tcp-check based expect rules.
ACL derivatives :
scook([<name>] : exact string match
@@ -18504,46 +18521,47 @@
scook_cnt([<name>]) : integer (deprecated)
Returns an integer value representing the number of occurrences of the cookie
<name> in the response, or all cookies if <name> is not specified. This is
- mostly useful when combined with ACLs to detect suspicious responses. It may
- be used in tcp-check based expect rules.
+ mostly useful when combined with ACLs to detect suspicious responses.
+
+ It may be used in tcp-check based expect rules.
res.cook_val([<name>]) : integer
scook_val([<name>]) : integer (deprecated)
This extracts the last occurrence of the cookie name <name> on a "Set-Cookie"
header line from the response, and converts its value to an integer which is
- returned. If no name is specified, the first cookie value is returned. It may
- be used in tcp-check based expect rules.
+ returned. If no name is specified, the first cookie value is returned.
+
+ It may be used in tcp-check based expect rules.
res.fhdr([<name>[,<occ>]]) : string
- This extracts the last occurrence of header <name> in an HTTP response, or of
- the last header if no <name> is specified. Optionally, a specific occurrence
- might be specified as a position number. Positive values indicate a position
- from the first occurrence, with 1 being the first one. Negative values
- indicate positions relative to the last one, with -1 being the last one. It
- differs from res.hdr() in that any commas present in the value are returned
- and are not used as delimiters. If this is not desired, the res.hdr() fetch
- should be used instead. This is sometimes useful with headers such as Date or
- Expires. It may be used in tcp-check based expect rules.
+ This fetch works like the req.fhdr() fetch with the difference that it acts
+ on the headers within an HTTP response.
+
+ Like req.fhdr() the res.fhdr() fetch returns full values. If the header is
+ defined to be a list you should use res.hdr().
+
+ This fetch is sometimes useful with headers such as Date or Expires.
+
+ It may be used in tcp-check based expect rules.
res.fhdr_cnt([<name>]) : integer
- Returns an integer value representing the number of occurrences of response
- header field name <name>, or the total number of header fields if <name> is
- not specified. Contrary to its res.hdr_cnt() cousin, this function returns
- the number of full line headers and does not stop on commas. If this is not
- desired, the res.hdr_cnt() fetch should be used instead. It may be used in
- tcp-check based expect rules.
+ This fetch works like the req.fhdr_cnt() fetch with the difference that it
+ acts on the headers within an HTTP response.
+
+ Like req.fhdr_cnt() the res.fhdr_cnt() fetch acts on full values. If the
+ header is defined to be a list you should use res.hdr_cnt().
+
+ It may be used in tcp-check based expect rules.
res.hdr([<name>[,<occ>]]) : string
shdr([<name>[,<occ>]]) : string (deprecated)
- This extracts the last occurrence of header <name> in an HTTP response, or of
- the last header if no <name> is specified. Optionally, a specific occurrence
- might be specified as a position number. Positive values indicate a position
- from the first occurrence, with 1 being the first one. Negative values
- indicate positions relative to the last one, with -1 being the last one. This
- can be useful to learn some data into a stick-table. The function considers
- any comma as a delimiter for distinct values. If this is not desired, the
- res.fhdr() fetch should be used instead. It may be used in tcp-check based
- expect rules.
+ This fetch works like the req.hdr() fetch with the difference that it acts
+ on the headers within an HTTP response.
+
+ Like req.hdr() the res.hdr() fetch considers the comma to be a delimeter. If
+ this is not desired res.fhdr() should be used.
+
+ It may be used in tcp-check based expect rules.
ACL derivatives :
shdr([<name>[,<occ>]]) : exact string match
@@ -18557,45 +18575,47 @@
res.hdr_cnt([<name>]) : integer
shdr_cnt([<name>]) : integer (deprecated)
- Returns an integer value representing the number of occurrences of response
- header field name <name>, or the total number of header fields if <name> is
- not specified. The function considers any comma as a delimiter for distinct
- values. If this is not desired, the res.fhdr_cnt() fetch should be used
- instead. It may be used in tcp-check based expect rules.
+ This fetch works like the req.hdr_cnt() fetch with the difference that it
+ acts on the headers within an HTTP response.
+
+ Like req.hdr_cnt() the res.hdr_cnt() fetch considers the comma to be a
+ delimeter. If this is not desired res.fhdr_cnt() should be used.
+
+ It may be used in tcp-check based expect rules.
res.hdr_ip([<name>[,<occ>]]) : ip
shdr_ip([<name>[,<occ>]]) : ip (deprecated)
- This extracts the last occurrence of header <name> in an HTTP response,
- convert it to an IPv4 or IPv6 address and returns this address. Optionally, a
- specific occurrence might be specified as a position number. Positive values
- indicate a position from the first occurrence, with 1 being the first one.
- Negative values indicate positions relative to the last one, with -1 being
- the last one. This can be useful to learn some data into a stick table. It
- may be used in tcp-check based expect rules.
+ This fetch works like the req.hdr_ip() fetch with the difference that it
+ acts on the headers within an HTTP response.
+
+ This can be useful to learn some data into a stick table.
+
+ It may be used in tcp-check based expect rules.
res.hdr_names([<delim>]) : string
This builds a string made from the concatenation of all header names as they
appear in the response when the rule is evaluated. The default delimiter is
the comma (',') but it may be overridden as an optional argument <delim>. In
- this case, only the first character of <delim> is considered. It may be used
- in tcp-check based expect rules.
+ this case, only the first character of <delim> is considered.
+
+ It may be used in tcp-check based expect rules.
res.hdr_val([<name>[,<occ>]]) : integer
shdr_val([<name>[,<occ>]]) : integer (deprecated)
- This extracts the last occurrence of header <name> in an HTTP response, and
- converts it to an integer value. Optionally, a specific occurrence might be
- specified as a position number. Positive values indicate a position from the
- first occurrence, with 1 being the first one. Negative values indicate
- positions relative to the last one, with -1 being the last one. This can be
- useful to learn some data into a stick table. It may be used in tcp-check
- based expect rules.
+ This fetch works like the req.hdr_val() fetch with the difference that it
+ acts on the headers within an HTTP response.
+
+ This can be useful to learn some data into a stick table.
+
+ It may be used in tcp-check based expect rules.
res.hdrs : string
Returns the current response headers as string including the last empty line
separating headers from the request body. The last empty line can be used to
detect a truncated header block. This sample fetch is useful for some SPOE
- headers analyzers and for advanced logging. It may also be used in tcp-check
- based expect rules.
+ headers analyzers and for advanced logging.
+
+ It may also be used in tcp-check based expect rules.
res.hdrs_bin : binary
Returns the current response headers contained in preparsed binary form. This
@@ -18614,8 +18634,9 @@
res.ver : string
resp_ver : string (deprecated)
Returns the version string from the HTTP response, for example "1.1". This
- can be useful for logs, but is mostly there for ACL. It may be used in
- tcp-check based expect rules.
+ can be useful for logs, but is mostly there for ACL.
+
+ It may be used in tcp-check based expect rules.
ACL derivatives :
resp_ver : exact string match
@@ -18632,8 +18653,9 @@
status : integer
Returns an integer containing the HTTP status code in the HTTP response, for
example, 302. It is mostly used within ACLs and integer ranges, for example,
- to remove any Location header if the response is not a 3xx. It may be used in
- tcp-check based expect rules.
+ to remove any Location header if the response is not a 3xx.
+
+ It may be used in tcp-check based expect rules.
unique-id : string
Returns the unique-id attached to the request. The directive