From: Willy Tarreau Date: Mon, 26 May 2025 07:07:54 +0000 (+0200) Subject: DOC: config: fix alphabetical ordering of layer 7 sample fetch functions X-Git-Tag: v3.2.0~24 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e9248243e9946174271bf29d3b44634c862ae444;p=thirdparty%2Fhaproxy.git DOC: config: fix alphabetical ordering of layer 7 sample fetch functions Some misordering has been accumulating over time, making some of them hard to spot. --- diff --git a/doc/configuration.txt b/doc/configuration.txt index 4b23854c3..36ef943ed 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -25140,36 +25140,14 @@ capture.req.uri string capture.req.ver string capture.res.hdr() string capture.res.ver string -req.body binary -req.body_param([[,i]]) string -req.body_len integer -req.body_size integer -req.cook([]) string cook([]) string -req.cook_cnt([]) integer cook_cnt([]) integer -req.cook_val([]) integer cook_val([]) integer -req.cook_names([]) string cookie([]) string hdr([[,]]) string -request_date([]) integer -req.fhdr([,]) string -req.fhdr_cnt([]) integer -req.hdr([[,]]) string -req.hdr_cnt([]) integer hdr_cnt([
]) integer -req.hdr_ip([[,]]) ip hdr_ip([[,]]) ip -req.hdr_val([[,]]) integer hdr_val([[,]]) integer -req.hdrs string -req.hdrs_bin binary -req.timer.hdr integer -req.timer.idle integer -req.timer.queue integer -req.timer.tq integer -res.timer.hdr integer http_auth() boolean http_auth_bearer([
]) string http_auth_group() string @@ -25181,9 +25159,30 @@ method integer path string pathq string query([]) string +req.body binary +req.body_len integer +req.body_param([[,i]]) string +req.body_size integer +req.cook([]) string +req.cook_cnt([]) integer +req.cook_names([]) string +req.cook_val([]) integer +req.fhdr([,]) string +req.fhdr_cnt([]) integer +req.hdr([[,]]) string +req.hdr_cnt([]) integer +req.hdr_ip([[,]]) ip req.hdr_names([]) string +req.hdr_val([[,]]) integer +req.hdrs string +req.hdrs_bin binary +req.timer.hdr integer +req.timer.idle integer +req.timer.queue integer +req.timer.tq integer req.ver string req_ver string +request_date([]) integer res.body binary res.body_len integer res.body_size integer @@ -25192,41 +25191,42 @@ res.cache_name string res.comp boolean res.comp_algo string res.cook([]) string -scook([]) string res.cook_cnt([]) integer -scook_cnt([]) integer -res.cook_val([]) integer -scook_val([]) integer res.cook_names([]) string +res.cook_val([]) integer res.fhdr([[,]]) string res.fhdr_cnt([]) integer res.hdr([[,]]) string -shdr([[,]]) string res.hdr_cnt([]) integer -shdr_cnt([]) integer res.hdr_ip([[,]]) ip -shdr_ip([[,]]) ip res.hdr_names([]) string res.hdr_val([[,]]) integer -shdr_val([[,]]) integer res.hdrs string res.hdrs_bin binary +res.timer.hdr integer res.ver string resp_ver string +scook([]) string +scook_cnt([]) integer +scook_val([]) integer server_status integer set-cookie([]) string +shdr([[,]]) string +shdr_cnt([]) integer +shdr_ip([[,]]) ip +shdr_val([[,]]) integer status integer txn.status integer txn.timer.total integer unique-id string url string +url32 integer +url32+src binary url_ip ip +url_param([[,[,i]]]) string url_port integer urlp([[,[,i]]]) string -url_param([[,[,i]]]) string urlp_val([[,[,i]]]) integer -url32 integer -url32+src binary -------------------------------------------------+------------- Detailed list: @@ -25303,11 +25303,150 @@ capture.res.ver : string "HTTP/1.1". Unlike "res.ver", it can be used in logs because it relies on a persistent flag. +cookie([]) : string (deprecated) + This extracts the last occurrence of the cookie name on a "Cookie" + header line from the request, or a "Set-Cookie" header from the response, and + returns its value as a string. A typical use is to get multiple clients + sharing a same profile use the same server. This can be similar to what + "appsession" did with the "request-learn" statement, but with support for + multi-peer synchronization and state keeping across restarts. If no name is + specified, the first cookie value is returned. This fetch should not be used + anymore and should be replaced by req.cook() or res.cook() instead as it + ambiguously uses the direction based on the context where it is used. + +hdr([[,]]) : string + This is equivalent to req.hdr() when used on requests, and to res.hdr() when + used on responses. Please refer to these respective fetches for more details. + In case of doubt about the fetch direction, please use the explicit ones. + Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords + unambiguously apply to the request headers. + +http_auth() : boolean + Returns a boolean indicating whether the authentication data received from + the client match a username & password stored in the specified userlist. This + fetch function is not really useful outside of ACLs. Currently only http + basic auth is supported. + +http_auth_bearer([
]) : string + Returns the client-provided token found in the authorization data when the + Bearer scheme is used (to send JSON Web Tokens for instance). No check is + performed on the data sent by the client. + If a specific
is supplied, it will parse this header instead of the + Authorization one. + +http_auth_group() : string + Returns a string corresponding to the user name found in the authentication + data received from the client if both the user name and password are valid + according to the specified userlist. The main purpose is to use it in ACLs + where it is then checked whether the user belongs to any group within a list. + This fetch function is not really useful outside of ACLs. Currently only http + basic auth is supported. + + ACL derivatives : + http_auth_group() : group ... + Returns true when the user extracted from the request and whose password is + valid according to the specified userlist belongs to at least one of the + groups. + +http_auth_pass : string + Returns the user's password found in the authentication data received from + the client, as supplied in the Authorization header. Not checks are + performed by this sample fetch. Only Basic authentication is supported. + +http_auth_type : string + Returns the authentication method found in the authentication data received from + the client, as supplied in the Authorization header. Not checks are + performed by this sample fetch. Only Basic authentication is supported. + +http_auth_user : string + Returns the user name found in the authentication data received from the + client, as supplied in the Authorization header. Not checks are performed by + this sample fetch. Only Basic authentication is supported. + +http_first_req : boolean + Returns true when the request being processed is the first one of the + connection. This can be used to add or remove headers that may be missing + from some requests when a request is not the first one, or to help grouping + requests in the logs. + +method : integer + string + Returns an integer value corresponding to the method in the HTTP request. For + example, "GET" equals 1 (check sources to establish the matching). Value 9 + means "other method" and may be converted to a string extracted from the + stream. This should not be used directly as a sample, this is only meant to + be used from ACLs, which transparently convert methods from patterns to these + integer + string values. Some predefined ACL already check for most common + methods. + + ACL derivatives : + method : case insensitive method match + + Example : + # only accept GET and HEAD requests + acl valid_method method GET HEAD + http-request deny if ! valid_method + +path : string + This extracts the request's URL path, which starts at the first slash and + ends before the question mark (without the host part). A typical use is with + prefetch-capable caches, and with portals which need to aggregate multiple + information from databases and keep them in caches. Note that with outgoing + caches, it would be wiser to use "url" instead. With ACLs, it's typically + used to match exact file names (e.g. "/login.php"), or directory parts using + the derivative forms. See also the "url" and "base" fetch methods. Please + note that any fragment reference in the URI ('#' after the path) is strictly + forbidden by the HTTP standard and will be rejected. However, if the frontend + receiving the request has "option accept-unsafe-violations-in-http-request", + then this fragment part will be accepted and will also appear in the path. + + ACL derivatives : + path : exact string match + path_beg : prefix match + path_dir : subdir match + path_dom : domain match + path_end : suffix match + path_len : length match + path_reg : regex match + path_sub : substring match + +pathq : string + This extracts the request's URL path with the query-string, which starts at + the first slash. This sample fetch is pretty handy to always retrieve a + relative URI, excluding the scheme and the authority part, if any. Indeed, + while it is the common representation for an HTTP/1.1 request target, in + HTTP/2, an absolute URI is often used. This sample fetch will return the same + result in both cases. Please note that any fragment reference in the URI ('#' + after the path) is strictly forbidden by the HTTP standard and will be + rejected. However, if the frontend receiving the request has "option + accept-unsafe-violations-in-http-request", then this fragment part will be + accepted and will also appear in the path. + +query([]) : string + This extracts the request's query string, which starts after the first + question mark. If no question mark is present, this fetch returns nothing. If + a question mark is present but nothing follows, it returns an empty string. + This means it's possible to easily know whether a query string is present + using the "found" matching method. This fetch is the complement of "path" + which stops before the question mark and of "query_string", which include the + question mark. + + An optional parameter may be used to customize the return value. Following + options are supported: + + - with_qm : Include the question mark at the beginning ot the query string, + if not empty. + req.body : binary This returns the HTTP request's available body as a block of data. It is recommended to use "option http-buffer-request" to be sure to wait, as much as possible, for the request's body. +req.body_len : integer + This returns the length of the HTTP request's available body in bytes. It may + be lower than the advertised length if the body is larger than the buffer. It + is recommended to use "option http-buffer-request" to be sure to wait, as + much as possible, for the request's body. + req.body_param([[,i]]) : string This fetch assumes that the body of the POST request is url-encoded. The user can check if the "content-type" contains the value @@ -25320,12 +25459,6 @@ req.body_param([[,i]]) : string ACL version of this fetch iterates over multiple parameters and will iteratively report all parameters values if no name is given. -req.body_len : integer - This returns the length of the HTTP request's available body in bytes. It may - be lower than the advertised length if the body is larger than the buffer. It - is recommended to use "option http-buffer-request" to be sure to wait, as - much as possible, for the request's body. - req.body_size : integer This returns the advertised length of the HTTP request's body in bytes. It will represent the advertised Content-Length header, or the size of the @@ -25357,49 +25490,18 @@ cook_cnt([]) : integer (deprecated) Returns an integer value representing the number of occurrences of the cookie in the request, or all cookies if is not specified. -req.cook_val([]) : integer -cook_val([]) : integer (deprecated) - This extracts the last occurrence of the cookie name on a "Cookie" - header line from the request, and converts its value to an integer which is - returned. If no name is specified, the first cookie value is returned. When - used in ACLs, all matching names are iterated over until a value matches. - req.cook_names([]) : string This builds a string made from the concatenation of all cookie names as they appear in the request (Cookie header) when the rule is evaluated. The default delimiter is the comma (',') but it may be overridden as an optional argument . In this case, only the first character of is considered. -cookie([]) : string (deprecated) +req.cook_val([]) : integer +cook_val([]) : integer (deprecated) This extracts the last occurrence of the cookie name on a "Cookie" - header line from the request, or a "Set-Cookie" header from the response, and - returns its value as a string. A typical use is to get multiple clients - sharing a same profile use the same server. This can be similar to what - "appsession" did with the "request-learn" statement, but with support for - multi-peer synchronization and state keeping across restarts. If no name is - specified, the first cookie value is returned. This fetch should not be used - anymore and should be replaced by req.cook() or res.cook() instead as it - ambiguously uses the direction based on the context where it is used. - -hdr([[,]]) : string - This is equivalent to req.hdr() when used on requests, and to res.hdr() when - used on responses. Please refer to these respective fetches for more details. - In case of doubt about the fetch direction, please use the explicit ones. - Note that contrary to the hdr() sample fetch method, the hdr_* ACL keywords - unambiguously apply to the request headers. - -request_date([]) : integer - This is the exact date when the first byte of the HTTP request was received - by HAProxy (log-format alias %tr). This is computed from accept_date + - handshake time (%Th) + idle time (%Ti). - - Returns a value in number of seconds since epoch. - - is facultative, and can be set to "s" for seconds (default behavior), - "ms" for milliseconds or "us" for microseconds. - If unit is set, return value is an integer reflecting either seconds, - milliseconds or microseconds since epoch. - It is useful when a time resolution of less than a second is needed. + header line from the request, and converts its value to an integer which is + returned. If no name is specified, the first cookie value is returned. When + used in ACLs, all matching names are iterated over until a value matches. req.fhdr([,]) : string This returns the full value of the last occurrence of header in an @@ -25480,6 +25582,12 @@ hdr_ip([[,]]) : ip (deprecated) A typical use is with the X-Forwarded-For and X-Client-IP headers. +req.hdr_names([]) : string + This builds a string made from the concatenation of all header names as they + appear in the request when the rule is evaluated. The default delimiter is + the comma (',') but it may be overridden as an optional argument . In + this case, only the first character of is considered. + req.hdr_val([[,]]) : integer hdr_val([[,]]) : integer (deprecated) This extracts the last occurrence of header in an HTTP request, and @@ -25533,134 +25641,6 @@ req.timer.tq : integer This is reported in milliseconds and is equivalent to %Tq in log-format. See section 8.4 "Timing events" for more details. -res.timer.hdr : integer - It's the time elapsed between the moment the TCP connection was established - to the server and the moment the server sent its complete response headers. - This is reported in milliseconds and is equivalent to %Tr in log-format. See - section 8.4 "Timing events" for more details. - - -http_auth() : boolean - Returns a boolean indicating whether the authentication data received from - the client match a username & password stored in the specified userlist. This - fetch function is not really useful outside of ACLs. Currently only http - basic auth is supported. - -http_auth_bearer([
]) : string - Returns the client-provided token found in the authorization data when the - Bearer scheme is used (to send JSON Web Tokens for instance). No check is - performed on the data sent by the client. - If a specific
is supplied, it will parse this header instead of the - Authorization one. - -http_auth_group() : string - Returns a string corresponding to the user name found in the authentication - data received from the client if both the user name and password are valid - according to the specified userlist. The main purpose is to use it in ACLs - where it is then checked whether the user belongs to any group within a list. - This fetch function is not really useful outside of ACLs. Currently only http - basic auth is supported. - - ACL derivatives : - http_auth_group() : group ... - Returns true when the user extracted from the request and whose password is - valid according to the specified userlist belongs to at least one of the - groups. - -http_auth_pass : string - Returns the user's password found in the authentication data received from - the client, as supplied in the Authorization header. Not checks are - performed by this sample fetch. Only Basic authentication is supported. - -http_auth_type : string - Returns the authentication method found in the authentication data received from - the client, as supplied in the Authorization header. Not checks are - performed by this sample fetch. Only Basic authentication is supported. - -http_auth_user : string - Returns the user name found in the authentication data received from the - client, as supplied in the Authorization header. Not checks are performed by - this sample fetch. Only Basic authentication is supported. - -http_first_req : boolean - Returns true when the request being processed is the first one of the - connection. This can be used to add or remove headers that may be missing - from some requests when a request is not the first one, or to help grouping - requests in the logs. - -method : integer + string - Returns an integer value corresponding to the method in the HTTP request. For - example, "GET" equals 1 (check sources to establish the matching). Value 9 - means "other method" and may be converted to a string extracted from the - stream. This should not be used directly as a sample, this is only meant to - be used from ACLs, which transparently convert methods from patterns to these - integer + string values. Some predefined ACL already check for most common - methods. - - ACL derivatives : - method : case insensitive method match - - Example : - # only accept GET and HEAD requests - acl valid_method method GET HEAD - http-request deny if ! valid_method - -path : string - This extracts the request's URL path, which starts at the first slash and - ends before the question mark (without the host part). A typical use is with - prefetch-capable caches, and with portals which need to aggregate multiple - information from databases and keep them in caches. Note that with outgoing - caches, it would be wiser to use "url" instead. With ACLs, it's typically - used to match exact file names (e.g. "/login.php"), or directory parts using - the derivative forms. See also the "url" and "base" fetch methods. Please - note that any fragment reference in the URI ('#' after the path) is strictly - forbidden by the HTTP standard and will be rejected. However, if the frontend - receiving the request has "option accept-unsafe-violations-in-http-request", - then this fragment part will be accepted and will also appear in the path. - - ACL derivatives : - path : exact string match - path_beg : prefix match - path_dir : subdir match - path_dom : domain match - path_end : suffix match - path_len : length match - path_reg : regex match - path_sub : substring match - -pathq : string - This extracts the request's URL path with the query-string, which starts at - the first slash. This sample fetch is pretty handy to always retrieve a - relative URI, excluding the scheme and the authority part, if any. Indeed, - while it is the common representation for an HTTP/1.1 request target, in - HTTP/2, an absolute URI is often used. This sample fetch will return the same - result in both cases. Please note that any fragment reference in the URI ('#' - after the path) is strictly forbidden by the HTTP standard and will be - rejected. However, if the frontend receiving the request has "option - accept-unsafe-violations-in-http-request", then this fragment part will be - accepted and will also appear in the path. - -query([]) : string - This extracts the request's query string, which starts after the first - question mark. If no question mark is present, this fetch returns nothing. If - a question mark is present but nothing follows, it returns an empty string. - This means it's possible to easily know whether a query string is present - using the "found" matching method. This fetch is the complement of "path" - which stops before the question mark and of "query_string", which include the - question mark. - - An optional parameter may be used to customize the return value. Following - options are supported: - - - with_qm : Include the question mark at the beginning ot the query string, - if not empty. - -req.hdr_names([]) : string - This builds a string made from the concatenation of all header names as they - appear in the request when the rule is evaluated. The default delimiter is - the comma (',') but it may be overridden as an optional argument . In - this case, only the first character of is considered. - req.ver : string req_ver : string (deprecated) Returns the version string from the HTTP request, for example "1.1". This can @@ -25676,6 +25656,19 @@ req_ver : string (deprecated) ACL derivatives : req.ver : exact string match +request_date([]) : integer + This is the exact date when the first byte of the HTTP request was received + by HAProxy (log-format alias %tr). This is computed from accept_date + + handshake time (%Th) + idle time (%Ti). + + Returns a value in number of seconds since epoch. + + is facultative, and can be set to "s" for seconds (default behavior), + "ms" for milliseconds or "us" for microseconds. + If unit is set, return value is an integer reflecting either seconds, + milliseconds or microseconds since epoch. + It is useful when a time resolution of less than a second is needed. + 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 @@ -25737,14 +25730,6 @@ scook_cnt([]) : integer (deprecated) It may be used in tcp-check based expect rules. -res.cook_val([]) : integer -scook_val([]) : integer (deprecated) - This extracts the last occurrence of the cookie 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. - res.cook_names([]) : string This builds a string made from the concatenation of all cookie names as they appear in the response (Set-Cookie headers) when the rule is evaluated. The @@ -25754,6 +25739,14 @@ res.cook_names([]) : string It may be used in tcp-check based expect rules. +res.cook_val([]) : integer +scook_val([]) : integer (deprecated) + This extracts the last occurrence of the cookie 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. + res.fhdr([[,]]) : string This fetch works like the req.fhdr() fetch with the difference that it acts on the headers within an HTTP response. @@ -25852,6 +25845,12 @@ res.hdrs_bin : binary int: refer to the SPOE documentation for the encoding str: +res.timer.hdr : integer + It's the time elapsed between the moment the TCP connection was established + to the server and the moment the server sent its complete response headers. + This is reported in milliseconds and is equivalent to %Tr in log-format. See + section 8.4 "Timing events" for more details. + res.ver : string resp_ver : string (deprecated) Returns the version string from the HTTP response, for example "1.1". This @@ -25926,6 +25925,18 @@ url : string url_reg : regex match url_sub : substring match +url32 : integer + This returns a 32-bit hash of the value obtained by concatenating the first + Host header and the whole URL including parameters (not only the path part of + the request, as in the "base32" fetch above). This is useful to track per-URL + activity. A shorter hash is stored, saving a lot of memory. The output type + is an unsigned integer. + +url32+src : binary + This returns the concatenation of the "url32" fetch and the "src" fetch. The + resulting type is of type binary, with a size of 8 or 20 bytes depending on + the source address family. This can be used to track per-IP, per-URL counters. + url_ip : ip This extracts the IP address from the request's URL when the host part is presented as an IP address. Its use is very limited. For instance, a @@ -25973,18 +25984,6 @@ urlp_val([[,[,i]]]) : integer and converts it to an integer value. This can be used for session stickiness based on a user ID for example, or with ACLs to match a page number or price. -url32 : integer - This returns a 32-bit hash of the value obtained by concatenating the first - Host header and the whole URL including parameters (not only the path part of - the request, as in the "base32" fetch above). This is useful to track per-URL - activity. A shorter hash is stored, saving a lot of memory. The output type - is an unsigned integer. - -url32+src : binary - This returns the concatenation of the "url32" fetch and the "src" fetch. The - resulting type is of type binary, with a size of 8 or 20 bytes depending on - the source address family. This can be used to track per-IP, per-URL counters. - 7.3.7. Fetching samples for developers ---------------------------------------