See also : "option httpchk", "http-check disable-on-404"
-http-request { allow | auth [realm <realm>] | redirect <rule> | reject |
- tarpit [deny_status <status>] | deny [deny_status <status>] |
- add-header <name> <fmt> | set-header <name> <fmt> |
- capture <sample> [ len <length> | id <id> ] |
- del-header <name> | set-nice <nice> | set-log-level <level> |
- replace-header <name> <match-regex> <replace-fmt> |
- replace-value <name> <match-regex> <replace-fmt> |
- set-method <fmt> | set-path <fmt> | set-query <fmt> |
- set-uri <fmt> | set-tos <tos> | set-mark <mark> |
- set-priority-class <expr> | set-priority-offset <expr>
- add-acl(<file name>) <key fmt> |
- del-acl(<file name>) <key fmt> |
- del-map(<file name>) <key fmt> |
- set-map(<file name>) <key fmt> <value fmt> |
- set-var(<var name>) <expr> |
- unset-var(<var name>) |
- { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
- sc-inc-gpc0(<sc-id>) |
- sc-inc-gpc1(<sc-id>) |
- sc-set-gpt0(<sc-id>) <int> |
- silent-drop |
- send-spoe-group |
- cache-use
- }
- [ { if | unless } <condition> ]
+
+http-request <action> [options...] [ { if | unless } <condition> ]
Access control for Layer 7 requests
May be used in sections: defaults | frontend | listen | backend
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. Currently supported actions include :
- - "allow" : this stops the evaluation of the rules and lets the request
- pass the check. No further "http-request" rules are evaluated.
+ The first keyword is the rule's action. The supported actions are described
+ below.
- - "deny" : this stops the evaluation of the rules and immediately rejects
- the request and emits an HTTP 403 error, or optionally the status code
- specified as an argument to "deny_status". The list of permitted status
- codes is limited to those that can be overridden by the "errorfile"
- directive. No further "http-request" rules are evaluated.
-
- - "reject" : this stops the evaluation of the rules and immediately closes
- the connection without sending any response. It acts similarly to the
- "tcp-request content reject" rules. It can be useful to force an
- immediate connection closure on HTTP/2 connections.
-
- - "tarpit" : this stops the evaluation of the rules and immediately blocks
- the request without responding for a delay specified by "timeout tarpit"
- or "timeout connect" if the former is not set. After that delay, if the
- client is still connected, an HTTP error 500 (or optionally the status
- code specified as an argument to "deny_status") is returned so that the
- client does not suspect it has been tarpitted. Logs will report the flags
- "PT". The goal of the tarpit rule is to slow down robots during an attack
- when they're limited on the number of concurrent requests. It can be very
- efficient against very dumb robots, and will significantly reduce the
- load on firewalls compared to a "deny" rule. But when facing "correctly"
- developed robots, it can make things worse by forcing haproxy and the
- front firewall to support insane number of concurrent connections. See
- also the "silent-drop" action below.
-
- - "auth" : this stops the evaluation of the rules and immediately responds
- with an HTTP 401 or 407 error code to invite the user to present a valid
- user name and password. No further "http-request" rules are evaluated. An
- optional "realm" parameter is supported, it sets the authentication realm
- that is returned with the response (typically the application's name).
+ There is no limit to the number of http-request statements per instance.
- - "redirect" : this performs an HTTP redirection based on a redirect rule.
- This is exactly the same as the "redirect" statement except that it
- inserts a redirect rule which can be processed in the middle of other
- "http-request" rules and that these rules use the "log-format" strings.
- See the "redirect" keyword for the rule's syntax.
+ It is important to know that http-request rules are processed very early in
+ the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
+ or "reqadd" rules. That way, headers added by "add-header"/"set-header" are
+ visible by almost all further ACL rules.
- - "add-header" appends an HTTP header field whose name is specified in
- <name> and whose value is defined by <fmt> which follows the log-format
- rules (see Custom Log Format in section 8.2.4). This is particularly
- useful to pass connection-specific information to the server (e.g. the
- client's SSL certificate), or to combine several headers into one. 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.
+ Using "reqadd"/"reqdel"/"reqrep" to manipulate request headers is discouraged
+ in newer versions (>= 1.5). But if you need to use regular expression to
+ delete headers, you can still use "reqdel". Also please use
+ "http-request deny/allow/tarpit" instead of "reqdeny"/"reqpass"/"reqtarpit".
- - "set-header" 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. Note that the new value is computed before the removal so
- it is possible to concatenate a value to an existing header.
+ Example:
+ acl nagios src 192.168.129.3
+ acl local_net src 192.168.0.0/16
+ acl auth_ok http_auth(L1)
- - "del-header" removes all HTTP header fields whose name is specified in
- <name>.
+ http-request allow if nagios
+ http-request allow if local_net auth_ok
+ http-request auth realm Gimme if local_net auth_ok
+ http-request deny
- - "replace-header" matches the regular expression in all occurrences of
- header field <name> according to <match-regex>, and replaces them with
- the <replace-fmt> argument. Format characters are allowed in replace-fmt
- and work like in <fmt> arguments in "add-header". The match is only
- case-sensitive. It is important to understand that this action only
- considers whole header lines, regardless of the number of values they
- may contain. This usage is suited to headers naturally containing commas
- in their value, such as If-Modified-Since and so on.
+ Example:
+ acl key req.hdr(X-Add-Acl-Key) -m found
+ acl add path /addacl
+ acl del path /delacl
- Example:
+ acl myhost hdr(Host) -f myhost.lst
- http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
+ http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
+ http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
- applied to:
+ Example:
+ acl value req.hdr(X-Value) -m found
+ acl setmap path /setmap
+ acl delmap path /delmap
- Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
+ use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
- outputs:
+ http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
+ http-request del-map(map.lst) %[src] if delmap
- Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
+ See also : "stats http-request", section 3.4 about userlists and section 7
+ about ACL usage.
- assuming the backend IP is 192.168.1.20
+http-request add-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
- - "replace-value" works like "replace-header" except that it matches the
- regex against every comma-delimited value of the header field <name>
- instead of the entire header. This is suited for all headers which are
- allowed to carry more than one value. An example could be the Accept
- header.
+ This is used to add a new entry into an ACL. The ACL must be loaded from a
+ file (even a dummy empty file). The file name of the ACL to be updated is
+ passed between parentheses. It takes one argument: <key fmt>, which follows
+ log-format rules, to collect content of the new entry. It performs a lookup
+ in the ACL before insertion, to avoid duplicated (or more) values. This
+ lookup is done by a linear search and can be expensive with large lists!
+ It is the equivalent of the "add acl" command from the stats socket, but can
+ be triggered by an HTTP request.
- Example:
+http-request add-header <name> <fmt> [ { if | unless } <condition> ]
- http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
+ This appends an HTTP header field whose name is specified in <name> and
+ whose value is defined by <fmt> which follows the log-format rules (see
+ Custom Log Format in section 8.2.4). This is particularly useful to pass
+ connection-specific information to the server (e.g. the client's SSL
+ certificate), or to combine several headers into one. 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.
- applied to:
+http-request allow [ { if | unless } <condition> ]
- X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
+ This stops the evaluation of the rules and lets the request pass the check.
+ No further "http-request" rules are evaluated.
- outputs:
- X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
-
- - "set-method" rewrites the request method with the result of the
- evaluation of format string <fmt>. There should be very few valid reasons
- for having to do so as this is more likely to break something than to fix
- it.
-
- - "set-path" rewrites the request path with the result of the evaluation of
- format string <fmt>. The query string, if any, is left intact. If a
- scheme and authority is found before the path, they are left intact as
- well. If the request doesn't have a path ("*"), this one is replaced with
- the format. This can be used to prepend a directory component in front of
- a path for example. See also "set-query" and "set-uri".
-
- Example :
- # prepend the host name before the path
- http-request set-path /%[hdr(host)]%[path]
-
- - "set-query" rewrites the request's query string which appears after the
- first question mark ("?") with the result of the evaluation of format
- string <fmt>. The part prior to the question mark is left intact. If the
- request doesn't contain a question mark and the new value is not empty,
- then one is added at the end of the URI, followed by the new value. If
- a question mark was present, it will never be removed even if the value
- is empty. This can be used to add or remove parameters from the query
- string. See also "set-query" and "set-uri".
-
- Example :
- # replace "%3D" with "=" in the query string
- http-request set-query %[query,regsub(%3D,=,g)]
-
- - "set-uri" rewrites the request URI with the result of the evaluation of
- format string <fmt>. The scheme, authority, path and query string are all
- replaced at once. This can be used to rewrite hosts in front of proxies,
- or to perform complex modifications to the URI such as moving parts
- between the path and the query string. See also "set-path" and
- "set-query".
+http-request auth [realm <realm>] [ { if | unless } <condition> ]
- - "set-nice" sets the "nice" factor of the current request being processed.
- It only has effect against the other requests being processed at the same
- time. The default value is 0, unless altered by the "nice" setting on the
- "bind" line. The accepted range is -1024..1024. The higher the value, the
- nicest the request will be. Lower values will make the request more
- important than other ones. This can be useful to improve the speed of
- some requests, or lower the priority of non-important requests. Using
- this setting without prior experimentation can cause some major slowdown.
+ This stops the evaluation of the rules and immediately responds with an
+ HTTP 401 or 407 error code to invite the user to present a valid user name
+ and password. No further "http-request" rules are evaluated. An optional
+ "realm" parameter is supported, it sets the authentication realm that is
+ returned with the response (typically the application's name).
- - "set-log-level" is used to change the log level of the current request
- when a certain condition is met. Valid levels are the 8 syslog levels
- (see the "log" keyword) plus the special level "silent" which disables
- logging for this request. This rule is not final so the last matching
- rule wins. This rule can be useful to disable health checks coming from
- another equipment.
+ Example:
+ acl auth_ok http_auth_group(L1) G1
+ http-request auth unless auth_ok
- - "set-tos" is used to set the TOS or DSCP field value of packets sent to
- the client to the value passed in <tos> 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.
+http-request cache-use [ { if | unless } <condition> ]
- - "set-mark" is used to set the Netfilter MARK on all packets sent to the
- client to the value passed in <mark> on platforms which support it. This
- value is an unsigned 32 bit value which can be matched by netfilter and
- by the routing table. 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.
+ See section 10.2 about cache setup.
- - "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.
-
- - "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.
+http-request capture <sample> [ len <length> | id <id> ]
+ [ { if | unless } <condition> ]
- - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded
- from a file (even a dummy empty file). The file name of the ACL to be
- updated is passed between parentheses. It takes one argument: <key fmt>,
- which follows log-format rules, to collect content of the new entry. It
- performs a lookup in the ACL before insertion, to avoid duplicated (or
- more) values. This lookup is done by a linear search and can be expensive
- with large lists! It is the equivalent of the "add acl" command from the
- stats socket, but can be triggered by an HTTP request.
+ This captures sample expression <sample> from the request buffer, and
+ converts it to a string of at most <len> 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.
- - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded
- from a file (even a dummy empty file). The file name of the ACL to be
- updated is passed between parentheses. It takes one argument: <key fmt>,
- which follows log-format rules, to collect content of the entry to delete.
- It is the equivalent of the "del acl" command from the stats socket, but
- can be triggered by an HTTP request.
+ If the keyword "id" is used instead of "len", the action tries to store the
+ captured string in a previously declared capture slot. This is useful to run
+ captures in backends. The slot id can be declared by a previous directive
+ "http-request capture" or with the "declare capture" keyword. If the slot
+ <id> doesn't exist, then HAProxy fails parsing the configuration to prevent
+ unexpected behavior at run time.
- - "del-map" is used to delete an entry from a MAP. The MAP must be loaded
- from a file (even a dummy empty file). The file name of the MAP to be
- updated is passed between parentheses. It takes one argument: <key fmt>,
- which follows log-format rules, to collect content of the entry to delete.
- It takes one argument: "file name" It is the equivalent of the "del map"
- command from the stats socket, but can be triggered by an HTTP request.
+http-request del-acl(<file-name>) <key fmt> [ { if | unless } <condition> ]
- - "set-map" is used to add a new entry into a MAP. The MAP must be loaded
- from a file (even a dummy empty file). The file name of the MAP to be
- updated is passed between parentheses. It takes 2 arguments: <key fmt>,
- which follows log-format rules, used to collect MAP key, and <value fmt>,
- which follows log-format rules, used to collect content for the new entry.
- It performs a lookup in the MAP before insertion, to avoid duplicated (or
- more) values. This lookup is done by a linear search and can be expensive
- with large lists! It is the equivalent of the "set map" command from the
- stats socket, but can be triggered by an HTTP request.
-
- - capture <sample> [ len <length> | id <id> ] :
- captures sample expression <sample> from the request buffer, and converts
- it to a string of at most <len> 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.
-
- If the keyword "id" is used instead of "len", the action tries to store
- the captured string in a previously declared capture slot. This is useful
- to run captures in backends. The slot id can be declared by a previous
- directive "http-request capture" or with the "declare capture" keyword.
- If the slot <id> doesn't exist, then HAProxy fails parsing the
- configuration to prevent unexpected behavior at run time.
+ This is used to delete an entry from an ACL. The ACL must be loaded from a
+ file (even a dummy empty file). The file name of the ACL to be updated is
+ passed between parentheses. It takes one argument: <key fmt>, which follows
+ log-format rules, to collect content of the entry to delete.
+ It is the equivalent of the "del acl" command from the stats socket, but can
+ be triggered by an HTTP request.
- - cache-use <name> :
- See section 10.2 about cache setup.
+http-request del-header <name> [ { if | unless } <condition> ]
- - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] :
- enables tracking of sticky counters from current request. 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_STCKTR-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 :
- <key> 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.
-
- <table> 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. As an exception, connection counters and request counters
- are systematically updated so that they reflect useful information.
-
- 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.
+ This removes all HTTP header fields whose name is specified in <name>.
- - sc-set-gpt0(<sc-id>) <int> :
- This action sets the GPT0 tag according to the sticky counter designated
- by <sc-id> and the value of <int>. The expected result is a boolean. If
- an error occurs, this action silently fails and the actions evaluation
- continues.
+http-request del-map(<file-name>) <key fmt> [ { if | unless } <condition> ]
- - sc-inc-gpc0(<sc-id>):
- This action increments the GPC0 counter according with the sticky counter
- designated by <sc-id>. If an error occurs, this action silently fails and
- the actions evaluation continues.
+ This is used to delete an entry from a MAP. The MAP must be loaded from a
+ file (even a dummy empty file). The file name of the MAP to be updated is
+ passed between parentheses. It takes one argument: <key fmt>, which follows
+ log-format rules, to collect content of the entry to delete.
+ It takes one argument: "file name" It is the equivalent of the "del map"
+ command from the stats socket, but can be triggered by an HTTP request.
- - sc-inc-gpc1(<sc-id>):
- Same as "sc-inc-gpc0" action above but for GPC1 counter.
+http-request deny [deny_status <status>] [ { if | unless } <condition> ]
- - set-var(<var-name>) <expr> :
- Is used to set the contents of a variable. The variable is declared
- inline.
+ This stops the evaluation of the rules and immediately rejects the request
+ and emits an HTTP 403 error, or optionally the status code specified as an
+ argument to "deny_status". The list of permitted status codes is limited to
+ those that can be overridden by the "errorfile" directive.
+ No further "http-request" rules are evaluated.
- <var-name> 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-request redirect <rule> [ { if | unless } <condition> ]
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ This performs an HTTP redirection based on a redirect rule. This is exactly
+ the same as the "redirect" statement except that it inserts a redirect rule
+ which can be processed in the middle of other "http-request" rules and that
+ these rules use the "log-format" strings. See the "redirect" keyword for the
+ rule's syntax.
- Example:
+http-request reject [ { if | unless } <condition> ]
- http-request set-var(req.my_var) req.fhdr(user-agent),lower
+ This stops the evaluation of the rules and immediately closes the connection
+ without sending any response. It acts similarly to the
+ "tcp-request content reject" rules. It can be useful to force an immediate
+ connection closure on HTTP/2 connections.
- - unset-var(<var-name>) :
- Is used to unset a variable. See above for details about <var-name>.
+http-request replace-header <name> <match-regex> <replace-fmt>
+ [ { if | unless } <condition> ]
- Example:
+ This matches the regular expression in all occurrences of header field
+ <name> according to <match-regex>, and replaces them with the
+ <replace-fmt> argument. Format characters are allowed in replace-fmt and
+ work like in <fmt> arguments in "http-request add-header". The match is
+ only case-sensitive. It is important to understand that this action only
+ considers whole header lines, regardless of the number of values they may
+ contain. This usage is suited to headers naturally containing commas in
+ their value, such as If-Modified-Since and so on.
- http-request unset-var(req.my_var)
+ Example:
+ http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2
- - set-src <expr> :
- Is used to set the source IP address to the value of specified
- expression. Useful when a proxy in front of HAProxy rewrites source IP,
- but provides the correct IP in a HTTP header; or you want to mask
- source IP for privacy.
+ # applied to:
+ Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT;
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ # outputs:
+ Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT;
- Example:
+ # assuming the backend IP is 192.168.1.20
- http-request set-src hdr(x-forwarded-for)
- http-request set-src src,ipmask(24)
+http-request replace-value <name> <match-regex> <replace-fmt>
+ [ { if | unless } <condition> ]
- 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.
+ This works like "replace-header" except that it matches the regex against
+ every comma-delimited value of the header field <name> instead of the
+ entire header. This is suited for all headers which are allowed to carry
+ more than one value. An example could be the Accept header.
- - set-src-port <expr> :
- Is used to set the source port address to the value of specified
- expression.
+ Example:
+ http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ # applied to:
+ X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37
- Example:
+ # outputs:
+ X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37
- http-request set-src-port hdr(x-port)
- http-request set-src-port int(4000)
+http-request sc-inc-gpc0(<sc-id>) [ { if | unless } <condition> ]
+http-request sc-inc-gpc1(<sc-id>) [ { if | unless } <condition> ]
- 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.
+ This actions increments the GPC0 or GPC1 counter according with the sticky
+ counter designated by <sc-id>. If an error occurs, this action silently fails
+ and the actions evaluation continues.
- - set-dst <expr> :
- Is used to set the destination IP address to the value of specified
- expression. Useful when a proxy in front of HAProxy rewrites destination
- IP, but provides the correct IP in a HTTP header; or you want to mask
- the IP for privacy. If you want to connect to the new address/port, use
- '0.0.0.0:0' as a server address in the backend.
+http-request sc-set-gpt0(<sc-id>) <int> [ { if | unless } <condition> ]
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ This action sets the GPT0 tag according to the sticky counter designated by
+ <sc-id> and the value of <int>. The expected result is a boolean. If an error
+ occurs, this action silently fails and the actions evaluation continues.
- Example:
+http-request set-dst <expr> [ { if | unless } <condition> ]
- http-request set-dst hdr(x-dst)
- http-request set-dst dst,ipmask(24)
+ This is used to set the destination IP address to the value of specified
+ expression. Useful when a proxy in front of HAProxy rewrites destination IP,
+ but provides the correct IP in a HTTP header; or you want to mask the IP for
+ privacy. If you want to connect to the new address/port, use '0.0.0.0:0' as a
+ server address in the backend.
- 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.
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters.
- - set-dst-port <expr> :
- 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.
+ Example:
+ http-request set-dst hdr(x-dst)
+ http-request set-dst dst,ipmask(24)
- <expr> Is a standard HAProxy expression formed by a sample-fetch
- followed by some converters.
+ 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.
- Example:
+http-request set-dst-port <expr> [ { if | unless } <condition> ]
- http-request set-dst-port hdr(x-port)
- http-request set-dst-port int(4000)
+ This 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.
- 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.
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch
+ followed by some converters.
- - "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.
+ Example:
+ http-request set-dst-port hdr(x-port)
+ http-request 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.
- - "wait-for-handshake" : this will delay the processing of the request
- until the SSL handshake happened. This is mostly useful to delay
- processing early data until we're sure they are valid.
+http-request set-header <name> <fmt> [ { if | unless } <condition> ]
- - send-spoe-group <engine-name> <group-name> :
- This action 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.
+ This does the same as "http-request 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. Note that the new value is computed before the removal so it
+ is possible to concatenate a value to an existing header.
- <engine-name> The SPOE engine name.
+ Example:
+ http-request set-header X-Haproxy-Current-Date %T
+ http-request set-header X-SSL %[ssl_fc]
+ http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
+ http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
+ http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
+ http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
+ http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
+ http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
+ http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
- <group-name> The SPOE group name as specified in the engine
- configuration.
+http-request set-log-level <level> [ { if | unless } <condition> ]
+
+ This is used to change the log level of the current request when a certain
+ condition is met. Valid levels are the 8 syslog levels (see the "log"
+ keyword) plus the special level "silent" which disables logging for this
+ request. This rule is not final so the last matching rule wins. This rule
+ can be useful to disable health checks coming from another equipment.
+
+http-request set-map(<file-name>) <key fmt> <value fmt>
+ [ { if | unless } <condition> ]
+
+ This is used to add a new entry into a MAP. The MAP must be loaded from a
+ file (even a dummy empty file). The file name of the MAP to be updated is
+ passed between parentheses. It takes 2 arguments: <key fmt>, which follows
+ log-format rules, used to collect MAP key, and <value fmt>, which follows
+ log-format rules, used to collect content for the new entry.
+ It performs a lookup in the MAP before insertion, to avoid duplicated (or
+ more) values. This lookup is done by a linear search and can be expensive
+ with large lists! It is the equivalent of the "set map" command from the
+ stats socket, but can be triggered by an HTTP request.
+
+http-request set-mark <mark> [ { if | unless } <condition> ]
+
+ This is used to set the Netfilter MARK on all packets sent to the client to
+ the value passed in <mark> on platforms which support it. This value is an
+ unsigned 32 bit value which can be matched by netfilter and by the routing
+ table. 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.
+
+http-request set-method <fmt> [ { if | unless } <condition> ]
+
+ This rewrites the request method with the result of the evaluation of format
+ string <fmt>. There should be very few valid reasons for having to do so as
+ this is more likely to break something than to fix it.
+
+http-request set-nice <nice> [ { if | unless } <condition> ]
+
+ This sets the "nice" factor of the current request being processed. It only
+ has effect against the other requests being processed at the same time.
+ The default value is 0, unless altered by the "nice" setting on the "bind"
+ line. The accepted range is -1024..1024. The higher the value, the nicest
+ the request will be. Lower values will make the request more important than
+ other ones. This can be useful to improve the speed of some requests, or
+ lower the priority of non-important requests. Using this setting without
+ prior experimentation can cause some major slowdown.
+
+http-request set-path <fmt> [ { if | unless } <condition> ]
+
+ This rewrites the request path with the result of the evaluation of format
+ string <fmt>. The query string, if any, is left intact. If a scheme and
+ authority is found before the path, they are left intact as well. If the
+ request doesn't have a path ("*"), this one is replaced with the format.
+ This can be used to prepend a directory component in front of a path for
+ example. See also "http-request set-query" and "http-request set-uri".
+
+ Example :
+ # prepend the host name before the path
+ http-request set-path /%[hdr(host)]%[path]
+
+http-request set-priority-class <expr> [ { if | unless } <condition> ]
+
+ This 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.
+
+http-request set-priority-offset <expr> [ { if | unless } <condition> ]
+
+ This 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.
- There is no limit to the number of http-request statements per instance.
+http-request set-query <fmt> [ { if | unless } <condition> ]
- It is important to know that http-request rules are processed very early in
- the HTTP processing, just after "block" rules and before "reqdel" or "reqrep"
- or "reqadd" rules. That way, headers added by "add-header"/"set-header" are
- visible by almost all further ACL rules.
+ This rewrites the request's query string which appears after the first
+ question mark ("?") with the result of the evaluation of format string <fmt>.
+ The part prior to the question mark is left intact. If the request doesn't
+ contain a question mark and the new value is not empty, then one is added at
+ the end of the URI, followed by the new value. If a question mark was
+ present, it will never be removed even if the value is empty. This can be
+ used to add or remove parameters from the query string.
- Using "reqadd"/"reqdel"/"reqrep" to manipulate request headers is discouraged
- in newer versions (>= 1.5). But if you need to use regular expression to
- delete headers, you can still use "reqdel". Also please use
- "http-request deny/allow/tarpit" instead of "reqdeny"/"reqpass"/"reqtarpit".
+ See also "http-request set-query" and "http-request set-uri".
Example:
- acl nagios src 192.168.129.3
- acl local_net src 192.168.0.0/16
- acl auth_ok http_auth(L1)
+ # replace "%3D" with "=" in the query string
+ http-request set-query %[query,regsub(%3D,=,g)]
- http-request allow if nagios
- http-request allow if local_net auth_ok
- http-request auth realm Gimme if local_net auth_ok
- http-request deny
+http-request set-src <expr> [ { if | unless } <condition> ]
+ This is used to set the source IP address to the value of specified
+ expression. Useful when a proxy in front of HAProxy rewrites source IP, but
+ provides the correct IP in a HTTP header; or you want to mask source IP for
+ privacy.
+
+ Arguments :
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters.
Example:
- acl auth_ok http_auth_group(L1) G1
- http-request auth unless auth_ok
+ http-request set-src hdr(x-forwarded-for)
+ http-request 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.
+
+http-request set-src-port <expr> [ { if | unless } <condition> ]
+
+ This is used to set the source port address to the value of specified
+ expression.
+
+ Arguments:
+ <expr> Is a standard HAProxy expression formed by a sample-fetch followed
+ by some converters.
Example:
- http-request set-header X-Haproxy-Current-Date %T
- http-request set-header X-SSL %[ssl_fc]
- http-request set-header X-SSL-Session_ID %[ssl_fc_session_id,hex]
- http-request set-header X-SSL-Client-Verify %[ssl_c_verify]
- http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn]
- http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)]
- http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn]
- http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore]
- http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter]
+ http-request set-src-port hdr(x-port)
+ http-request 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.
+
+http-request set-tos <tos> [ { if | unless } <condition> ]
+
+ This is used to set the TOS or DSCP field value of packets sent to the client
+ to the value passed in <tos> 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.
+
+http-request set-uri <fmt> [ { if | unless } <condition> ]
+
+ This rewrites the request URI with the result of the evaluation of format
+ string <fmt>. The scheme, authority, path and query string are all replaced
+ at once. This can be used to rewrite hosts in front of proxies, or to
+ perform complex modifications to the URI such as moving parts between the
+ path and the query string.
+ See also "http-request set-path" and "http-request set-query".
+
+http-request set-var(<var-name>) <expr> [ { if | unless } <condition> ]
+
+ This is used to set the contents of a variable. The variable is declared
+ inline.
+
+ Arguments:
+ <var-name> 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 '_'.
+
+ <expr> Is a standard HAProxy expression formed by a sample-fetch
+ followed by some converters.
Example:
- acl key req.hdr(X-Add-Acl-Key) -m found
- acl add path /addacl
- acl del path /delacl
+ http-request set-var(req.my_var) req.fhdr(user-agent),lower
- acl myhost hdr(Host) -f myhost.lst
+http-request send-spoe-group <engine-name> <group-name>
+ [ { if | unless } <condition> ]
- http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add
- http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del
+ This action 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.
+
+ Arguments:
+ <engine-name> The SPOE engine name.
+
+ <group-name> The SPOE group name as specified in the engine
+ configuration.
+
+http-request silent-drop [ { if | unless } <condition> ]
+
+ 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.
+
+http-request tarpit [deny_status <status>] [ { if | unless } <condition> ]
+
+ This stops the evaluation of the rules and immediately blocks the request
+ without responding for a delay specified by "timeout tarpit" or
+ "timeout connect" if the former is not set. After that delay, if the client
+ is still connected, an HTTP error 500 (or optionally the status code
+ specified as an argument to "deny_status") is returned so that the client
+ does not suspect it has been tarpitted. Logs will report the flags "PT".
+ The goal of the tarpit rule is to slow down robots during an attack when
+ they're limited on the number of concurrent requests. It can be very
+ efficient against very dumb robots, and will significantly reduce the load
+ on firewalls compared to a "deny" rule. But when facing "correctly"
+ developed robots, it can make things worse by forcing haproxy and the front
+ firewall to support insane number of concurrent connections.
+ See also the "silent-drop" action.
+
+http-request track-sc0 <key> [table <table>] [ { if | unless } <condition> ]
+http-request track-sc1 <key> [table <table>] [ { if | unless } <condition> ]
+http-request track-sc2 <key> [table <table>] [ { if | unless } <condition> ]
+
+ This enables tracking of sticky counters from current request. 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_STCKTR-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.
+
+ Arguments :
+ <key> 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.
+
+ <table> 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. As an exception, connection
+ counters and request counters are systematically updated so that they reflect
+ useful information.
+
+ 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.
+
+http-request unset-var(<var-name>) [ { if | unless } <condition> ]
+
+ This is used to unset a variable. See above for details about <var-name>.
Example:
- acl value req.hdr(X-Value) -m found
- acl setmap path /setmap
- acl delmap path /delmap
+ http-request unset-var(req.my_var)
- use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found }
+http-request wait-for-handshake [ { if | unless } <condition> ]
- http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value
- http-request del-map(map.lst) %[src] if delmap
+ This will delay the processing of the request until the SSL handshake
+ happened. This is mostly useful to delay processing early data until we're
+ sure they are valid.
- See also : "stats http-request", section 3.4 about userlists and section 7
- about ACL usage.
-http-response { allow | deny | add-header <name> <fmt> | set-nice <nice> |
- capture <sample> id <id> | redirect <rule> |
- set-header <name> <fmt> | del-header <name> |
- replace-header <name> <regex-match> <replace-fmt> |
- replace-value <name> <regex-match> <replace-fmt> |
- set-status <status> [reason <str>] |
- set-log-level <level> | set-mark <mark> | set-tos <tos> |
- add-acl(<file name>) <key fmt> |
- del-acl(<file name>) <key fmt> |
- del-map(<file name>) <key fmt> |
- set-map(<file name>) <key fmt> <value fmt> |
- set-var(<var-name>) <expr> |
- unset-var(<var-name>) |
- { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] |
- sc-inc-gpc0(<sc-id>) |
- sc-inc-gpc1(<sc-id>) |
- sc-set-gpt0(<sc-id>) <int> |
- silent-drop |
- send-spoe-group |
- cache-store
- }
- [ { if | unless } <condition> ]
Access control for Layer 7 responses
May be used in sections: defaults | frontend | listen | backend
projects / thirdparty / haproxy.git / commitdiff
