mirrors/haproxy
1
0
Fork 0
mirror of https://git.haproxy.org/git/haproxy.git/ synced 2025-08-06 15:17:01 +02:00
Code Issues Projects Releases Wiki Activity

DOC: config: uniformize the naming and description of custom log format args

Browse Source 
A significant number of actions now take arguments that are evaluated as
log-format expressions. Some of them are called "fmt", others "string".
The description of the argument sometimes just says "the log-format
string" or "log format" or "custom log format" etc. Most of them do not
mention the section to visit, and section 8.2 speaking about log-format
is very centric on logs usage (the primary use case), making all of this
very confusing for newcomers.

Since section 8.2.6 is titled "Custom log format" and describes the syntax
to be used with the "log-format" (and other) directives, let's call this
"Custom log format" everywhere and mention section 8.2.6. When the field
was called "string", it was also renamed to "fmt".

It doesn't seem worth backporting this, unless it applies fine.
This commit is contained in:
Willy Tarreau 2024-05-24 16:18:20 +02:00
parent 474cbcf842
commit c02cefce23
1 changed files with 122 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

233
doc/configuration.txt
View File

@ -2326,7 +2326,7 @@ set-var-fmt <var-name> <fmt>
are only those using internal data, typically 'int(value)' or 'str(value)'. are only those using internal data, typically 'int(value)' or 'str(value)'.
It is possible to reference previously allocated variables as well. These It is possible to reference previously allocated variables as well. These
variables will then be readable (and modifiable) from the regular rule sets. variables will then be readable (and modifiable) from the regular rule sets.
Please see section 8.2.6 for details on the custom log-format syntax. Please see section 8.2.6 for details on the Custom log format syntax.
Example: Example:
global global
@ -6823,7 +6823,7 @@ email-alert to <emailaddr>
"email-alert myhostname", section 3.6 about mailers. "email-alert myhostname", section 3.6 about mailers.
error-log-format <string> error-log-format <fmt>
Specifies the log format string to use in case of connection error on the frontend side. Specifies the log format string to use in case of connection error on the frontend side.
May be used in the following contexts: tcp, http May be used in the following contexts: tcp, http
@ -7347,12 +7347,13 @@ http-check expect [min-recv <int>] [comment <msg>]
on-success <fmt> is optional and can be used to customize the on-success <fmt> is optional and can be used to customize the
informational message reported in logs if the expect informational message reported in logs if the expect
rule is successfully evaluated and if it is the last rule rule is successfully evaluated and if it is the last rule
in the tcp-check ruleset. <fmt> is a log-format string. in the tcp-check ruleset. <fmt> is a Custom log format
string (see section 8.2.6).
on-error <fmt> is optional and can be used to customize the on-error <fmt> is optional and can be used to customize the
informational message reported in logs if an error informational message reported in logs if an error
occurred during the expect rule evaluation. <fmt> is a occurred during the expect rule evaluation. <fmt> is a
log-format string. Custom log format string (see section 8.2.6).
<match> is a keyword indicating how to look for a specific pattern in the <match> is a keyword indicating how to look for a specific pattern in the
response. The keyword may be one of "status", "rstatus", "hdr", response. The keyword may be one of "status", "rstatus", "hdr",
@ -7398,17 +7399,18 @@ http-check expect [min-recv <int>] [comment <msg>]
match), "end" (suffix match), "sub" (substring match) or match), "end" (suffix match), "sub" (substring match) or
"reg" (regex match). If not specified, exact matching "reg" (regex match). If not specified, exact matching
method is used. If the "name-lf" parameter is used, method is used. If the "name-lf" parameter is used,
<name> is evaluated as a log-format string. If "value-lf" <name> is evaluated as a Custom log format string (see
parameter is used, <value> is evaluated as a log-format section 8.2.6). If "value-lf" parameter is used, <value>
string. These parameters cannot be used with the regex is evaluated as a log-format string. These parameters
matching method. Finally, the header value is considered cannot be used with the regex matching method. Finally,
as comma-separated list. Note that matchings are case the header value is considered as comma-separated
insensitive on the header names. list. Note that matchings are case insensitive on the
header names.
fhdr { name | name-lf } [ -m <meth> ] <name> fhdr { name | name-lf } [ -m <meth> ] <name>
[ { value | value-lf } [ -m <meth> ] <value> : [ { value | value-lf } [ -m <meth> ] <value> :
test the specified full header pattern on the HTTP test the specified full header pattern on the HTTP
response headers. It does exactly the same than "hdr" response headers. It does exactly the same as the "hdr"
keyword, except the full header value is tested, commas keyword, except the full header value is tested, commas
are not considered as delimiters. are not considered as delimiters.
@ -7431,12 +7433,13 @@ http-check expect [min-recv <int>] [comment <msg>]
of a dynamic page, or to detect a failure when a specific of a dynamic page, or to detect a failure when a specific
error appears on the check page (e.g. a stack trace). error appears on the check page (e.g. a stack trace).
string-lf <fmt> : test a log-format string match in the HTTP response body. string-lf <fmt> : test a Custom log format string (see section 8.2.6) match
A health check response will be considered valid if the in the HTTP response body. A health check response will
response's body contains the string resulting of the be considered valid if the response's body contains the
evaluation of <fmt>, which follows the log-format rules. string resulting of the evaluation of <fmt>, which
If prefixed with "!", then the response will be follows the log-format rules. If prefixed with "!", then
considered invalid if the body contains the string. the response will be considered invalid if the body
contains the string.
It is important to note that the responses will be limited to a certain size It is important to note that the responses will be limited to a certain size
defined by the global "tune.bufsize" option, which defaults to 16384 bytes. defined by the global "tune.bufsize" option, which defaults to 16384 bytes.
@ -7502,9 +7505,10 @@ http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
other URI. Query strings are permitted. other URI. Query strings are permitted.
uri-lf <fmt> is optional and set the URI referenced in the HTTP requests uri-lf <fmt> is optional and set the URI referenced in the HTTP requests
using the log-format string <fmt>. It defaults to "/" which using the Custom log format <fmt> (see section 8.2.6). It
is accessible by default on almost any server, but may be defaults to "/" which is accessible by default on almost any
changed to any other URI. Query strings are permitted. server, but may be changed to any other URI. Query strings
are permitted.
ver <version> is the optional HTTP version string. It defaults to ver <version> is the optional HTTP version string. It defaults to
"HTTP/1.0" but some servers might behave incorrectly in HTTP "HTTP/1.0" but some servers might behave incorrectly in HTTP
@ -7514,16 +7518,16 @@ http-check send [meth <method>] [{ uri <uri> | uri-lf <fmt> }>] [ver <version>]
hdr <name> <fmt> adds the HTTP header field whose name is specified in hdr <name> <fmt> adds the HTTP header field whose name is specified in
<name> and whose value is defined by <fmt>, which follows <name> and whose value is defined by <fmt>, which follows
to the log-format rules. the Custom log format rules described in section 8.2.6.
body <string> add the body defined by <string> to the request sent during body <string> add the body defined by <string> to the request sent during
HTTP health checks. If defined, the "Content-Length" header HTTP health checks. If defined, the "Content-Length" header
is thus automatically added to the request. is thus automatically added to the request.
body-lf <fmt> add the body defined by the log-format string <fmt> to the body-lf <fmt> add the body defined by the Custom log format <fmt> (see
request sent during HTTP health checks. If defined, the section 8.2.6) to the request sent during HTTP health
"Content-Length" header is thus automatically added to the checks. If defined, the "Content-Length" header is thus
request. automatically added to the request.
In addition to the request line defined by the "option httpchk" directive, In addition to the request line defined by the "option httpchk" directive,
this one is the valid way to add some headers and optionally a body to the this one is the valid way to add some headers and optionally a body to the
@ -7632,7 +7636,7 @@ http-check set-var-fmt(<var-name>[,<cond>...]) <fmt>
<expr> Is a sample-fetch expression potentially followed by converters. <expr> Is a sample-fetch expression potentially followed by converters.
<fmt> This is the value expressed using log-format rules (see Custom <fmt> This is the value expressed using Custom log format (see Custom
Log Format in section 8.2.6). Log Format in section 8.2.6).
Examples : Examples :
@ -7715,7 +7719,7 @@ http-error status <code> [content-type <type>]
file is not empty, its content-type must be set as file is not empty, its content-type must be set as
argument to "content-type", otherwise, any argument to "content-type", otherwise, any
"content-type" argument is ignored. <file> is "content-type" argument is ignored. <file> is
evaluated as a log-format string. evaluated as a Custom log format (see section 8.2.6).
lf-string <str> specifies the log-format string to use as response lf-string <str> specifies the log-format string to use as response
payload. The content-type must always be set as payload. The content-type must always be set as
@ -7723,8 +7727,9 @@ http-error status <code> [content-type <type>]
hdr <name> <fmt> adds to the response the HTTP header field whose name hdr <name> <fmt> adds to the response the HTTP header field whose name
is specified in <name> and whose value is defined by is specified in <name> and whose value is defined by
<fmt>, which follows to the log-format rules. <fmt>, which follows the Custom log format rules (see
This parameter is ignored if an errorfile is used. section 8.2.6). This parameter is ignored if an
errorfile is used.
This directive may be used instead of "errorfile", to define a custom error This directive may be used instead of "errorfile", to define a custom error
message. As "errorfile" directive, it is used for errors detected and message. As "errorfile" directive, it is used for errors detected and
@ -8339,8 +8344,8 @@ no log
# level and send in tcp # level and send in tcp
log "${LOCAL_SYSLOG}:514" local0 notice # send to local server log "${LOCAL_SYSLOG}:514" local0 notice # send to local server
log-format <string> log-format <fmt>
Specifies the log format string to use for traffic logs Specifies the custom log format string to use for traffic logs
May be used in the following contexts: tcp, http May be used in the following contexts: tcp, http
@ -8359,8 +8364,8 @@ log-format <string>
"log-format" directive overrides previous "option tcplog", "log-format", "log-format" directive overrides previous "option tcplog", "log-format",
"option httplog" and "option httpslog" directives. "option httplog" and "option httpslog" directives.
log-format-sd <string> log-format-sd <fmt>
Specifies the RFC5424 structured-data log format string Specifies the Custom log format string used to produce RFC5424 structured-data
May be used in the following contexts: tcp, http May be used in the following contexts: tcp, http
@ -10924,8 +10929,8 @@ redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
Arguments : Arguments :
<loc> With "redirect location", the exact value in <loc> is placed into <loc> With "redirect location", the exact value in <loc> is placed into
the HTTP "Location" header. When used in an "http-request" rule, the HTTP "Location" header. When used in an "http-request" rule,
<loc> value follows the log-format rules and can include some <loc> value follows the Custom log format rules and can include
dynamic values (see Custom Log Format in section 8.2.6). some dynamic values (see Custom log format in section 8.2.6).
<pfx> With "redirect prefix", the "Location" header is built from the <pfx> With "redirect prefix", the "Location" header is built from the
concatenation of <pfx> and the complete URI path, including the concatenation of <pfx> and the complete URI path, including the
@ -10933,9 +10938,9 @@ redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
below). As a special case, if <pfx> equals exactly "/", then below). As a special case, if <pfx> equals exactly "/", then
nothing is inserted before the original URI. It allows one to nothing is inserted before the original URI. It allows one to
redirect to the same URL (for instance, to insert a cookie). When redirect to the same URL (for instance, to insert a cookie). When
used in an "http-request" rule, <pfx> value follows the log-format used in an "http-request" rule, <pfx> value follows the Custom
rules and can include some dynamic values (see Custom Log Format Log Format rules and can include some dynamic values (see Custom
in section 8.2.6). Log Format in section 8.2.6).
<sch> With "redirect scheme", then the "Location" header is built by <sch> With "redirect scheme", then the "Location" header is built by
concatenating <sch> with "://" then the first occurrence of the concatenating <sch> with "://" then the first occurrence of the
@ -10946,8 +10951,8 @@ redirect scheme <sch> [code <code>] <option> [{if | unless} <condition>]
returned, which most recent browsers interpret as redirecting to returned, which most recent browsers interpret as redirecting to
the same host. This directive is mostly used to redirect HTTP to the same host. This directive is mostly used to redirect HTTP to
HTTPS. When used in an "http-request" rule, <sch> value follows HTTPS. When used in an "http-request" rule, <sch> value follows
the log-format rules and can include some dynamic values (see the Custom log format rules and can include some dynamic values
Custom Log Format in section 8.2.6). (see Custom log format in section 8.2.6).
<code> The code is optional. It indicates which type of HTTP redirection <code> The code is optional. It indicates which type of HTTP redirection
is desired. Only codes 301, 302, 303, 307 and 308 are supported, is desired. Only codes 301, 302, 303, 307 and 308 are supported,
@ -12824,12 +12829,13 @@ tcp-check expect [min-recv <int>] [comment <msg>]
on-success <fmt> is optional and can be used to customize the on-success <fmt> is optional and can be used to customize the
informational message reported in logs if the expect informational message reported in logs if the expect
rule is successfully evaluated and if it is the last rule rule is successfully evaluated and if it is the last rule
in the tcp-check ruleset. <fmt> is a log-format string. in the tcp-check ruleset. <fmt> is a Custom log format
(see section 8.2.6).
on-error <fmt> is optional and can be used to customize the on-error <fmt> is optional and can be used to customize the
informational message reported in logs if an error informational message reported in logs if an error
occurred during the expect rule evaluation. <fmt> is a occurred during the expect rule evaluation. <fmt> is a
log-format string. Custom log format (see section 8.2.6).
status-code <expr> is optional and can be used to set the check status code status-code <expr> is optional and can be used to set the check status code
reported in logs, on success or on error. <expr> is a reported in logs, on success or on error. <expr> is a
@ -12862,12 +12868,13 @@ tcp-check expect [min-recv <int>] [comment <msg>]
will be considered invalid if the body matches the will be considered invalid if the body matches the
expression. expression.
string-lf <fmt> : test a log-format string match in the response's buffer. string-lf <fmt> : test a Custom log format match in the response's buffer.
A health check response will be considered valid if the A health check response will be considered valid if the
response's buffer contains the string resulting of the response's buffer contains the string resulting of the
evaluation of <fmt>, which follows the log-format rules. evaluation of <fmt>, which follows the Custom log format
If prefixed with "!", then the response will be rules described in section 8.2.6. If prefixed with "!",
considered invalid if the buffer contains the string. then the response will be considered invalid if the
buffer contains the string.
binary <hexstring> : test the exact string in its hexadecimal form matches binary <hexstring> : test the exact string in its hexadecimal form matches
in the response buffer. A health check response will in the response buffer. A health check response will
@ -12884,16 +12891,16 @@ tcp-check expect [min-recv <int>] [comment <msg>]
pattern should work on at-most half the response buffer pattern should work on at-most half the response buffer
size. size.
binary-lf <hexfmt> : test a log-format string in its hexadecimal form binary-lf <hexfmt> : test a Custom log format in its hexadecimal form match
match in the response's buffer. A health check response in the response's buffer. A health check response will
will be considered valid if the response's buffer be considered valid if the response's buffer contains
contains the hexadecimal string resulting of the the hexadecimal string resulting of the evaluation of
evaluation of <fmt>, which follows the log-format <fmt>, which follows the Custom log format rules (see
rules. If prefixed with "!", then the response will be section 8.2.6). If prefixed with "!", then the
considered invalid if the buffer contains the response will be considered invalid if the buffer
hexadecimal string. The hexadecimal string is converted contains the hexadecimal string. The hexadecimal
in a binary string before matching the response's string is converted in a binary string before matching
buffer. the response's buffer.
It is important to note that the responses will be limited to a certain size It is important to note that the responses will be limited to a certain size
defined by the global "tune.bufsize" option, which defaults to 16384 bytes. defined by the global "tune.bufsize" option, which defaults to 16384 bytes.
@ -12932,7 +12939,7 @@ tcp-check expect [min-recv <int>] [comment <msg>]
tcp-check send <data> [comment <msg>] tcp-check send <data> [comment <msg>]
tcp-check send-lf <fmt> [comment <msg>] tcp-check send-lf <fmt> [comment <msg>]
Specify a string or a log-format string to be sent as a question during a Specify a string or a Custom log format to be sent as a question during a
generic health check generic health check
May be used in the following contexts: tcp, http, log May be used in the following contexts: tcp, http, log
@ -12946,8 +12953,8 @@ tcp-check send-lf <fmt> [comment <msg>]
<data> is the string that will be sent during a generic health <data> is the string that will be sent during a generic health
check session. check session.
<fmt> is the log-format string that will be sent, once evaluated, <fmt> is the Custom log format that will be sent, once evaluated,
during a generic health check session. during a generic health check session (see section 8.2.6).
Examples : Examples :
# look for the redis master server # look for the redis master server
@ -12961,7 +12968,7 @@ tcp-check send-lf <fmt> [comment <msg>]
tcp-check send-binary <hexstring> [comment <msg>] tcp-check send-binary <hexstring> [comment <msg>]
tcp-check send-binary-lf <hexfmt> [comment <msg>] tcp-check send-binary-lf <hexfmt> [comment <msg>]
Specify an hex digits string or an hex digits log-format string to be sent as Specify an hex digits string or an hex digits Custom log format to be sent as
a binary question during a raw tcp health check a binary question during a raw tcp health check
May be used in the following contexts: tcp, http, log May be used in the following contexts: tcp, http, log
@ -12975,9 +12982,9 @@ tcp-check send-binary-lf <hexfmt> [comment <msg>]
<hexstring> is the hexadecimal string that will be send, once converted <hexstring> is the hexadecimal string that will be send, once converted
to binary, during a generic health check session. to binary, during a generic health check session.
<hexfmt> is the hexadecimal log-format string that will be send, once <hexfmt> is the hexadecimal Custom log format that will be send, once
evaluated and converted to binary, during a generic health evaluated and converted to binary, during a generic health
check session. check session (see section 8.2.6).
Examples : Examples :
# redis check in binary # redis check in binary
@ -13016,8 +13023,8 @@ tcp-check set-var-fmt(<var-name>[,<cond>...]) <fmt>
<expr> Is a sample-fetch expression potentially followed by converters. <expr> Is a sample-fetch expression potentially followed by converters.
<fmt> This is the value expressed using log-format rules (see Custom <fmt> This is the value expressed using Custom log format rules (see
Log Format in section 8.2.6). Custom log format in section 8.2.6).
Examples : Examples :
tcp-check set-var(check.port) int(1234) tcp-check set-var(check.port) int(1234)
@ -13956,7 +13963,7 @@ transparent (deprecated)
See also: "option transparent" See also: "option transparent"
unique-id-format <string> unique-id-format <fmt>
Generate a unique ID for each request. Generate a unique ID for each request.
May be used in the following contexts: tcp, http May be used in the following contexts: tcp, http
@ -13965,12 +13972,12 @@ unique-id-format <string>
yes | yes | yes | no yes | yes | yes | no
Arguments : Arguments :
<string> is a log-format string. <fmt> is a Custom log format string (see section 8.2.6).
This keyword creates a ID for each request using the custom log format. A This keyword creates a ID for each request using the custom log format. A
unique ID is useful to trace a request passing through many components of unique ID is useful to trace a request passing through many components of
a complex infrastructure. The newly created ID may also be logged using the a complex infrastructure. The newly created ID may also be logged using the
%ID tag the log-format string. %ID tag the Custom log format string.
The format should be composed from elements that are guaranteed to be The format should be composed from elements that are guaranteed to be
unique when combined together. For instance, if multiple HAProxy instances unique when combined together. For instance, if multiple HAProxy instances
@ -14029,7 +14036,8 @@ use_backend <backend> [{if | unless} <condition>]
Arguments : Arguments :
<backend> is the name of a valid backend or "listen" section, or a <backend> is the name of a valid backend or "listen" section, or a
"log-format" string resolving to a backend name. Custom log format resolving to a backend name (see Custom
Log Format in section 8.2.6).
<condition> is a condition composed of ACLs, as described in section 7. If <condition> is a condition composed of ACLs, as described in section 7. If
it is omitted, the rule is unconditionally applied. it is omitted, the rule is unconditionally applied.
@ -14061,7 +14069,7 @@ use_backend <backend> [{if | unless} <condition>]
When <backend> is a simple name, it is resolved at configuration time, and an When <backend> is a simple name, it is resolved at configuration time, and an
error is reported if the specified backend does not exist. If <backend> is error is reported if the specified backend does not exist. If <backend> is
a log-format string instead, no check may be done at configuration time, so a Custom log format instead, no check may be done at configuration time, so
the backend name is resolved dynamically at run time. If the resulting the backend name is resolved dynamically at run time. If the resulting
backend name does not correspond to any valid backend, no other rule is backend name does not correspond to any valid backend, no other rule is
evaluated, and the default_backend directive is applied instead. Note that evaluated, and the default_backend directive is applied instead. Note that
@ -14100,7 +14108,8 @@ use-server <server> unless <condition>
Arguments : Arguments :
<server> is the name of a valid server in the same backend section <server> is the name of a valid server in the same backend section
or a "log-format" string resolving to a server name. or a Custom log format string resolving to a server name
(see section 8.2.6).
<condition> is a condition composed of ACLs, as described in section 7. <condition> is a condition composed of ACLs, as described in section 7.
@ -14148,10 +14157,10 @@ use-server <server> unless <condition>
When <server> is a simple name, it is checked against existing servers in the When <server> is a simple name, it is checked against existing servers in the
configuration and an error is reported if the specified server does not exist. configuration and an error is reported if the specified server does not exist.
If it is a log-format, no check is performed when parsing the configuration, If it is a Custom log format, no check is performed when parsing the
and if we can't resolve a valid server name at runtime but the use-server rule configuration, and if we can't resolve a valid server name at runtime but the
was conditioned by an ACL returning true, no other use-server rule is applied use-server rule was conditioned by an ACL returning true, no other use-server
and we fall back to load balancing. rule is applied and we fall back to load balancing.
See also: "use_backend", section 5 about server and section 7 about ACLs. See also: "use_backend", section 5 about server and section 7 about ACLs.
@ -14288,10 +14297,10 @@ add-acl(<file-name>) <key fmt>
This is used to add a new entry into an ACL. The ACL must be loaded from a 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 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 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 Custom log format rules described in section 8.2.6, to collect content of the
in the ACL before insertion, to avoid duplicated (or more) values. new entry. It performs a lookup in the ACL before insertion, to avoid
It is the equivalent of the "add acl" command from the stats socket, but can duplicated (or more) values. It is the equivalent of the "add acl" command
be triggered by an HTTP request. from the stats socket, but can be triggered by an HTTP request.
add-header <name> <fmt> add-header <name> <fmt>
@ -14299,13 +14308,13 @@ add-header <name> <fmt>
- | - | - | - | X | X | X - | - | - | - | X | X | X
This appends an HTTP header field whose name is specified in <name> and 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 whose value is defined by <fmt> which follows the Custom log format rules
Custom Log Format in section 8.2.6). This is particularly useful to pass (see Custom log format in section 8.2.6). This is particularly useful to pass
connection-specific information to the server (e.g. the client's SSL connection-specific information to the server (e.g. the client's SSL
certificate), or to combine several headers into one. This rule is not certificate), or to combine several headers into one. This rule is not final,
final, so it is possible to add other similar rules. Note that header so it is possible to add other similar rules. Note that header addition is
addition is performed immediately, so one rule might reuse the resulting performed immediately, so one rule might reuse the resulting header from a
header from a previous rule. previous rule.
allow allow
@ -14436,9 +14445,9 @@ del-acl(<file-name>) <key fmt>
This is used to delete an entry from an ACL. The ACL must be loaded from a 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 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 passed between parentheses. It takes one argument: <key fmt>, which follows
log-format rules, to collect content of the entry to delete. Custom log format rules of section 8.2.6, to collect content of the entry to
It is the equivalent of the "del acl" command from the stats socket, but can delete. It is the equivalent of the "del acl" command from the stats socket,
be triggered by an HTTP request or response. but can be triggered by an HTTP request or response.
del-header <name> [ -m <meth> ] del-header <name> [ -m <meth> ]
@ -14459,10 +14468,10 @@ del-map(<map-name>) <key fmt>
This is used to delete an entry from a MAP. <map-name> must follow the format This is used to delete an entry from a MAP. <map-name> must follow the format
described in 2.7. about name format for maps and ACLs. The name of the MAP to described in 2.7. about name format for maps and ACLs. The name of the MAP to
be updated is passed between parentheses. It takes one argument: <key fmt>, 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. which follows Custom log format rules of section 8.2.6, to collect content of
It takes one argument: "file name" It is the equivalent of the "del map" the entry to delete. It takes one argument: "file name" It is the equivalent
command from the stats socket, but can be triggered by an HTTP request or of the "del map" command from the stats socket, but can be triggered by an
response. HTTP request or response.
deny [ { status | deny_status } <code> ] [ content-type <type> ] deny [ { status | deny_status } <code> ] [ content-type <type> ]
@ -14557,10 +14566,10 @@ early-hint <name> <fmt>
This is used to build an HTTP 103 Early Hints response prior to any other one. This is used to build an HTTP 103 Early Hints response prior to any other one.
This appends an HTTP header field to this response whose name is specified in This appends an HTTP header field to this response whose name is specified in
<name> and whose value is defined by <fmt> which follows the log-format rules <name> and whose value is defined by <fmt> which follows the Custom Log
(see Custom Log Format in section 8.2.6). This is particularly useful to pass Format rules (see Custom log format in section 8.2.6). This is particularly
to the client some Link headers to preload resources required to render the useful to pass to the client some Link headers to preload resources required
HTML documents. to render the HTML documents.
See RFC 8297 for more information. See RFC 8297 for more information.
@ -14747,7 +14756,7 @@ redirect <rule>
This performs an HTTP redirection based on a redirect rule. This is exactly 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 the same as the "redirect" statement except that it inserts a redirect rule
which is processed in the middle of other "http-request" or "http-response" which is processed in the middle of other "http-request" or "http-response"
rules and that these rules use the "log-format" strings. For responses, only rules and that these rules use the Custom log format. For responses, only
the "location" type of redirect is permitted. In addition, when a redirect is the "location" type of redirect is permitted. In addition, when a redirect is
performed during a response, the transfer from the server to HAProxy is performed during a response, the transfer from the server to HAProxy is
interrupted so that no payload can be forwarded to the client. This may cause interrupted so that no payload can be forwarded to the client. This may cause
@ -14973,19 +14982,20 @@ return [ status <code> ] [ content-type <type> ]
used as the response payload. If the file is not empty, its content-type used as the response payload. If the file is not empty, its content-type
must be set as argument to "content-type". Otherwise, any "content-type" must be set as argument to "content-type". Otherwise, any "content-type"
argument is ignored. With a "lf-file" argument, the file's content is argument is ignored. With a "lf-file" argument, the file's content is
evaluated as a log-format string. With a "file" argument, it is considered evaluated as a Custom log format (see section 8.2.6). With a "file"
as a raw content. argument, it is considered as a raw content.
* If a "string" or "lf-string" argument is specified, the defined string is * If a "string" or "lf-string" argument is specified, the defined string is
used as the response payload. The content-type must always be set as used as the response payload. The content-type must always be set as
argument to "content-type". With a "lf-string" argument, the string is argument to "content-type". With a "lf-string" argument, the string is
evaluated as a log-format string. With a "string" argument, it is evaluated as a Custom log format (see section 8.2.6). With a "string"
considered as a raw string. argument, it is considered as a raw string.
When the response is not based on an errorfile, it is possible to append HTTP When the response is not based on an errorfile, it is possible to append HTTP
header fields to the response using "hdr" arguments. Otherwise, all "hdr" header fields to the response using "hdr" arguments. Otherwise, all "hdr"
arguments are ignored. For each one, the header name is specified in <name> arguments are ignored. For each one, the header name is specified in <name>
and its value is defined by <fmt> which follows the log-format rules. and its value is defined by <fmt> which follows the Custom log format rules
described in section 8.2.6.
Note that the generated response must be smaller than a buffer. And to avoid Note that the generated response must be smaller than a buffer. And to avoid
any warning, when an errorfile or a raw file is loaded, the buffer space any warning, when an errorfile or a raw file is loaded, the buffer space
@ -15289,11 +15299,12 @@ set-map(<map-name>) <key fmt> <value fmt>
This is used to add a new entry into a map. <map-name> must follow the format This is used to add a new entry into a map. <map-name> must follow the format
described in 2.7. about name format for maps and ACLs. The name of the MAP to described in 2.7. about name format for maps and ACLs. The name of the MAP to
be updated is passed between parentheses. It takes 2 arguments: <key fmt>, 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 Custom log format rules described in section 8.2.6, used to
which follows log-format rules, used to collect content for the new entry. collect map key, and <value fmt>, which follows Custom log format rules, used
It performs a lookup in the map before insertion, to avoid duplicated (or to collect content for the new entry. It performs a lookup in the map before
more) values. It is the equivalent of the "set map" command from the insertion, to avoid duplicated (or more) values. It is the equivalent of the
stats socket, but can be triggered by an HTTP request. "set map" command from the stats socket, but can be triggered by an HTTP
request.
set-mark <mark> (deprecated) set-mark <mark> (deprecated)
@ -15533,8 +15544,8 @@ set-var-fmt(<var-name>[,<cond>...]) <fmt>
<expr> Is a standard HAProxy expression formed by a sample-fetch <expr> Is a standard HAProxy expression formed by a sample-fetch
followed by some converters. followed by some converters.
<fmt> This is the value expressed using log-format rules (see Custom <fmt> This is the value expressed using Custom log format rules (see
Log Format in section 8.2.6). Custom log format in section 8.2.6).
All scopes are usable for HTTP rules, but scopes "proc" and "sess" are the All scopes are usable for HTTP rules, but scopes "proc" and "sess" are the
only usable ones in rule sets which do not have access to contents such as only usable ones in rule sets which do not have access to contents such as
@ -23724,7 +23735,7 @@ Warning : Following sample fetches are ignored if used from HTTP proxies. They
HTTP proxies use structured content. Thus raw representation of HTTP proxies use structured content. Thus raw representation of
these data are meaningless. A warning is emitted if an ACL relies on these data are meaningless. A warning is emitted if an ACL relies on
one of the following sample fetches. But it is not possible to detect one of the following sample fetches. But it is not possible to detect
all invalid usage (for instance inside a log-format string or a all invalid usage (for instance inside a Custom log format or a
sample expression). So be careful. sample expression). So be careful.
Summary of sample fetch methods in this section and their respective types: Summary of sample fetch methods in this section and their respective types:
@ -27425,8 +27436,8 @@ no option mpxs-conns
set-param <name> <fmt> [ { if | unless } <condition> ] set-param <name> <fmt> [ { if | unless } <condition> ]
Set a FastCGI parameter that should be passed to this application. Its Set a FastCGI parameter that should be passed to this application. Its
value, defined by <fmt> must follows the log-format rules (see section 8.2.6 value, defined by <fmt> must follows the Custom log format rules (see section
"Custom Log format"). It may optionally be followed by an ACL-based 8.2.6 "Custom Log format"). It may optionally be followed by an ACL-based
condition, in which case it will only be evaluated if the condition is true. condition, in which case it will only be evaluated if the condition is true.
With this directive, it is possible to overwrite the value of default FastCGI With this directive, it is possible to overwrite the value of default FastCGI