From 71d1892190b841b37e818bc7c871f01f277921da Mon Sep 17 00:00:00 2001 From: Christopher Faulet Date: Thu, 14 Oct 2021 08:18:50 +0200 Subject: [PATCH] DOC: config: Rework and uniformize how TCP/HTTP rules are documented Now all these rules are documented using the same structure. First there is a general description with the list of all supported actions. Then all actions are described in details. Thus, it is easy to have a quick list of all supported actions and this avoids to have a huge description with all info about these actions. In addition, when it is possible, we make a reference to already documented parts. --- doc/configuration.txt | 1588 +++++++++++++++++++---------------------- 1 file changed, 718 insertions(+), 870 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index 6166912ede..a05bfa694f 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -5304,8 +5304,21 @@ http-after-response [ { if | unless } ] server ones but also to all responses generated by HAProxy. These rules are evaluated at the end of the responses analysis, before the data forwarding. - The first keyword is the rule's action. The supported actions are described - below. + The first keyword is the rule's action. Several types of actions are + supported: + - add-header + - allow + - del-header [ -m ] + - replace-header + - replace-value + - set-header + - set-status [reason ] + - set-var() + - set-var-fmt() + - strict-mode { on | off } + - unset-var() + + The supported actions are described below. There is no limit to the number of http-after-response statements per instance. @@ -5329,12 +5342,8 @@ http-after-response [ { if | unless } ] http-after-response add-header [ { if | unless } ] This appends an HTTP header field whose name is specified in and whose - value is defined by which follows the log-format rules (see Custom Log - Format in section 8.2.4). This may be used to send a cookie to a client for - example, or to pass some internal information. - This rule is not final, so it is possible to add other similar rules. - Note that header addition is performed immediately, so one rule might reuse - the resulting header from a previous rule. + value is defined by . Please refer to "http-request add-header" for a + complete description. http-after-response allow [ { if | unless } ] @@ -5343,11 +5352,8 @@ http-after-response allow [ { if | unless } ] http-after-response del-header [ -m ] [ { if | unless } ] - This removes all HTTP header fields whose name is specified in . - is the matching method, applied on the header name. Supported matching methods - are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub" - (substring match) and "reg" (regex match). If not specified, exact matching - method is used. + This removes all HTTP header fields whose name is specified in . Please + refer to "http-request del-header" for a complete description. http-after-response replace-header [ { if | unless } ] @@ -5381,76 +5387,34 @@ http-after-response replace-value http-after-response set-header [ { if | unless } ] - This does the same as "add-header" except that the header name is first - removed if it existed. This is useful when passing security information to - the server, where the header must not be manipulated by external users. + This does the same as "http-after-response add-header" except that the header + name is first removed if it existed. This is useful when passing security + information to the server, where the header must not be manipulated by + external users. http-after-response set-status [reason ] [ { if | unless } ] This replaces the response status code with which must be an integer - between 100 and 999. Optionally, a custom reason text can be provided defined - by , or the default reason for the specified code will be used as a - fallback. - - Example: - # return "431 Request Header Fields Too Large" - http-response set-status 431 - # return "503 Slow Down", custom reason - http-response set-status 503 reason "Slow Down" + between 100 and 999. Plese refer to "http-response set-status" for a complete + description. http-after-response set-var() [ { if | unless } ] http-after-response set-var-fmt() [ { if | unless } ] + This is used to set the contents of a variable. The variable is declared - inline. + inline. Please refer to "http-request set-var" and "http-request set-var-fmt" + for a complete description. - Arguments: - The name of the variable starts with an indication about its - scope. The scopes allowed are: - "proc" : the variable is shared with the whole process - "sess" : the variable is shared with the whole session - "txn" : the variable is shared with the transaction - (request and response) - "req" : the variable is shared only during request - processing - "res" : the variable is shared only during response - processing - This prefix is followed by a name. The separator is a '.'. - The name may only contain characters 'a-z', 'A-Z', '0-9', '.' - and '_'. +http-after-response strict-mode { on | off } [ { if | unless } ] - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - This is the value expressed using log-format rules (see Custom - Log Format in section 8.2.4). - - Examples: - http-after-response set-var(sess.last_redir) res.hdr(location) - http-after-response set-var-fmt(sess.last_be_addr) %[bi]:%[bp] - -http-after-response strict-mode { on | off } - - This enables or disables the strict rewriting mode for following rules. It - does not affect rules declared before it and it is only applicable on rules - performing a rewrite on the responses. When the strict mode is enabled, any - rewrite failure triggers an internal error. Otherwise, such errors are - silently ignored. The purpose of the strict rewriting mode is to make some - rewrites optional while others must be performed to continue the response - processing. - - By default, the strict rewriting mode is enabled. Its value is also reset - when a ruleset evaluation ends. So, for instance, if you change the mode on - the backend, the default mode is restored when HAProxy starts the frontend - rules evaluation. + This enables or disables the strict rewriting mode for following + rules. Please refer to "http-request strict-mode" for a complete description. http-after-response unset-var() [ { if | unless } ] - This is used to unset a variable. See "http-after-response set-var" for - details about . - - Example: - http-after-response unset-var(sess.last_redir) + This is used to unset a variable. See "http-request set-var" for details + about . http-check comment @@ -6014,8 +5978,69 @@ http-request [options...] [ { if | unless } ] followed by an ACL-based condition, in which case it will only be evaluated if the condition is true. - The first keyword is the rule's action. The supported actions are described - below. + The first keyword is the rule's action. Several types of actions are + supported: + - add-acl() + - add-header + - allow + - auth [realm ] + - cache-use + - capture [ len | id ] + - del-acl() + - del-header [ -m ] + - del-map() + - deny [ { status | deny_status } ] ... + - disable-l7-retry + - do-resolve(,,[ipv4,ipv6]) + - early-hint + - normalize-uri + - redirect + - reject + - replace-header + - replace-path + - replace-pathq + - replace-uri + - replace-value + - return [status ] [content-type ] ... + - sc-inc-gpc(,) + - sc-inc-gpc0() + - sc-inc-gpc1() + - sc-set-gpt(,) { | } + - sc-set-gpt0() { | } + - set-dst + - set-dst-port + - set-header + - set-log-level + - set-map() + - set-mark + - set-method + - set-nice + - set-path + - set-pathq + - set-priority-class + - set-priority-offset + - set-query + - set-src + - set-src-port + - set-timeout { server | tunnel } { | } + - set-tos + - set-uri + - set-var() + - set-var-fmt() + - send-spoe-group + - silent-drop + - strict-mode { on | off } + - tarpit [ { status | deny_status } ] ... + - track-sc0 [table ] + - track-sc1 [table
] + - track-sc2 [table
] + - unset-var() + - use-service + - wait-for-body time
] + - track-sc1 [table
] + - track-sc2 [table
] + - unset-var() + - wait-for-body time
] [ { if | unless } ] http-response track-sc1 [table
] [ { if | unless } ] http-response track-sc2 [table
] [ { if | unless } ] - This enables tracking of sticky counters from current response. Please refer - to "http-request track-sc" for a complete description. The only difference - from "http-request track-sc" is the sample expression can only make use - of samples in response (e.g. res.*, status etc.) and samples below Layer 6 - (e.g. SSL-related samples, see section 7.3.4). If the sample is not - supported, HAProxy will fail and warn while parsing the config. + This enables tracking of sticky counters from current connection. Please + refer to "http-request track-sc0", "http-request track-sc1" and "http-request + track-sc2" for a complete description. http-response unset-var() [ { if | unless } ] - This is used to unset a variable. See "http-response set-var" for details + This is used to unset a variable. See "http-request set-var" for details about . - Example: - http-response unset-var(sess.last_redir) - http-response wait-for-body time
] + - track-sc1 [table
] + - track-sc2 [table
] + + The supported actions are described below. + + There is no limit to the number of "tcp-request connection" statements per + instance. This directive is only available from named defaults sections, not anonymous ones. Rules defined in the defaults section are evaluated before ones in the @@ -12110,244 +11999,6 @@ tcp-request connection [{if | unless} ] by proxies with the backend capability. It means a listen section cannot use a defaults section defining such rules. - Four types of actions are supported : - - accept : - accepts the connection if the condition is true (when used with "if") - or false (when used with "unless"). The first such rule executed ends - the rules evaluation. - - - reject : - rejects the connection if the condition is true (when used with "if") - or false (when used with "unless"). The first such rule executed ends - the rules evaluation. Rejected connections do not even become a - session, which is why they are accounted separately for in the stats, - as "denied connections". They are not considered for the session - rate-limit and are not logged either. The reason is that these rules - should only be used to filter extremely high connection rates such as - the ones encountered during a massive DDoS attack. Under these extreme - conditions, the simple action of logging each event would make the - system collapse and would considerably lower the filtering capacity. If - logging is absolutely desired, then "tcp-request content" rules should - be used instead, as "tcp-request session" rules will not log either. - - - expect-proxy layer4 : - configures the client-facing connection to receive a PROXY protocol - header before any byte is read from the socket. This is equivalent to - having the "accept-proxy" keyword on the "bind" line, except that using - the TCP rule allows the PROXY protocol to be accepted only for certain - IP address ranges using an ACL. This is convenient when multiple layers - of load balancers are passed through by traffic coming from public - hosts. - - - expect-netscaler-cip layer4 : - configures the client-facing connection to receive a NetScaler Client - IP insertion protocol header before any byte is read from the socket. - This is equivalent to having the "accept-netscaler-cip" keyword on the - "bind" line, except that using the TCP rule allows the PROXY protocol - to be accepted only for certain IP address ranges using an ACL. This - is convenient when multiple layers of load balancers are passed - through by traffic coming from public hosts. - - - capture len : - This only applies to "tcp-request content" rules. It captures sample - expression from the request buffer, and converts it to a - string of at most characters. The resulting string is stored into - the next request "capture" slot, so it will possibly appear next to - some captured HTTP headers. It will then automatically appear in the - logs, and it will be possible to extract it using sample fetch rules to - feed it into headers or anything. The length should be limited given - that this size will be allocated for each capture during the whole - session life. Please check section 7.3 (Fetching samples) and "capture - request header" for more information. - - - { track-sc0 | track-sc1 | track-sc2 } [table
] : - enables tracking of sticky counters from current connection. These - rules do not stop evaluation and do not change default action. The - number of counters that may be simultaneously tracked by the same - connection is set in MAX_SESS_STKCTR at build time (reported in - haproxy -vv) which defaults to 3, so the track-sc number is between 0 - and (MAX_SESS_STKCTR-1). The first "track-sc0" rule executed enables - tracking of the counters of the specified table as the first set. The - first "track-sc1" rule executed enables tracking of the counters of the - specified table as the second set. The first "track-sc2" rule executed - enables tracking of the counters of the specified table as the third - set. It is a recommended practice to use the first set of counters for - the per-frontend counters and the second set for the per-backend ones. - But this is just a guideline, all may be used everywhere. - - These actions take one or two arguments : - is mandatory, and is a sample expression rule as described - in section 7.3. It describes what elements of the incoming - request or connection will be analyzed, extracted, combined, - and used to select which table entry to update the counters. - Note that "tcp-request connection" cannot use content-based - fetches. - -
is an optional table to be used instead of the default one, - which is the stick-table declared in the current proxy. All - the counters for the matches and updates for the key will - then be performed in that table until the session ends. - - Once a "track-sc*" rule is executed, the key is looked up in the table - and if it is not found, an entry is allocated for it. Then a pointer to - that entry is kept during all the session's life, and this entry's - counters are updated as often as possible, every time the session's - counters are updated, and also systematically when the session ends. - Counters are only updated for events that happen after the tracking has - been started. For example, connection counters will not be updated when - tracking layer 7 information, since the connection event happens before - layer7 information is extracted. - - If the entry tracks concurrent connection counters, one connection is - counted for as long as the entry is tracked, and the entry will not - expire during that time. Tracking counters also provides a performance - advantage over just checking the keys, because only one table lookup is - performed for all ACL checks that make use of it. - - - sc-inc-gpc(,): - This actions increments the General Purpose Counter at the index - of the array associated to the sticky counter designated by . - If an error occurs, this action silently fails and the actions - evaluation continues. is an integer between 0 and 99 and - is an integer between 0 and 2. It also silently fails if the there is - no GPC stored at this index. - This action applies only to the 'gpc' and 'gpc_rate' array data_types - (and not to the legacy 'gpc0', 'gpc1', 'gpc0_rate' nor 'gpc1_rate' - data_types). - - - sc-inc-gpc0(): - The "sc-inc-gpc0" increments the GPC0 counter according to the sticky - counter designated by . If an error occurs, this action silently - fails and the actions evaluation continues. - - - sc-inc-gpc1(): - The "sc-inc-gpc1" increments the GPC1 counter according to the sticky - counter designated by . If an error occurs, this action silently - fails and the actions evaluation continues. - - - sc-set-gpt(,) { | }: - This action sets the 32-bit unsigned GPT at the index of the - array associated to the sticky counter designated by at the - value of /. The expected result is a boolean. - If an error occurs, this action silently fails and the actions - evaluation continues. is an integer between 0 and 99 and - is an integer between 0 and 2. It also silently fails if the there is - no GPT stored at this index. - This action applies only to the 'gpt' array data_type (and not to the - legacy 'gpt0' data-type). - - - sc-set-gpt0() { | }: - This action sets the 32-bit unsigned GPT0 tag according to the sticky - counter designated by and the value of /. The - expected result is a boolean. If an error occurs, this action silently - fails and the actions evaluation continues. - - - set-mark : - Is used to set the Netfilter/IPFW MARK in all packets sent to the client - to the value passed in on platforms which support it. This value - is an unsigned 32 bit value which can be matched by netfilter/ipfw and by - the routing table or monitoring the packets through DTrace. - It can be expressed both in decimal or hexadecimal format (prefixed by - "0x"). This can be useful to force certain packets to take a different - route (for example a cheaper network path for bulk downloads). This works - on Linux kernels 2.6.32 and above and requires admin privileges, as well - on FreeBSD and OpenBSD. - - - set-src : - Is used to set the source IP address to the value of specified - expression. Useful if you want to mask source IP for privacy. - If you want to provide an IP from a HTTP header use "http-request - set-src". - - Arguments: - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - Example: - tcp-request connection set-src src,ipmask(24) - - When possible, set-src preserves the original source port as long as the - address family allows it, otherwise the source port is set to 0. - - - set-src-port : - Is used to set the source port address to the value of specified - expression. - - Arguments: - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - Example: - tcp-request connection set-src-port int(4000) - - When possible, set-src-port preserves the original source address as long - as the address family supports a port, otherwise it forces the source - address to IPv4 "0.0.0.0" before rewriting the port. - - - set-dst : - Is used to set the destination IP address to the value of specified - expression. Useful if you want to mask IP for privacy in log. - If you want to provide an IP from a HTTP header use "http-request - set-dst". If you want to connect to the new address/port, use - '0.0.0.0:0' as a server address in the backend. - - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - Example: - - tcp-request connection set-dst dst,ipmask(24) - tcp-request connection set-dst ipv4(10.0.0.1) - - When possible, set-dst preserves the original destination port as long as - the address family allows it, otherwise the destination port is set to 0. - - - set-dst-port : - Is used to set the destination port address to the value of specified - expression. If you want to connect to the new address/port, use - '0.0.0.0:0' as a server address in the backend. - - - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - Example: - - tcp-request connection set-dst-port int(4000) - - When possible, set-dst-port preserves the original destination address as - long as the address family supports a port, otherwise it forces the - destination address to IPv4 "0.0.0.0" before rewriting the port. - - - set-tos : - Is used to set the TOS or DSCP field value of packets sent to the client - to the value passed in on platforms which support this. This value - represents the whole 8 bits of the IP TOS field, and can be expressed - both in decimal or hexadecimal format (prefixed by "0x"). Note that only - the 6 higher bits are used in DSCP or TOS, and the two lower bits are - always 0. This can be used to adjust some routing behavior on border - routers based on some information from the request. - - See RFC 2474, 2597, 3260 and 4594 for more information. - - - "silent-drop" : - This stops the evaluation of the rules and makes the client-facing - connection suddenly disappear using a system-dependent way that tries - to prevent the client from being notified. The effect it then that the - client still sees an established connection while there's none on - HAProxy. The purpose is to achieve a comparable effect to "tarpit" - except that it doesn't use any local resource at all on the machine - running HAProxy. It can resist much higher loads than "tarpit", and - slow down stronger attackers. It is important to understand the impact - of using this mechanism. All stateful equipment placed between the - client and HAProxy (firewalls, proxies, load balancers) will also keep - the established connection for a long time and may suffer from this - action. On modern Linux systems running with enough privileges, the - TCP_REPAIR socket option is used to block the emission of a TCP - reset. On other systems, the socket's TTL is reduced to 1 so that the - TCP reset doesn't pass the first router, though it's still delivered to - local networks. Do not use it unless you fully understand how it works. - Note that the "if/unless" condition is optional. If no condition is set on the action, it is simply performed unconditionally. That can be useful for "track-sc*" actions as well as for changing the default action to a reject. @@ -12376,6 +12027,104 @@ tcp-request connection [{if | unless} ] See also : "tcp-request session", "tcp-request content", "stick-table" +tcp-request connection accept [ { if | unless } ] + + This is used to accept the connection. No further "tcp-request connection" + rules are evaluated. + +tcp-request connection expect-netscaler-cip layer4 + [ { if | unless } ] + + This configures the client-facing connection to receive a NetScaler Client IP + insertion protocol header before any byte is read from the socket. This is + equivalent to having the "accept-netscaler-cip" keyword on the "bind" line, + except that using the TCP rule allows the PROXY protocol to be accepted only + for certain IP address ranges using an ACL. This is convenient when multiple + layers of load balancers are passed through by traffic coming from public + hosts. + +tcp-request connection expect-proxy layer4 [ { if | unless } ] + + This configures the client-facing connection to receive a PROXY protocol + header before any byte is read from the socket. This is equivalent to having + the "accept-proxy" keyword on the "bind" line, except that using the TCP rule + allows the PROXY protocol to be accepted only for certain IP address ranges + using an ACL. This is convenient when multiple layers of load balancers are + passed through by traffic coming from public hosts. + +tcp-request connection reject [ { if | unless } ] + + This is used to reject the connection. No further "tcp-request connection" + rules are evaluated. Rejected connections do not even become a session, which + is why they are accounted separately for in the stats, as "denied + connections". They are not considered for the session rate-limit and are not + logged either. The reason is that these rules should only be used to filter + extremely high connection rates such as the ones encountered during a massive + DDoS attack. Under these extreme conditions, the simple action of logging + each event would make the system collapse and would considerably lower the + filtering capacity. If logging is absolutely desired, then "tcp-request + content" rules should be used instead, as "tcp-request session" rules will + not log either. + +tcp-request connection sc-inc-gpc(,) [ { if | unless } ] +tcp-request connection sc-inc-gpc0() [ { if | unless } ] +tcp-request connection sc-inc-gpc1() [ { if | unless } ] + + These actions increment the General Purppose Counters according to the sticky + counter designated by . Please refer to "http-request sc-inc-gpc", + "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete + description. + +tcp-request connection sc-set-gpt(,) { | } + [ { if | unless } ] +tcp-request connection sc-set-gpt0() { | } + [ { if | unless } ] + + These actions set the 32-bit unsigned General Purpose Tags according to the + sticky counter designated by . Please refer to "http-request + sc-inc-gpt" and "http-request sc-inc-gpt0" for a complete description. + +tcp-request connection set-dst [ { if | unless } ] +tcp-request connection set-dst-port [ { if | unless } ] + + These actions are used to set the destination IP/Port address to the value of + specified expression. Please refer to "http-request set-dst" and + "http-request set-dst-port" for a complete description. + +tcp-request connection set-mark [ { if | unless } ] + + This action is used to set the Netfilter/IPFW MARK in all packets sent to the + client to the value passed in on platforms which support it. Please + refer to "http-request set-mark" for a complete description. + +tcp-request connection set-src [ { if | unless } ] +tcp-request connection set-src-port [ { if | unless } ] + + These actions are used to set the source IP/Port address to the value of + specified expression. Please refer to "http-request set-src" and + "http-request set-src-port" for a complete description. + +tcp-request connection set-tos [ { if | unless } ] + + This is used to set the TOS or DSCP field value of packets sent to the client + to the value passed in on platforms which support this. Please refer to + "http-request set-tos" for a complete description. + +tcp-request connection silent-drop [ { if | unless } ] + + This stops the evaluation of the rules and makes the client-facing connection + suddenly disappear using a system-dependent way that tries to prevent the + client from being notified. Please refer to "http-request silent-drop" for a + complete description. + +tcp-request connection track-sc0 [table
] [ { if | unless } ] +tcp-request connection track-sc1 [table
] [ { if | unless } ] +tcp-request connection track-sc2 [table
] [ { if | unless } ] + + This enables tracking of sticky counters from current connection. Please + refer to "http-request track-sc0", "http-request track-sc1" and "http-request + track-sc2" for a complete description. + tcp-request content [{if | unless} ] Perform an action on a new session depending on a layer 4-7 condition @@ -12411,43 +12160,37 @@ tcp-request content [{if | unless} ] contents. There is no specific limit to the number of rules which may be inserted. - This directive is only available from named defaults sections, not anonymous - ones. Rules defined in the defaults section are evaluated before ones in the - associated proxy section. To avoid ambiguities, in this case the same - defaults section cannot be used by proxies with the frontend capability and - by proxies with the backend capability. It means a listen section cannot use - a defaults section defining such rules. - - Several types of actions are supported : - - accept : the request is accepted - - do-resolve: perform a DNS resolution - - reject : the request is rejected and the connection is closed - - capture : the specified sample expression is captured - - set-priority-class | set-priority-offset - - { track-sc0 | track-sc1 | track-sc2 } [table
] + The first keyword is the rule's action. Several types of actions are + supported: + - accept + - capture len + - do-resolve(,,[ipv4,ipv6]) + - reject - sc-inc-gpc(,) - sc-inc-gpc0() - sc-inc-gpc1() - sc-set-gpt(,) { | } - sc-set-gpt0() { | } + - send-spoe-group - set-dst - set-dst-port - set-log-level - set-mark - set-nice + - set-priority-class + - set-priority-offset - set-tos - set-var() - set-var-fmt() - - switch-mode http [ proto ] - - unset-var() - silent-drop - - send-spoe-group + - switch-mode http [ proto ] + - track-sc0 [table
] + - track-sc1 [table
] + - track-sc2 [table
] + - unset-var() - use-service - They have the same meaning as their counter-parts in "tcp-request connection" - so please refer to that section for a complete description. - For "do-resolve" action, please check the "http-request do-resolve" - configuration section. + The supported actions are described below. While there is nothing mandatory about it, it is recommended to use the track-sc0 in "tcp-request connection" rules, track-sc1 for "tcp-request @@ -12456,6 +12199,13 @@ tcp-request content [{if | unless} ] and easier to troubleshoot, but this is just a guideline and all counters may be used everywhere. + This directive is only available from named defaults sections, not anonymous + ones. Rules defined in the defaults section are evaluated before ones in the + associated proxy section. To avoid ambiguities, in this case the same + defaults section cannot be used by proxies with the frontend capability and + by proxies with the backend capability. It means a listen section cannot use + a defaults section defining such rules. + Note that the "if/unless" condition is optional. If no condition is set on the action, it is simply performed unconditionally. That can be useful for "track-sc*" actions as well as for changing the default action to a reject. @@ -12484,98 +12234,6 @@ tcp-request content [{if | unless} ] wait until the inspect delay expires when the data to be tracked is not yet available. - The "set-dst" and "set-dst-port" are used to set respectively the destination - IP and port. More information on how to use it at "http-request set-dst". - - The "set-log-level" is used to set the log level of the current session. More - information on how to use it at "http-request set-log-level". - - The "set-mark" is used to set the Netfilter MARK in all packets sent to the - client. More information on how to use it at "http-request set-mark". - - The "set-nice" is used to set the "nice" factor of the current session. More - information on how to use it at "http-request set-nice". - - The "set-tos" is used to set the TOS or DSCP field value of packets sent to - the client. More information on how to use it at "http-request set-tos". - - The "set-var" and "set-var-fmt" are used to set the contents of a variable. - The variable is declared inline. For "tcp-request session" rules, only - session-level variables can be used, without any layer7 contents. The - "set-var" action takes a regular expression while "set-var-fmt" takes a - format string. - - The name of the variable starts with an indication about - its scope. The scopes allowed are: - "proc" : the variable is shared with the whole process - "sess" : the variable is shared with the whole session - "txn" : the variable is shared with the transaction - (request and response) - "req" : the variable is shared only during request - processing - "res" : the variable is shared only during response - processing - This prefix is followed by a name. The separator is a '.'. - The name may only contain characters 'a-z', 'A-Z', '0-9', - '.' and '_'. - - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - This is the value expressed using log-format rules (see Custom - Log Format in section 8.2.4). - - The "switch-mode" is used to perform a connection upgrade. Only HTTP - upgrades are supported for now. The protocol may optionally be - specified. This action is only available for a proxy with the frontend - capability. The connection upgrade is immediately performed, following - "tcp-request content" rules are not evaluated. This upgrade method should be - preferred to the implicit one consisting to rely on the backend mode. When - used, it is possible to set HTTP directives in a frontend without any - warning. These directives will be conditionally evaluated if the HTTP upgrade - is performed. However, an HTTP backend must still be selected. It remains - unsupported to route an HTTP connection (upgraded or not) to a TCP server. - - See section 4 about Proxies for more details on HTTP upgrades. - - The "unset-var" is used to unset a variable. See above for details about - . - - The "set-priority-class" is used to set the queue priority class of the - current request. The value must be a sample expression which converts to an - integer in the range -2047..2047. Results outside this range will be - truncated. The priority class determines the order in which queued requests - are processed. Lower values have higher priority. - - The "set-priority-offset" is used to set the queue priority timestamp offset - of the current request. The value must be a sample expression which converts - to an integer in the range -524287..524287. Results outside this range will be - truncated. When a request is queued, it is ordered first by the priority - class, then by the current timestamp adjusted by the given offset in - milliseconds. Lower values have higher priority. - Note that the resulting timestamp is is only tracked with enough precision for - 524,287ms (8m44s287ms). If the request is queued long enough to where the - adjusted timestamp exceeds this value, it will be misidentified as highest - priority. Thus it is important to set "timeout queue" to a value, where when - combined with the offset, does not exceed this limit. - - The "send-spoe-group" is used to trigger sending of a group of SPOE - messages. To do so, the SPOE engine used to send messages must be defined, as - well as the SPOE group to send. Of course, the SPOE engine must refer to an - existing SPOE filter. If not engine name is provided on the SPOE filter line, - the SPOE agent name must be used. - - The SPOE engine name. - - The SPOE group name as specified in the engine configuration. - - The "use-service" is used to executes a TCP service which will reply to the - request and stop the evaluation of the rules. This service may choose to - reply by sending any valid response or it may immediately close the - connection without sending anything. Outside natives services, it is possible - to write your own services in Lua. No further "tcp-request" rules are - evaluated. - Example: tcp-request content use-service lua.deny { src -f /etc/haproxy/blacklist.lst } @@ -12652,6 +12310,150 @@ tcp-request content [{if | unless} ] See also : "tcp-request connection", "tcp-request session", "tcp-request inspect-delay", and "http-request". +tcp-request content accept [ { if | unless } ] + + This is used to accept the connection. No further "tcp-request content" + rules are evaluated. + +tcp-request content capture len + [ { if | unless } ] + + This captures sample expression from the request buffer, and + converts it to a string of at most characters. The resulting string is + stored into the next request "capture" slot, so it will possibly appear next + to some captured HTTP headers. It will then automatically appear in the logs, + and it will be possible to extract it using sample fetch rules to feed it + into headers or anything. The length should be limited given that this size + will be allocated for each capture during the whole session life. Please + check section 7.3 (Fetching samples) and "capture request header" for more + information. + +tcp-request content do-resolve(,,[ipv4,ipv6]) + + This action performs a DNS resolution of the output of and stores the + result in the variable . Please refer to "http-request do-resolve" for a + complete description. + +tcp-request content reject [ { if | unless } ] + + This is used to reject the connection. No further "tcp-request content" rules + are evaluated. + +tcp-request content sc-inc-gpc(,) [ { if | unless } ] +tcp-request content sc-inc-gpc0() [ { if | unless } ] +tcp-request content sc-inc-gpc1() [ { if | unless } ] + + These actions increment the General Purppose Counters according to the sticky + counter designated by . Please refer to "http-request sc-inc-gpc", + "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete + description. + +tcp-request content sc-set-gpt(,) { | } + [ { if | unless } ] +tcp-request content sc-set-gpt0() { | } + [ { if | unless } ] + + These actions set the 32-bit unsigned General Purpose Tags according to the + sticky counter designated by . Please refer to "http-request + sc-inc-gpt" and "http-request sc-inc-gpt0" for a complete description. + +tcp-request content send-spoe-group + [ { if | unless } ] + + Thaction is is used to trigger sending of a group of SPOE messages. Please + refer to "http-request send-spoe-group" for a complete description. + +tcp-request content set-dst [ { if | unless } ] +tcp-request content set-dst-port [ { if | unless } ] + + These actions are used to set the destination IP/Port address to the value of + specified expression. Please refer to "http-request set-dst" and + "http-request set-dst-port" for a complete description. + +tcp-request content set-log-level [ { if | unless } ] + + This action is used to set the log level of the current session. Please refer + to "http-request set-log-level". for a complete description. + +tcp-request content set-mark [ { if | unless } ] + + This action is used to set the Netfilter/IPFW MARK in all packets sent to the + client to the value passed in on platforms which support it. Please + refer to "http-request set-mark" for a complete description. + +tcp-request content set-nice [ { if | unless } ] + + This sets the "nice" factor of the current request being processed. Please + refer to "http-request set-nice" for a complete description. + +tcp-request content set-priority-class [ { if | unless } ] + + This is used to set the queue priority class of the current request. Please + refer to "http-request set-priority-class" for a complete description. + +tcp-request content set-priority-offset [ { if | unless } ] + + This is used to set the queue priority timestamp offset of the current + request. Please refer to "http-request set-priority-offset" for a complete + description. + +tcp-request content set-tos [ { if | unless } ] + + This is used to set the TOS or DSCP field value of packets sent to the client + to the value passed in on platforms which support this. Please refer to + "http-request set-tos" for a complete description. + +tcp-request content set-var() [ { if | unless } ] +tcp-request content set-var-fmt() [ { if | unless } ] + + This is used to set the contents of a variable. The variable is declared + inline. Please refer to "http-request set-var" and "http-request set-var-fmt" + for a complete description. + +tcp-request content silent-drop [ { if | unless } ] + + This stops the evaluation of the rules and makes the client-facing connection + suddenly disappear using a system-dependent way that tries to prevent the + client from being notified. Please refer to "http-request silent-drop" for a + complete description. + +tcp-request content switch-mode http [ proto ] + [ { if | unless } ] + + This action is used to perform a connection upgrade. Only HTTP upgrades are + supported for now. The protocol may optionally be specified. This action is + only available for a proxy with the frontend capability. The connection + upgrade is immediately performed, following "tcp-request content" rules are + not evaluated. This upgrade method should be preferred to the implicit one + consisting to rely on the backend mode. When used, it is possible to set HTTP + directives in a frontend without any warning. These directives will be + conditionally evaluated if the HTTP upgrade is performed. However, an HTTP + backend must still be selected. It remains unsupported to route an HTTP + connection (upgraded or not) to a TCP server. + + See section 4 about Proxies for more details on HTTP upgrades. + +tcp-request content track-sc0 [table
] [ { if | unless } ] +tcp-request content track-sc1 [table
] [ { if | unless } ] +tcp-request content track-sc2 [table
] [ { if | unless } ] + + This enables tracking of sticky counters from current connection. Please + refer to "http-request track-sc0", "http-request track-sc1" and "http-request + track-sc2" for a complete description. + +tcp-request content unset-var() [ { if | unless } ] + + This is used to unset a variable. Please refer to "http-request set-var" for + details about variables. + +tcp-request content use-service [ { if | unless } ] + + This action is used to executes a TCP service which will reply to the request + and stop the evaluation of the rules. This service may choose to reply by + sending any valid response or it may immediately close the connection without + sending anything. Outside natives services, it is possible to write your own + services in Lua. No further "tcp-request content" rules are evaluated. + tcp-request inspect-delay Set the maximum allowed time to wait for data during content inspection @@ -12739,6 +12541,31 @@ tcp-request session [{if | unless} ] accept the incoming session. There is no specific limit to the number of rules which may be inserted. + The first keyword is the rule's action. Several types of actions are + supported: + - accept + - reject + - sc-inc-gpc(,) + - sc-inc-gpc0() + - sc-inc-gpc1() + - sc-set-gpt(,) { | } + - sc-set-gpt0() { | } + - set-dst + - set-dst-port + - set-mark + - set-src + - set-src-port + - set-tos + - set-var() + - set-var-fmt() + - silent-drop + - track-sc0 [table
] + - track-sc1 [table
] + - track-sc2 [table
] + - unset-var() + + The supported actions are described below. + This directive is only available from named defaults sections, not anonymous ones. Rules defined in the defaults section are evaluated before ones in the associated proxy section. To avoid ambiguities, in this case the same @@ -12746,30 +12573,6 @@ tcp-request session [{if | unless} ] by proxies with the backend capability. It means a listen section cannot use a defaults section defining such rules. - Several types of actions are supported : - - accept : the request is accepted - - reject : the request is rejected and the connection is closed - - { track-sc0 | track-sc1 | track-sc2 } [table
] - - sc-inc-gpc(,) - - sc-inc-gpc0() - - sc-inc-gpc1() - - sc-set-gpt(,) { | } - - sc-set-gpt0() { | } - - set-mark - - set-dst - - set-dst-port - - set-src - - set-src-port - - set-tos - - set-var() - - set-var-fmt() - - unset-var() - - silent-drop - - These actions have the same meaning as their respective counter-parts in - "tcp-request connection" and "tcp-request content", so please refer to these - sections for a complete description. - Note that the "if/unless" condition is optional. If no condition is set on the action, it is simply performed unconditionally. That can be useful for "track-sc*" actions as well as for changing the default action to a reject. @@ -12803,6 +12606,88 @@ tcp-request session [{if | unless} ] See also : "tcp-request connection", "tcp-request content", "stick-table" +tcp-request session accept [ { if | unless } ] + + This is used to accept the connection. No further "tcp-request session" + rules are evaluated. + +tcp-request session reject [ { if | unless } ] + + This is used to reject the connection. No further "tcp-request session" rules + are evaluated. + +tcp-request session sc-inc-gpc(,) [ { if | unless } ] +tcp-request session sc-inc-gpc0() [ { if | unless } ] +tcp-request session sc-inc-gpc1() [ { if | unless } ] + + These actions increment the General Purppose Counters according to the sticky + counter designated by . Please refer to "http-request sc-inc-gpc", + "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete + description. + +tcp-request session sc-set-gpt(,) { | } + [ { if | unless } ] +tcp-request session sc-set-gpt0() { | } + [ { if | unless } ] + + These actions set the 32-bit unsigned General Purpose Tags according to the + sticky counter designated by . Please refer to "tcp-request connection + sc-inc-gpt" and "tcp-request connection sc-inc-gpt0" for a complete + description. + +tcp-request session set-dst [ { if | unless } ] +tcp-request session set-dst-port [ { if | unless } ] + + These actions are used to set the destination IP/Port address to the value of + specified expression. Please refer to "http-request set-dst" and + "http-request set-dst-port" for a complete description. + +tcp-request session set-mark [ { if | unless } ] + + This action is used to set the Netfilter/IPFW MARK in all packets sent to the + client to the value passed in on platforms which support it. Please + refer to "http-request set-mark" for a complete description. + +tcp-request session set-src [ { if | unless } ] +tcp-request session set-src-port [ { if | unless } ] + + These actions are used to set the source IP/Port address to the value of + specified expression. Please refer to "http-request set-src" and + "http-request set-src-port" for a complete description. + +tcp-request session set-tos [ { if | unless } ] + + This is used to set the TOS or DSCP field value of packets sent to the client + to the value passed in on platforms which support this. Please refer to + "http-request set-tos" for a complete description. + +tcp-request session set-var() [ { if | unless } ] +tcp-request session set-var-fmt() [ { if | unless } ] + + This is used to set the contents of a variable. The variable is declared + inline. Please refer to "http-request set-var" and "http-request set-var-fmt" + for a complete description. + +tcp-request session silent-drop [ { if | unless } ] + + This stops the evaluation of the rules and makes the client-facing connection + suddenly disappear using a system-dependent way that tries to prevent the + client from being notified. Please refer to "http-request silent-drop" for a + complete description. + +tcp-request session track-sc0 [table
] [ { if | unless } ] +tcp-request session track-sc1 [table
] [ { if | unless } ] +tcp-request session track-sc2 [table
] [ { if | unless } ] + + This enables tracking of sticky counters from current connection. Please + refer to "http-request track-sc0", "http-request track-sc1" and "http-request + track-sc2" for a complete description. + +tcp-request session unset-var() [ { if | unless } ] + + This is used to unset a variable. Please refer to "http-request set-var" for + details about variables. + tcp-response content [{if | unless} ] Perform an action on a session response depending on a layer 4-7 condition @@ -12827,6 +12712,28 @@ tcp-response content [{if | unless} ] contents. There is no specific limit to the number of rules which may be inserted. + The first keyword is the rule's action. Several types of actions are + supported: + - accept + - close + - reject + - sc-inc-gpc(,) + - sc-inc-gpc0() + - sc-inc-gpc1() + - sc-set-gpt(,) { | } + - sc-set-gpt0() { | } + - send-spoe-group + - set-log-level + - set-mark + - set-nice + - set-tos + - set-var() + - set-var-fmt() + - silent-drop + - unset-var() + + The supported actions are described below. + This directive is only available from named defaults sections, not anonymous ones. Rules defined in the defaults section are evaluated before ones in the associated proxy section. To avoid ambiguities, in this case the same @@ -12834,165 +12741,106 @@ tcp-response content [{if | unless} ] by proxies with the backend capability. It means a listen section cannot use a defaults section defining such rules. - Several types of actions are supported : - - accept : - accepts the response if the condition is true (when used with "if") - or false (when used with "unless"). The first such rule executed ends - the rules evaluation. - - - close : - immediately closes the connection with the server if the condition is - true (when used with "if"), or false (when used with "unless"). The - first such rule executed ends the rules evaluation. The main purpose of - this action is to force a connection to be finished between a client - and a server after an exchange when the application protocol expects - some long time outs to elapse first. The goal is to eliminate idle - connections which take significant resources on servers with certain - protocols. - - - reject : - rejects the response if the condition is true (when used with "if") - or false (when used with "unless"). The first such rule executed ends - the rules evaluation. Rejected session are immediately closed. - - - set-log-level - The "set-log-level" is used to set the log level of the current - session. More information on how to use it at "http-response - set-log-level". - - - set-mark - The "set-mark" is used to set the Netfilter MARK in all packets sent to - the client. More information on how to use it at "http-response - set-mark". - - - set-nice - The "set-nice" is used to set the "nice" factor of the current - session. More information on how to use it at "http-response - set-nice". - - - set-tos - The "set-tos" is used to set the TOS or DSCP field value of packets - sent to the client. More information on how to use it at "http-response - set-tos". - - - set-var() - Sets a variable from an expression. - - - set-var-fmt() - Sets a variable from a log format string. - - - unset-var() - Unsets a variable. - - - sc-inc-gpc(,): - This actions increments the General Purpose Counter at the index - of the array associated to the sticky counter designated by . - If an error occurs, this action silently fails and the actions - evaluation continues. is an integer between 0 and 99 and - is an integer between 0 and 2. It also silently fails if the there is - no GPC stored at this index. - This action applies only to the 'gpc' and 'gpc_rate' array data_types - (and not to the legacy 'gpc0', 'gpc1', 'gpc0_rate' nor 'gpc1_rate' - data_types). - - - sc-inc-gpc0(): - This action increments the GPC0 counter according to the sticky - counter designated by . If an error occurs, this action fails - silently and the actions evaluation continues. - - - sc-inc-gpc1(): - This action increments the GPC1 counter according to the sticky - counter designated by . If an error occurs, this action fails - silently and the actions evaluation continues. - - - sc-set-gpt(,) { | } - This action sets the 32-bit unsigned GPT at the index of the - array associated to the sticky counter designated by at the - value of /. The expected result is a boolean. - If an error occurs, this action silently fails and the actions - evaluation continues. is an integer between 0 and 99 and - is an integer between 0 and 2. It also silently fails if the there is - no GPT stored at this index. - This action applies only to the 'gpt' array data_type (and not to the - legacy 'gpt0' data-type). - - - sc-set-gpt0() { | } - This action sets the 32-bit unsigned GPT0 tag according to the sticky - counter designated by and the value of /. The - expected result is a boolean. If an error occurs, this action silently - fails and the actions evaluation continues. - - - "silent-drop" : - This stops the evaluation of the rules and makes the client-facing - connection suddenly disappear using a system-dependent way that tries - to prevent the client from being notified. The effect it then that the - client still sees an established connection while there's none on - HAProxy. The purpose is to achieve a comparable effect to "tarpit" - except that it doesn't use any local resource at all on the machine - running HAProxy. It can resist much higher loads than "tarpit", and - slow down stronger attackers. It is important to understand the impact - of using this mechanism. All stateful equipment placed between the - client and HAProxy (firewalls, proxies, load balancers) will also keep - the established connection for a long time and may suffer from this - action. On modern Linux systems running with enough privileges, the - TCP_REPAIR socket option is used to block the emission of a TCP - reset. On other systems, the socket's TTL is reduced to 1 so that the - TCP reset doesn't pass the first router, though it's still delivered to - local networks. Do not use it unless you fully understand how it works. - - - send-spoe-group - Send a group of SPOE messages. - Note that the "if/unless" condition is optional. If no condition is set on the action, it is simply performed unconditionally. That can be useful for for changing the default action to a reject. + Several types of actions are supported : + It is perfectly possible to match layer 7 contents with "tcp-response content" rules, but then it is important to ensure that a full response has been buffered, otherwise no contents will match. In order to achieve this, the best solution involves detecting the HTTP protocol during the inspection period. - The "set-var" is used to set the content of a variable. The variable is - declared inline. - - The name of the variable starts with an indication about - its scope. The scopes allowed are: - "proc" : the variable is shared with the whole process - "sess" : the variable is shared with the whole session - "txn" : the variable is shared with the transaction - (request and response) - "req" : the variable is shared only during request - processing - "res" : the variable is shared only during response - processing - This prefix is followed by a name. The separator is a '.'. - The name may only contain characters 'a-z', 'A-Z', '0-9', - '.' and '_'. - - Is a standard HAProxy expression formed by a sample-fetch - followed by some converters. - - This is the value expressed using log-format rules (see Custom - Log Format in section 8.2.4). - - The "unset-var" is used to unset a variable. See above for details about - . - - The "send-spoe-group" is used to trigger sending of a group of SPOE - messages. To do so, the SPOE engine used to send messages must be defined, as - well as the SPOE group to send. Of course, the SPOE engine must refer to an - existing SPOE filter. If not engine name is provided on the SPOE filter line, - the SPOE agent name must be used. - - The SPOE engine name. - - The SPOE group name as specified in the engine configuration. - See section 7 about ACL usage. See also : "tcp-request content", "tcp-response inspect-delay" +tcp-response content accept [ { if | unless } ] + + This is used to accept the response. No further "tcp-response content" rules + are evaluated. + +tcp-response content close [ { if | unless } ] + + This is used to immediately closes the connection with the server. No further + "tcp-response content" rules are evaluated. The main purpose of this action + is to force a connection to be finished between a client and a server after + an exchange when the application protocol expects some long time outs to + elapse first. The goal is to eliminate idle connections which take + significant resources on servers with certain protocols. + +tcp-response content reject [ { if | unless } ] + + This is used to reject the response. No further "tcp-response content" rules + are evaluated. + +tcp-response content sc-inc-gpc(,) [ { if | unless } ] +tcp-response content sc-inc-gpc0() [ { if | unless } ] +tcp-response content sc-inc-gpc1() [ { if | unless } ] + + These actions increment the General Purppose Counters according to the sticky + counter designated by . Please refer to "http-request sc-inc-gpc", + "http-request sc-inc-gpc0" and "http-request sc-inc-gpc1" for a complete + description. + +tcp-response content sc-set-gpt(,) { | } + [ { if | unless } ] +tcp-resposne content sc-set-gpt0() { | } + [ { if | unless } ] + + These actions set the 32-bit unsigned General Purpose Tags according to the + sticky counter designated by . Please refer to "http-request + sc-inc-gpt" and "http-request sc-inc-gpt0" for a complete description. + +tcp-response content send-spoe-group + [ { if | unless } ] + + Thaction is is used to trigger sending of a group of SPOE messages. Please + refer to "http-request send-spoe-group" for a complete description. + +tcp-response content set-log-level [ { if | unless } ] + + This action is used to set the log level of the current session. Please refer + to "http-request set-log-level". for a complete description. + +tcp-response content set-mark [ { if | unless } ] + + This action is used to set the Netfilter/IPFW MARK in all packets sent to the + client to the value passed in on platforms which support it. Please + refer to "http-request set-mark" for a complete description. + +tcp-response content set-nice [ { if | unless } ] + + This sets the "nice" factor of the current request being processed. Please + refer to "http-request set-nice" for a complete description. + +tcp-response content set-tos [ { if | unless } ] + + This is used to set the TOS or DSCP field value of packets sent to the client + to the value passed in on platforms which support this. Please refer to + "http-request set-tos" for a complete description. + +tcp-response content set-var() [ { if | unless } ] +tcp-response content set-var-fmt() [ { if | unless } ] + + This is used to set the contents of a variable. The variable is declared + inline. Please refer to "http-request set-var" and "http-request set-var-fmt" + for a complete description. + +tcp-response content silent-drop [ { if | unless } ] + + This stops the evaluation of the rules and makes the client-facing connection + suddenly disappear using a system-dependent way that tries to prevent the + client from being notified. Please refer to "http-request silent-drop" for a + complete description. + +tcp-response content unset-var() [ { if | unless } ] + + This is used to unset a variable. Please refer to "http-request set-var" for + details about variables. + tcp-response inspect-delay Set the maximum allowed time to wait for a response during content inspection @@ -13003,8 +12851,8 @@ tcp-response inspect-delay can be in any other unit if the number is suffixed by the unit, as explained at the top of this document. - Note: this directive is only available from named defaults sections, not - anonymous ones. + This directive is only available from named defaults sections, not anonymous + ones. Proxies inherit this value from their defaults section. See also : "tcp-response content", "tcp-request inspect-delay".