konevsa/haproxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOC: Improve documentation of the various hdr() fetches

Browse Source 
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.
This commit is contained in:
Tim Duesterhus 2021-01-23 17:50:21 +01:00 committed by Christopher Faulet
parent 7704b0e1e1
commit 27c70ae23c
1 changed files with 116 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
doc/configuration.txt
View File

@ -18509,33 +18509,44 @@ hdr([<name>[,<occ>]]) : string
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
@ -18551,34 +18562,36 @@ req.hdr_cnt([<name>]) : integer
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
@ -18710,22 +18723,25 @@ req_ver : string (deprecated)
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
@ -18750,8 +18766,9 @@ res.cook([<name>]) : string
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
@ -18760,46 +18777,47 @@ res.cook_cnt([<name>]) : integer
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
@ -18813,45 +18831,47 @@ shdr([<name>[,<occ>]]) : string (deprecated)
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
@ -18870,8 +18890,9 @@ res.hdrs_bin : binary
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
@ -18888,8 +18909,9 @@ set-cookie([<name>]) : string (deprecated)
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