22<html lang="en">
33 <head>
44 <meta charset="utf-8" />
5- <title>HAProxy version 2.8.15-36 - Configuration Manual</title>
5+ <title>HAProxy version 2.8.15-106 - 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" />
42944294 You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
42954295 </p>
42964296 <p class="text-right">
4297- <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2025/05/27 </b></small>
4297+ <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2025/10/01 </b></small>
42984298 </p>
42994299 </div>
43004300 <!-- /.sidebar -->
43054305 <div class="text-center">
43064306 <h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
43074307 <h2>Configuration Manual</h2>
4308- <p><strong>version 2.8.15-36 </strong></p>
4308+ <p><strong>version 2.8.15-106 </strong></p>
43094309 <p>
43104310 2025/04/22<br>
43114311
@@ -6295,8 +6295,8 @@ <h2 id="chapter-2.4" data-target="2.4"><small><a class="small" href="#2.4">2.4.<
62956295 - .warning "message" : emit this message at level WARNING
62966296 - .alert "message" : emit this message at level ALERT
62976297
6298- Messages emitted at level WARNING may cause the process to fail to start if the
6299- "strict-mode " is enabled. Messages emitted at level ALERT will always cause a
6298+ Messages emitted at level WARNING may cause the process to fail to start if
6299+ "<a href="#zero-warning">zero-warning</a> " is enabled. Messages emitted at level ALERT will always cause a
63006300fatal error. These can be used to detect some inappropriate conditions and
63016301provide advice to the user.
63026302</pre><div class="separator">
@@ -6439,6 +6439,7 @@ <h2 id="chapter-2.7" data-target="2.7"><small><a class="small" href="#2.7">2.7.<
64396439 - <a href="#insecure-fork-wanted">insecure-fork-wanted</a>
64406440 - <a href="#insecure-setuid-wanted">insecure-setuid-wanted</a>
64416441 - <a href="#issuers-chain-path">issuers-chain-path</a>
6442+ - <a href="#limited-quic">limited-quic</a>
64426443 - <a href="#localpeer">localpeer</a>
64436444 - <a href="#log">log</a>
64446445 - <a href="#log-send-hostname">log-send-hostname</a>
@@ -6448,6 +6449,7 @@ <h2 id="chapter-2.7" data-target="2.7"><small><a class="small" href="#2.7">2.7.<
64486449 - <a href="#lua-prepend-path">lua-prepend-path</a>
64496450 - <a href="#mworker-max-reloads">mworker-max-reloads</a>
64506451 - <a href="#nbthread">nbthread</a>
6452+ - <a href="#no-quic">no-quic</a>
64516453 - <a href="#node">node</a>
64526454 - <a href="#numa-cpu-mapping">numa-cpu-mapping</a>
64536455 - <a href="#pidfile">pidfile</a>
@@ -8775,6 +8777,10 @@ <h2 id="chapter-3.4" data-target="3.4"><small><a class="small" href="#3.4">3.4.<
87758777force attacks. They do not simply salt/hash the clear text password once,
87768778but thousands of times. This can quickly become a major factor in HAProxy's
87778779overall CPU consumption!
8780+
8781+ All passwords are considered normal arguments and are therefor subject to
8782+ regular <a href="#2.2">section 2.2</a> Quoting and escaping. Single quoting passwords is
8783+ therefor recommended.
87788784</pre><div class="separator">
87798785<span class="label label-success">Example:</span>
87808786<pre class="prettyprint">
@@ -8783,16 +8789,16 @@ <h2 id="chapter-3.4" data-target="3.4"><small><a class="small" href="#3.4">3.4.<
87838789 group G2 users xdb,scott
87848790
87858791 user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91
8786- user scott insecure-password elgato
8787- user xdb insecure-password hello
8792+ user scott insecure-password ' elgato'
8793+ user xdb insecure-password ' hello'
87888794
87898795userlist L2
87908796 group G1
87918797 group G2
87928798
87938799 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1
8794- user scott insecure-password elgato groups G1,G2
8795- user xdb insecure-password hello groups G2
8800+ user scott insecure-password ' elgato' groups G1,G2
8801+ user xdb insecure-password ' hello' groups G2
87968802</code></pre>
87978803</div><pre class="text">Please note that both lists are functionally identical.
87988804</pre></div>
@@ -15078,8 +15084,23 @@ <h2 id="chapter-4.2" data-target="4.2"><small><a class="small" href="#4.2">4.2.<
1507815084desirable in these environments as well, to avoid redistributing the traffic
1507915085after every other response.
1508015086
15081- If this option has been enabled in a "defaults" section, it can be disabled
15082- in a specific instance by prepending the "no" keyword before it.
15087+ It may be useful to precise here, which load balancing algorithms are
15088+ considered deterministic. Deterministic algorithms will always select the same
15089+ server for a given client data, assuming the set of available servers has not
15090+ changed. In general, deterministic algorithms involve hasing or lookups on the
15091+ incoming requests to choose the target server. However, this is not always the
15092+ case; "static-rr", for example, can be also considered as deterministic because
15093+ the server choice is based on the server's static weight, making the selection
15094+ predictable. "sticky" algorithm provides deterministic routing for the
15095+ returning clients.
15096+
15097+ As for non-deterministic algorithms, these algorithms select a server based on
15098+ dynamic server state or simple rotation, so two consecutive requests are not
15099+ guaranteed to land on the same server. option prefer-last-server is designed
15100+ specifically for these. roundrobin, leastconn are examples of such algorithms.
15101+
15102+ If this option has been enabled in a "defaults" section, it can be
15103+ disabled in a specific instance by prepending the "no" keyword before it.
1508315104</pre><div class="page-header"><b>See also:</b> "<a href="#option%20http-keep-alive">option http-keep-alive</a>"</div>
1508415105<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
1508515106</pre><div><p> May be used in sections :</p><table class="table table-bordered" border="0" cellspacing="0" cellpadding="0">
@@ -16314,9 +16335,9 @@ <h2 id="chapter-4.2" data-target="4.2"><small><a class="small" href="#4.2">4.2.<
1631416335<code><span class="comment"># statistics admin level depends on the authenticated user</span>
1631516336userlist stats-auth
1631616337 group admin users admin
16317- user admin insecure-password AdMiN123
16338+ user admin insecure-password ' AdMiN123'
1631816339 group readonly users haproxy
16319- user haproxy insecure-password haproxy
16340+ user haproxy insecure-password ' haproxy'
1632016341
1632116342backend stats_auth
1632216343 stats enable
@@ -19598,9 +19619,16 @@ <h2 id="chapter-5.1" data-target="5.1"><small><a class="small" href="#5.1">5.1.<
1959819619</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
1959919620the server's preference is enforced. This option is also available on
1960019621global statement "<a href="#ssl-default-bind-options">ssl-default-bind-options</a>".
19622+
1960119623Note that with OpenSSL >= 1.1.1 ChaCha20-Poly1305 is reprioritized anyway
1960219624(without setting this option), if a ChaCha20-Poly1305 cipher is at the top of
1960319625the client cipher list.
19626+
19627+ When using a dual algorithms setup (RSA + ECDSA), the selection algorithm
19628+ will chose between RSA and ECDSA and will always prioritize ECDSA. Once the
19629+ right certificate is chosen, it will let the SSL library prioritize ciphers,
19630+ curves etc. Meaning this option can't be used to prioritize an RSA
19631+ certificate over an ECDSA one.
1960419632</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
1960519633must be compatible with the mode of the frontend (TCP or HTTP). It must also
1960619634be usable on the frontend side. The list of available protocols is reported
@@ -22195,11 +22223,14 @@ <h3 id="chapter-7.3.1" data-target="7.3.1"><small><a class="small" href="#7.3.1"
2219522223compiled with USE_OPENSSL.
2219622224</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
2219722225by using the <alg> algorithm and the <key> parameter, which should either
22198- hold a secret or a path to a public certificate. Returns 1 in case of
22199- verification success, 0 in case of verification error and a strictly negative
22200- value for any other error. Because of all those non-null error return values,
22201- the result of this converter should never be converted to a boolean. See
22202- below for a full list of the possible return values.
22226+ hold a secret or a path to a public key. The public key should either be in
22227+ the PKCS#1 format (for RSA keys, starting with BEGIN RSA PUBLIC KEY) or SPKI
22228+ format (Subject Public Key Info, starting with BEGIN PUBLIC KEY).
22229+ Returns 1 in case of verification success, 0 in case of verification failure
22230+ and a strictly negative value for any other error. Because of all those
22231+ non-null error return values, the result of this converter should never be
22232+ converted to a boolean. See below for a full list of the possible return
22233+ values.
2220322234
2220422235For now, only JWS tokens using the Compact Serialization format can be
2220522236processed (three dot-separated base64-url encoded strings). All the
@@ -22208,16 +22239,16 @@ <h3 id="chapter-7.3.1" data-target="7.3.1"><small><a class="small" href="#7.3.1"
2220822239
2220922240If the used algorithm is of the HMAC family, <key> should be the secret used
2221022241in the HMAC signature calculation. Otherwise, <key> should be the path to the
22211- public certificate that can be used to validate the token's signature. All
22212- the certificates that might be used to verify JWTs must be known during init
22213- in order to be added into a dedicated certificate cache so that no disk
22214- access is required during runtime. For this reason, any used certificate must
22215- be mentioned explicitly at least once in a jwt_verify call. Passing an
22216- intermediate variable as second parameter is then not advised.
22242+ public key that can be used to validate the token's signature. All the public
22243+ keys that might be used to verify JWTs must be known during init in order to
22244+ be added into a dedicated cache so that no disk access is required during
22245+ runtime. For this reason, any used public key must be mentioned explicitly at
22246+ least once in a jwt_verify call. Passing an intermediate variable as second
22247+ parameter is then not advised.
2221722248
2221822249This converter only verifies the signature of the token and does not perform
2221922250a full JWT validation as specified in <a href="#7.2">section 7.2</a> of RFC7519. We do not
22220- ensure that the header and payload contents are fully valid JSON's once
22251+ ensure that the header and payload contents are fully valid JSONs once
2222122252decoded for instance, and no checks are performed regarding their respective
2222222253contents.
2222322254
@@ -22245,7 +22276,7 @@ <h3 id="chapter-7.3.1" data-target="7.3.1"><small><a class="small" href="#7.3.1"
2224522276http-request set-var(txn.bearer) http_auth_bearer
2224622277http-request set-var(txn.jwt_alg) var(txn.bearer),jwt_header_query('$.alg')
2224722278http-request deny unless { var(txn.jwt_alg) -m str "RS256" }
22248- http-request deny unless { var(txn.bearer),jwt_verify(txn.jwt_alg,"/path/to/crt .pem") 1 }
22279+ http-request deny unless { var(txn.bearer),jwt_verify(txn.jwt_alg,"/path/to/pubkey .pem") 1 }
2224922280</code></pre>
2225022281</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
2225122282"accept-language" header using "<a href="#req.fhdr">req.fhdr</a>". Values with no q-factor have a
@@ -27809,6 +27840,10 @@ <h2 id="chapter-11.1" data-target="11.1"><small><a class="small" href="#11.1">11
2780927840 the FD from the unix socket and uses it as if it were the FD
2781027841 of an accept(). Should be used carefully.
2781127842
27843+ Bugs: This protocol is known to be unreliable on macOS because
27844+ of an issue in the macOS sendmsg(2) implementation. The
27845+ connection might not be accepted correctly.
27846+
2781227847'unix@<path>' following string is considered as a UNIX socket <path>. this
2781327848 prefix is useful to declare an UNIX socket path which don't
2781427849 start by slash '/'.
@@ -27918,7 +27953,7 @@ <h2 id="chapter-11.3" data-target="11.3"><small><a class="small" href="#11.3">11
2791827953 <br>
2791927954 <hr>
2792027955 <div class="text-right">
27921- HAProxy 2.8.15-36 – Configuration Manual<br>
27956+ HAProxy 2.8.15-106 – Configuration Manual<br>
2792227957 <small>, 2025/04/22</small>
2792327958 </div>
2792427959 </div>
0 commit comments