|
2 | 2 | <html lang="en"> |
3 | 3 | <head> |
4 | 4 | <meta charset="utf-8" /> |
5 | | - <title>HAProxy version 3.4-dev12-53 - Configuration Manual</title> |
| 5 | + <title>HAProxy version 3.4-dev13 - Configuration Manual</title> |
6 | 6 | <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" /> |
7 | 7 | <link href="https://raw.githubusercontent.com/thomaspark/bootswatch/v3.3.7/cerulean/bootstrap.min.css" rel="stylesheet" /> |
8 | 8 | <link href="../css/page.css?0.4.2-15" rel="stylesheet" /> |
|
4926 | 4926 | You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br> |
4927 | 4927 | </p> |
4928 | 4928 | <p class="text-right"> |
4929 | | - <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2026/05/19</b></small> |
| 4929 | + <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2026/05/20</b></small> |
4930 | 4930 | </p> |
4931 | 4931 | </div> |
4932 | 4932 | <!-- /.sidebar --> |
|
4937 | 4937 | <div class="text-center"> |
4938 | 4938 | <h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1> |
4939 | 4939 | <h2>Configuration Manual</h2> |
4940 | | - <p><strong>version 3.4-dev12-53</strong></p> |
| 4940 | + <p><strong>version 3.4-dev13</strong></p> |
4941 | 4941 | <p> |
4942 | | - 2026/05/13<br> |
| 4942 | + 2026/05/20<br> |
4943 | 4943 |
|
4944 | 4944 | </p> |
4945 | 4945 | </div> |
@@ -8165,12 +8165,27 @@ <h2 id="chapter-3.1" data-target="3.1"><small><a class="small" href="#3.1">3.1.< |
8165 | 8165 | relative path is used with "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">ca-file<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#ca-file%20%28Bind%20options%29">Bind options</a></li><li><a href="#ca-file%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>", "<a href="#ca-verify-file">ca-verify-file</a>" or "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">crl-file<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#crl-file%20%28Bind%20options%29">Bind options</a></li><li><a href="#crl-file%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" |
8166 | 8166 | directives. Absolute locations specified in "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">ca-file<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#ca-file%20%28Bind%20options%29">Bind options</a></li><li><a href="#ca-file%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>", "<a href="#ca-verify-file">ca-verify-file</a>" and |
8167 | 8167 | "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">crl-file<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#crl-file%20%28Bind%20options%29">Bind options</a></li><li><a href="#crl-file%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" prevail and ignore "<a href="#ca-base">ca-base</a>". |
8168 | | -</pre><a class="anchor" name="chroot"></a><a class="anchor" name="3-chroot"></a><a class="anchor" name="3.1-chroot"></a><a class="anchor" name="chroot (Global section)"></a><a class="anchor" name="chroot (Process management and security)"></a><div class="keyword"><b><a class="anchor" name="chroot"></a><a href="#3.1-chroot">chroot</a></b> <span style="color: #080"><jail dir></span></div><pre class="text">Changes current directory to <jail dir> and performs a chroot() there before |
| 8168 | +</pre><a class="anchor" name="chroot"></a><a class="anchor" name="3-chroot"></a><a class="anchor" name="3.1-chroot"></a><a class="anchor" name="chroot (Global section)"></a><a class="anchor" name="chroot (Process management and security)"></a><div class="keyword"><b><a class="anchor" name="chroot"></a><a href="#3.1-chroot">chroot</a></b> <span style="color: # 800">{ <span style="color: #080"><jail dir> </span> | auto }</span></div><pre class="text">Changes current directory to <jail dir> and performs a chroot() there before |
8169 | 8169 | dropping privileges. This increases the security level in case an unknown |
8170 | 8170 | vulnerability would be exploited, since it would make it very hard for the |
8171 | | -attacker to exploit the system. This only works when the process is started |
8172 | | -with superuser privileges. It is important to ensure that <jail_dir> is both |
8173 | | -empty and non-writable to anyone. |
| 8171 | +attacker to exploit the system. It is important to ensure that <jail dir> |
| 8172 | +is both empty and non-writable to anyone. When the process is started with |
| 8173 | +superuser privileges, the chroot() is performed directly. On Linux, when |
| 8174 | +started unprivileged, haproxy attempts to perform it from inside a new |
| 8175 | +user namespace created with unshare(CLONE_NEWUSER); if that mechanism is |
| 8176 | +unavailable the chroot() will fail with the usual error. |
| 8177 | + |
| 8178 | +As a special case, <jail dir> may be set to "auto", in which case haproxy |
| 8179 | +creates an anonymous temporary directory, unlinks it, and chroots into it. |
| 8180 | +The resulting jail has no name in the filesystem and is empty and read-only, |
| 8181 | +removing the need to prepare a dedicated jail directory. |
| 8182 | + |
| 8183 | +When starting with superuser privileges, a warning will be displayed if no |
| 8184 | +chroot is used, in order to encourage users to always use the mechanism. If |
| 8185 | +for any reason there is a compelling reason not to use chroot (e.g. access to |
| 8186 | +a server via a UNIX socket with an unconvenient path), it remains possible to |
| 8187 | +silence the warning by adding an explicit "chroot /", which has the benefit |
| 8188 | +of being visible in a configuration. |
8174 | 8189 | </pre><a class="anchor" name="close-spread-time"></a><a class="anchor" name="3-close-spread-time"></a><a class="anchor" name="3.1-close-spread-time"></a><a class="anchor" name="close-spread-time (Global section)"></a><a class="anchor" name="close-spread-time (Process management and security)"></a><div class="keyword"><b><a class="anchor" name="close-spread-time"></a><a href="#3.1-close-spread-time">close-spread-time</a></b> <span style="color: #080"><time></span></div><pre class="text">Define a time window during which idle connections and active connections |
8175 | 8190 | closing is spread in case of soft-stop. After a SIGUSR1 is received and the |
8176 | 8191 | grace period is over (if any), the idle connections will all be closed at |
@@ -10867,16 +10882,25 @@ <h2 id="chapter-3.2" data-target="3.2"><small><a class="small" href="#3.2">3.2.< |
10867 | 10882 | <a class="anchor" name="tune.quic.frontend.stream-data-ratio"></a><a class="anchor" name="3-tune.quic.frontend.stream-data-ratio"></a><a class="anchor" name="3.2-tune.quic.frontend.stream-data-ratio"></a><a class="anchor" name="tune.quic.frontend.stream-data-ratio (Global section)"></a><a class="anchor" name="tune.quic.frontend.stream-data-ratio (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.quic.frontend.stream-data-ratio"></a><a href="#3.2-tune.quic.frontend.stream-data-ratio">tune.quic.frontend.stream-data-ratio</a></b> <span style="color: #080"><0..100, in percent></span> <span class="label label-warning">(deprecated)</span></div><pre class="text">This keyword has been deprecated in 3.3 and will be removed in 3.5. It is |
10868 | 10883 | part of the streamlining process apply on QUIC configuration. If used, this |
10869 | 10884 | setting will only be applied on frontend connections. |
10870 | | -</pre><a class="anchor" name="tune.quic.be.stream.max-concurrent"></a><a class="anchor" name="3-tune.quic.be.stream.max-concurrent"></a><a class="anchor" name="3.2-tune.quic.be.stream.max-concurrent"></a><a class="anchor" name="tune.quic.be.stream.max-concurrent (Global section)"></a><a class="anchor" name="tune.quic.be.stream.max-concurrent (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.quic.be.stream.max-concurrent"></a><a href="#3.2-tune.quic.be.stream.max-concurrent">tune.quic.be.stream.max-concurrent</a></b> <span style="color: #080"><number></span></div><a class="anchor" name="tune.quic.fe.stream.max-concurrent"></a><a class="anchor" name="3-tune.quic.fe.stream.max-concurrent"></a><a class="anchor" name="3.2-tune.quic.fe.stream.max-concurrent"></a><a class="anchor" name="tune.quic.fe.stream.max-concurrent (Global section)"></a><a class="anchor" name="tune.quic.fe.stream.max-concurrent (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.quic.fe.stream.max-concurrent"></a><a href="#3.2-tune.quic.fe.stream.max-concurrent">tune.quic.fe.stream.max-concurrent</a></b> <span style="color: #080"><number></span></div><pre class="text">Sets the QUIC initial_max_streams_bidi transport parameter either on frontend |
10871 | | -or backend side. This is the maximum number of bidirectional streams that the |
10872 | | -remote peer will be authorized to open concurrently during the connection |
10873 | | -lifetime. On frontend side, this limits the number of concurrent HTTP/3 |
10874 | | -client requests. |
| 10885 | +</pre><a class="anchor" name="tune.quic.be.stream.max-concurrent"></a><a class="anchor" name="3-tune.quic.be.stream.max-concurrent"></a><a class="anchor" name="3.2-tune.quic.be.stream.max-concurrent"></a><a class="anchor" name="tune.quic.be.stream.max-concurrent (Global section)"></a><a class="anchor" name="tune.quic.be.stream.max-concurrent (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.quic.be.stream.max-concurrent"></a><a href="#3.2-tune.quic.be.stream.max-concurrent">tune.quic.be.stream.max-concurrent</a></b> <span style="color: #080"><number></span></div><a class="anchor" name="tune.quic.fe.stream.max-concurrent"></a><a class="anchor" name="3-tune.quic.fe.stream.max-concurrent"></a><a class="anchor" name="3.2-tune.quic.fe.stream.max-concurrent"></a><a class="anchor" name="tune.quic.fe.stream.max-concurrent (Global section)"></a><a class="anchor" name="tune.quic.fe.stream.max-concurrent (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.quic.fe.stream.max-concurrent"></a><a href="#3.2-tune.quic.fe.stream.max-concurrent">tune.quic.fe.stream.max-concurrent</a></b> <span style="color: #080"><number></span></div><pre class="text">On frontend side, this is used as the value for the advertised |
| 10886 | +initial_max_streams_bidi transport parameter. This is enforced as the maximum |
| 10887 | +number of bidirectional streams that the remote peer will be authorized to |
| 10888 | +open concurrently during the connection lifetime. This effectively limits the |
| 10889 | +number of concurrent HTTP/3 client requests. |
10875 | 10890 |
|
10876 | 10891 | The default value is 100. Note that if you reduces it, it can restrict the |
10877 | 10892 | buffering capabilities of streams on receive, which would result in poor |
10878 | 10893 | upload throughput. It can be corrected by increasing the QUIC stream rxbuf |
10879 | 10894 | connection setting. |
| 10895 | + |
| 10896 | +On backend side, this is enforced locally by haproxy to limit the number of |
| 10897 | +concurrent requests multiplexed over a single connection. This may be further |
| 10898 | +restricted by the peer flow control. It may be necessary to reduce the |
| 10899 | +default value of 100 to improve a site's responsiveness at the expense of a |
| 10900 | +higher number of opened backend connections. Similarly to the frontend side, |
| 10901 | +this setting also directly impacts the Rx buffering capability, this time |
| 10902 | +though limiting the HTTP download capacity. QUIC stream rxbuf setting can be |
| 10903 | +increased when dealing mostly with HTTP responses larger than "<a href="#tune.bufsize">tune.bufsize</a>". |
10880 | 10904 | </pre><div class="page-header"><b>See also:</b> "<a href="#tune.quic.be.stream.rxbuf">tune.quic.be.stream.rxbuf</a>", "<a href="#tune.quic.fe.stream.rxbuf">tune.quic.fe.stream.rxbuf</a>", "<a href="#tune.quic.be.stream.data-ratio">tune.quic.be.stream.data-ratio</a>", "<a href="#tune.quic.fe.stream.data-ratio">tune.quic.fe.stream.data-ratio</a>"</div> |
10881 | 10905 | <a class="anchor" name="tune.quic.fe.stream.max-total"></a><a class="anchor" name="3-tune.quic.fe.stream.max-total"></a><a class="anchor" name="3.2-tune.quic.fe.stream.max-total"></a><a class="anchor" name="tune.quic.fe.stream.max-total (Global section)"></a><a class="anchor" name="tune.quic.fe.stream.max-total (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.quic.fe.stream.max-total"></a><a href="#3.2-tune.quic.fe.stream.max-total">tune.quic.fe.stream.max-total</a></b> <span style="color: #080"><number></span></div><pre class="text">Sets the maximum number of requests that can be handled by a single QUIC |
10882 | 10906 | connection. Once this total is reached, the connection will be gracefully |
@@ -11198,6 +11222,16 @@ <h2 id="chapter-3.2" data-target="3.2"><small><a class="small" href="#3.2">3.2.< |
11198 | 11222 | use lower values (120 to 200) to support 1.2 to 2 streams per connection on |
11199 | 11223 | average at full load. |
11200 | 11224 |
|
| 11225 | +Contrary to HTTP/2, QUIC is capable to dynamically adjust the number of |
| 11226 | +concurrent streams during the connection lifetime. However, QUIC flow control |
| 11227 | +is stricter than HTTP/2, thus it is preferable when using it to specify |
| 11228 | +values big enough to prevent extra latency on the connection. There is also a |
| 11229 | +limitation for QUIC listeners with enabled 0-RTT. In this case, the initial |
| 11230 | +value advertised to the peer will ignore stream elasticity and instead rely |
| 11231 | +solely on the "<a href="#tune.quic.fe.stream.max-concurrent">tune.quic.fe.stream.max-concurrent</a>" setting. However, the |
| 11232 | +stream elasticity principle will still be effective past this initial |
| 11233 | +annoucement during the connection lifetime. |
| 11234 | + |
11201 | 11235 | Monitoring the total number of active streams on backends, including queues, |
11202 | 11236 | provides a practical indicator of a sustainable target load and helps avoid |
11203 | 11237 | over-provisioning. |
@@ -35642,8 +35676,8 @@ <h2 id="chapter-12.9" data-target="12.9"><small><a class="small" href="#12.9">12 |
35642 | 35676 | <br> |
35643 | 35677 | <hr> |
35644 | 35678 | <div class="text-right"> |
35645 | | - HAProxy 3.4-dev12-53 – Configuration Manual<br> |
35646 | | - <small>, 2026/05/13</small> |
| 35679 | + HAProxy 3.4-dev13 – Configuration Manual<br> |
| 35680 | + <small>, 2026/05/20</small> |
35647 | 35681 | </div> |
35648 | 35682 | </div> |
35649 | 35683 | <!-- /.col-lg-12 --> |
|
0 commit comments