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.
---
doc/configuration.txt | 210 +++---
1 file changed, 116 insertions(+), 94 deletions(-)
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 899bdf553..4dd105d44 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -18509,33 +18509,44 @@ hdr([[,]]) : string
unambiguously apply to the request headers.
req.fhdr([,]) : string
- This extracts the last occurrence of header 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 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([]) : integer
Returns an integer value representing the number of occurrences of request
header field name , or the total number of header fields if 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([[,]]) : string
- This extracts the last occurrence of header 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 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([[,]]) : exact string match
@@ -18551,34 +18562,36 @@ req.hdr_cnt([]) : integer
hdr_cnt([]) : integer (deprecated)
Returns an integer value representing the number of occurrences of request
header field name , or the total number of header field values if
- 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.
+ is not specified. Like req.hdr() it counts each comma separated
+ part of the header's value. If counting of full-line headers
