22<html lang="en">
33 <head>
44 <meta charset="utf-8" />
5- <title>HAProxy version 3.1.8-17 - Configuration Manual</title>
5+ <title>HAProxy version 3.1.8-85 - Configuration Manual</title>
66 <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" />
77 <link href="https://raw.githubusercontent.com/thomaspark/bootswatch/v3.3.7/cerulean/bootstrap.min.css" rel="stylesheet" />
88 <link href="../css/page.css?0.4.2-15" rel="stylesheet" />
44304430 You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
44314431 </p>
44324432 <p class="text-right">
4433- <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2025/06/17 </b></small>
4433+ <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2025/08/26 </b></small>
44344434 </p>
44354435 </div>
44364436 <!-- /.sidebar -->
44414441 <div class="text-center">
44424442 <h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
44434443 <h2>Configuration Manual</h2>
4444- <p><strong>version 3.1.8-17 </strong></p>
4444+ <p><strong>version 3.1.8-85 </strong></p>
44454445 <p>
44464446 2025/06/02<br>
44474447
@@ -7073,6 +7073,7 @@ <h2 id="chapter-2.9" data-target="2.9"><small><a class="small" href="#2.9">2.9.<
70737073 - <a href="#insecure-setuid-wanted">insecure-setuid-wanted</a>
70747074 - <a href="#issuers-chain-path">issuers-chain-path</a>
70757075 - <a href="#key-base">key-base</a>
7076+ - <a href="#limited-quic">limited-quic</a>
70767077 - <a href="#localpeer">localpeer</a>
70777078 - <a href="#log">log</a>
70787079 - <a href="#log-send-hostname">log-send-hostname</a>
@@ -7082,6 +7083,7 @@ <h2 id="chapter-2.9" data-target="2.9"><small><a class="small" href="#2.9">2.9.<
70827083 - <a href="#lua-prepend-path">lua-prepend-path</a>
70837084 - <a href="#mworker-max-reloads">mworker-max-reloads</a>
70847085 - <a href="#nbthread">nbthread</a>
7086+ - <a href="#no-quic">no-quic</a>
70857087 - <a href="#node">node</a>
70867088 - <a href="#numa-cpu-mapping">numa-cpu-mapping</a>
70877089 - <a href="#ocsp-update.disable">ocsp-update.disable</a>
@@ -7210,6 +7212,7 @@ <h2 id="chapter-2.9" data-target="2.9"><small><a class="small" href="#2.9">2.9.<
72107212 - <a href="#tune.pool-low-fd-ratio">tune.pool-low-fd-ratio</a>
72117213 - <a href="#tune.pt.zero-copy-forwarding">tune.pt.zero-copy-forwarding</a>
72127214 - <a href="#tune.quic.cc-hystart">tune.quic.cc-hystart</a>
7215+ - <a href="#tune.quic.cc.cubic.min-losses">tune.quic.cc.cubic.min-losses</a>
72137216 - <a href="#tune.quic.disable-udp-gso">tune.quic.disable-udp-gso</a>
72147217 - <a href="#tune.quic.frontend.glitches-threshold">tune.quic.frontend.glitches-threshold</a>
72157218 - <a href="#tune.quic.frontend.max-idle-timeout">tune.quic.frontend.max-idle-timeout</a>
@@ -9781,6 +9784,10 @@ <h2 id="chapter-3.4" data-target="3.4"><small><a class="small" href="#3.4">3.4.<
97819784As a side note, musl (e.g. Alpine Linux) implementations are known to be
97829785slower than their glibc counterparts when calculating hashes, so you might
97839786want to consider this aspect too.
9787+
9788+ All passwords are considered normal arguments and are therefor subject to
9789+ regular <a href="#2.2">section 2.2</a> Quoting and escaping. Single quoting passwords is
9790+ therefor recommended.
97849791</pre><div class="separator">
97859792<span class="label label-success">Example:</span>
97869793<pre class="prettyprint">
@@ -9789,16 +9796,16 @@ <h2 id="chapter-3.4" data-target="3.4"><small><a class="small" href="#3.4">3.4.<
97899796 group G2 users xdb,scott
97909797
97919798 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
9792- user scott insecure-password elgato
9793- user xdb insecure-password hello
9799+ user scott insecure-password ' elgato'
9800+ user xdb insecure-password ' hello'
97949801
97959802userlist L2
97969803 group G1
97979804 group G2
97989805
97999806 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
9800- user scott insecure-password elgato groups G1,G2
9801- user xdb insecure-password hello groups G2
9807+ user scott insecure-password ' elgato' groups G1,G2
9808+ user xdb insecure-password ' hello' groups G2
98029809</code></pre>
98039810</div><pre class="text">Please note that both lists are functionally identical.
98049811</pre></div>
@@ -15357,8 +15364,23 @@ <h2 id="chapter-4.2" data-target="4.2"><small><a class="small" href="#4.2">4.2.<
1535715364desirable in these environments as well, to avoid redistributing the traffic
1535815365after every other response.
1535915366
15360- If this option has been enabled in a "defaults" section, it can be disabled
15361- in a specific instance by prepending the "no" keyword before it.
15367+ It may be useful to precise here, which load balancing algorithms are
15368+ considered deterministic. Deterministic algorithms will always select the same
15369+ server for a given client data, assuming the set of available servers has not
15370+ changed. In general, deterministic algorithms involve hasing or lookups on the
15371+ incoming requests to choose the target server. However, this is not always the
15372+ case; "static-rr", for example, can be also considered as deterministic because
15373+ the server choice is based on the server's static weight, making the selection
15374+ predictable. "sticky" algorithm provides deterministic routing for the
15375+ returning clients.
15376+
15377+ As for non-deterministic algorithms, these algorithms select a server based on
15378+ dynamic server state or simple rotation, so two consecutive requests are not
15379+ guaranteed to land on the same server. option prefer-last-server is designed
15380+ specifically for these. roundrobin, leastconn are examples of such algorithms.
15381+
15382+ If this option has been enabled in a "defaults" section, it can be
15383+ disabled in a specific instance by prepending the "no" keyword before it.
1536215384</pre><div class="page-header"><b>See also:</b> "<a href="#option%20http-keep-alive">option http-keep-alive</a>"</div>
1536315385<a class="anchor" name="option"></a><a class="anchor" name="4-option"></a><a class="anchor" name="4.2-option"></a><a class="anchor" name="option (Proxies)"></a><a class="anchor" name="option (Alphabetically sorted keywords reference)"></a><a class="anchor" name="option redispatch"></a><a class="anchor" name="4-option redispatch"></a><a class="anchor" name="4.2-option redispatch"></a><a class="anchor" name="option redispatch (Proxies)"></a><a class="anchor" name="option redispatch (Alphabetically sorted keywords reference)"></a><div class="keyword"><b><a class="anchor" name="option redispatch"></a><a href="#4.2-option%20redispatch">option redispatch</a></b></div><a class="anchor" name="option"></a><a class="anchor" name="4-option"></a><a class="anchor" name="4.2-option"></a><a class="anchor" name="option (Proxies)"></a><a class="anchor" name="option (Alphabetically sorted keywords reference)"></a><a class="anchor" name="option redispatch"></a><a class="anchor" name="4-option redispatch"></a><a class="anchor" name="4.2-option redispatch"></a><a class="anchor" name="option redispatch (Proxies)"></a><a class="anchor" name="option redispatch (Alphabetically sorted keywords reference)"></a><div class="keyword"><b><a class="anchor" name="option redispatch"></a><a href="#4.2-option%20redispatch">option redispatch</a></b> <span style="color: #080"><interval></span></div><a class="anchor" name="no"></a><a class="anchor" name="4-no"></a><a class="anchor" name="4.2-no"></a><a class="anchor" name="no (Proxies)"></a><a class="anchor" name="no (Alphabetically sorted keywords reference)"></a><a class="anchor" name="no option"></a><a class="anchor" name="4-no option"></a><a class="anchor" name="4.2-no option"></a><a class="anchor" name="no option (Proxies)"></a><a class="anchor" name="no option (Alphabetically sorted keywords reference)"></a><a class="anchor" name="no option redispatch"></a><a class="anchor" name="4-no option redispatch"></a><a class="anchor" name="4.2-no option redispatch"></a><a class="anchor" name="no option redispatch (Proxies)"></a><a class="anchor" name="no option redispatch (Alphabetically sorted keywords reference)"></a><div class="keyword"><b><a class="anchor" name="no option redispatch"></a><a href="#4.2-no%20option%20redispatch">no option redispatch</a></b></div><pre class="text">Enable or disable session redistribution in case of connection failure
1536415386
@@ -16715,9 +16737,9 @@ <h2 id="chapter-4.2" data-target="4.2"><small><a class="small" href="#4.2">4.2.<
1671516737<code><span class="comment"># statistics admin level depends on the authenticated user</span>
1671616738userlist stats-auth
1671716739 group admin users admin
16718- user admin insecure-password AdMiN123
16740+ user admin insecure-password ' AdMiN123'
1671916741 group readonly users haproxy
16720- user haproxy insecure-password haproxy
16742+ user haproxy insecure-password ' haproxy'
1672116743
1672216744backend stats_auth
1672316745 stats enable
@@ -21344,9 +21366,16 @@ <h2 id="chapter-5.1" data-target="5.1"><small><a class="small" href="#5.1">5.1.<
2134421366</pre><a class="anchor" name="prefer-client-ciphers"></a><a class="anchor" name="5-prefer-client-ciphers"></a><a class="anchor" name="5.1-prefer-client-ciphers"></a><a class="anchor" name="prefer-client-ciphers (Bind and server options)"></a><a class="anchor" name="prefer-client-ciphers (Bind options)"></a><div class="keyword"><b><a class="anchor" name="prefer-client-ciphers"></a><a href="#5.1-prefer-client-ciphers">prefer-client-ciphers</a></b></div><pre class="text">Use the client's preference when selecting the cipher suite, by default
2134521367the server's preference is enforced. This option is also available on
2134621368global statement "<a href="#ssl-default-bind-options">ssl-default-bind-options</a>".
21369+
2134721370Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
2134821371(without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
2134921372the client cipher list.
21373+
21374+ When using a dual algorithms setup (RSA + ECDSA), the selection algorithm
21375+ will chose between RSA and ECDSA and will always prioritize ECDSA. Once the
21376+ right certificate is chosen, it will let the SSL library prioritize ciphers,
21377+ curves etc. Meaning this option can't be used to prioritize an RSA
21378+ certificate over an ECDSA one.
2135021379</pre><a class="anchor" name="proto"></a><a class="anchor" name="5-proto"></a><a class="anchor" name="5.1-proto"></a><a class="anchor" name="proto (Bind and server options)"></a><a class="anchor" name="proto (Bind options)"></a><div class="keyword"><b><a class="anchor" name="proto"></a><a href="#5.1-proto">proto</a></b> <span style="color: #080"><name></span></div><pre class="text">Forces the multiplexer's protocol to use for the incoming connections. It
2135121380must be compatible with the mode of the frontend (TCP or HTTP). It must also
2135221381be usable on the frontend side. The list of available protocols is reported
@@ -24450,11 +24479,14 @@ <h3 id="chapter-7.3.1" data-target="7.3.1"><small><a class="small" href="#7.3.1"
2445024479compiled with USE_OPENSSL.
2445124480</pre><a class="anchor" name="jwt_verify"></a><a class="anchor" name="7-jwt_verify"></a><a class="anchor" name="7.3.1-jwt_verify"></a><a class="anchor" name="jwt_verify (Using ACLs and fetching samples)"></a><a class="anchor" name="jwt_verify (Converters)"></a><div class="keyword"><b><a class="anchor" name="jwt_verify"></a><a href="#7.3.1-jwt_verify">jwt_verify</a></b>(<span style="color: #080"><alg></span>,<span style="color: #080"><key></span>)</div><pre class="text">Performs a signature verification for the JSON Web Token (JWT) given in input
2445224481by using the <alg> algorithm and the <key> parameter, which should either
24453- hold a secret or a path to a public certificate. Returns 1 in case of
24454- verification success, 0 in case of verification error and a strictly negative
24455- value for any other error. Because of all those non-null error return values,
24456- the result of this converter should never be converted to a boolean. See
24457- below for a full list of the possible return values.
24482+ hold a secret or a path to a public key. The public key should either be in
24483+ the PKCS#1 format (for RSA keys, starting with BEGIN RSA PUBLIC KEY) or SPKI
24484+ format (Subject Public Key Info, starting with BEGIN PUBLIC KEY).
24485+ Returns 1 in case of verification success, 0 in case of verification failure
24486+ and a strictly negative value for any other error. Because of all those
24487+ non-null error return values, the result of this converter should never be
24488+ converted to a boolean. See below for a full list of the possible return
24489+ values.
2445824490
2445924491For now, only JWS tokens using the Compact Serialization format can be
2446024492processed (three dot-separated base64-url encoded strings). All the
@@ -24463,16 +24495,16 @@ <h3 id="chapter-7.3.1" data-target="7.3.1"><small><a class="small" href="#7.3.1"
2446324495
2446424496If the used algorithm is of the HMAC family, <key> should be the secret used
2446524497in the HMAC signature calculation. Otherwise, <key> should be the path to the
24466- public certificate that can be used to validate the token's signature. All
24467- the certificates that might be used to verify JWTs must be known during init
24468- in order to be added into a dedicated certificate cache so that no disk
24469- access is required during runtime. For this reason, any used certificate must
24470- be mentioned explicitly at least once in a jwt_verify call. Passing an
24471- intermediate variable as second parameter is then not advised.
24498+ public key that can be used to validate the token's signature. All the public
24499+ keys that might be used to verify JWTs must be known during init in order to
24500+ be added into a dedicated cache so that no disk access is required during
24501+ runtime. For this reason, any used public key must be mentioned explicitly at
24502+ least once in a jwt_verify call. Passing an intermediate variable as second
24503+ parameter is then not advised.
2447224504
2447324505This converter only verifies the signature of the token and does not perform
2447424506a full JWT validation as specified in <a href="#7.2">section 7.2</a> of RFC7519. We do not
24475- ensure that the header and payload contents are fully valid JSON's once
24507+ ensure that the header and payload contents are fully valid JSONs once
2447624508decoded for instance, and no checks are performed regarding their respective
2447724509contents.
2447824510
@@ -24500,7 +24532,7 @@ <h3 id="chapter-7.3.1" data-target="7.3.1"><small><a class="small" href="#7.3.1"
2450024532http-request set-var(txn.bearer) http_auth_bearer
2450124533http-request set-var(txn.jwt_alg) var(txn.bearer),jwt_header_query('$.alg')
2450224534http-request deny unless { var(txn.jwt_alg) -m str "RS256" }
24503- http-request deny unless { var(txn.bearer),jwt_verify(txn.jwt_alg,"/path/to/crt .pem") 1 }
24535+ http-request deny unless { var(txn.bearer),jwt_verify(txn.jwt_alg,"/path/to/pubkey .pem") 1 }
2450424536</code></pre>
2450524537</div><a class="anchor" name="language"></a><a class="anchor" name="7-language"></a><a class="anchor" name="7.3.1-language"></a><a class="anchor" name="language (Using ACLs and fetching samples)"></a><a class="anchor" name="language (Converters)"></a><div class="keyword"><b><a class="anchor" name="language"></a><a href="#7.3.1-language">language</a></b>(<span style="color: #080"><value></span><span style="color: #008">[,<span style="color: #080"><default></span>]</span>)</div><pre class="text">Returns the value with the highest q-factor from a list as extracted from the
2450624538"accept-language" header using "<a href="#req.fhdr">req.fhdr</a>". Values with no q-factor have a
@@ -31786,7 +31818,7 @@ <h2 id="chapter-11.3" data-target="11.3"><small><a class="small" href="#11.3">11
3178631818 <br>
3178731819 <hr>
3178831820 <div class="text-right">
31789- HAProxy 3.1.8-17 – Configuration Manual<br>
31821+ HAProxy 3.1.8-85 – Configuration Manual<br>
3179031822 <small>, 2025/06/02</small>
3179131823 </div>
3179231824 </div>
0 commit comments