Skip to content

Commit a99893d

Browse files
author
HAProxy Community
committed
Update docs for 2.9
1 parent b8fed0e commit a99893d

File tree

3 files changed

+109
-52
lines changed

3 files changed

+109
-52
lines changed

docs/2.9/configuration.html

Lines changed: 101 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<html lang="en">
33
<head>
44
<meta charset="utf-8" />
5-
<title>HAProxy version 2.9.12-2 - Configuration Manual</title>
5+
<title>HAProxy version 2.9.12-27 - 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" />
@@ -4145,7 +4145,7 @@
41454145
You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
41464146
</p>
41474147
<p class="text-right">
4148-
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/11/08</b></small>
4148+
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/11/22</b></small>
41494149
</p>
41504150
</div>
41514151
<!-- /.sidebar -->
@@ -4156,7 +4156,7 @@
41564156
<div class="text-center">
41574157
<h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
41584158
<h2>Configuration Manual</h2>
4159-
<p><strong>version 2.9.12-2</strong></p>
4159+
<p><strong>version 2.9.12-27</strong></p>
41604160
<p>
41614161
2024/11/08<br>
41624162

@@ -5626,7 +5626,7 @@ <h3 id="chapter-1.3.1" data-target="1.3.1"><small><a class="small" href="#1.3.1"
56265626
It is mostly used with GET requests sent to dynamic scripts and is very
56275627
specific to the language, framework or application in use.
56285628

5629-
HTTP/3 and HTTP/3 do not convey a version information with the request, so the
5629+
HTTP/2 and HTTP/3 do not convey a version information with the request, so the
56305630
version is assumed to be the same as the one of the underlying protocol (i.e.
56315631
&quot;HTTP/2&quot;). In addition, these protocols do not send a request line as one part,
56325632
but split it into individual fields called &quot;pseudo-headers&quot;, whose name start
@@ -6206,6 +6206,54 @@ <h2 id="chapter-2.4" data-target="2.4"><small><a class="small" href="#2.4">2.4.<
62066206
- expressions combined with a logical OR ('||'), which will be evaluated
62076207
from right to left until one returns true
62086208

6209+
The same line tokenizer and argument parser are used as for the rest of the
6210+
configuration language. Words are split around consecutive series of one or
6211+
more unquoted spaces or tabs, and are reassembled together using a single space
6212+
to delimit them before evaluation, in order to save the user from having to
6213+
quote the entire line. But this also means that spaces surrounding commas or
6214+
parenthesis are definitely part of the value, which is not always expected.
6215+
For example, the expression below:
6216+
6217+
.if defined( HAPROXY_MWORKER )
6218+
6219+
will test for the existence of variable &quot; HAPROXY_MWORKER &quot; (with spaces),
6220+
and this one:
6221+
6222+
.if streq(&quot;$ENABLE_SSL&quot;, 1)
6223+
6224+
will compare the environment variable &quot;ENABLE_SSL&quot; to the value &quot; 1&quot; (with a
6225+
single leading space). The reason is the line is first split into words like
6226+
this:
6227+
6228+
.if streq(&quot;$ENABLE_SSL&quot;, 1)
6229+
|---|--------------------| |--|
6230+
1 2 3
6231+
6232+
then the weak quoting is applied and environment variable &quot;$ENABLE_SSL&quot; is
6233+
resolved (let's say for example that ENABLE_SSL=0), and finally the words are
6234+
reassembled into a single string by placing a single space between the words:
6235+
6236+
.if streq(0, 1)
6237+
|---|-------|--|
6238+
1 2 3
6239+
6240+
and only then it is parsed as a single expression. The space that was inserted
6241+
between the comma and &quot;1&quot; is still part of the argument value, making this
6242+
argument &quot; 1&quot;:
6243+
6244+
.if streq(0, 1)
6245+
|---|-----|-|--|
6246+
\ \ \ \_ argument2: &quot; 1&quot;
6247+
\ \ \___ argument1: &quot;0&quot;
6248+
\ \_______ function: &quot;streq&quot;
6249+
\___________ directive: &quot;.if&quot;
6250+
6251+
It's visible here that even if ENABLE_SSL had been equal to &quot;1&quot;, it wouldn't
6252+
have matched &quot; 1&quot; since the string would differ by one space.
6253+
6254+
Note: as explained in section &quot;2.2. Quoting and escaping&quot;, a good rule of thumb
6255+
is to never insert unneeded spaces inside expressions.
6256+
62096257
Note that like in other languages, the AND operator has precedence over the OR
62106258
operator, so that &quot;A &amp;&amp; B || C &amp;&amp; D&quot; evalues as &quot;(A &amp;&amp; B) || (C &amp;&amp; D)&quot;.
62116259

@@ -6220,7 +6268,8 @@ <h2 id="chapter-2.4" data-target="2.4"><small><a class="small" href="#2.4">2.4.<
62206268

62216269
- streq(&lt;str1&gt;,&lt;str2&gt;) : returns true only if the two strings are equal
62226270
- strneq(&lt;str1&gt;,&lt;str2&gt;) : returns true only if the two strings differ
6223-
- strstr(&lt;str1&gt;,&lt;str2&gt;) : returns true only if the second string is found in the first one
6271+
- strstr(&lt;str1&gt;,&lt;str2&gt;) : returns true only if the second string is found in
6272+
the first one.
62246273

62256274
- version_atleast(&lt;ver&gt;): returns true if the current haproxy version is
62266275
at least as recent as &lt;ver&gt; otherwise false. The
@@ -8154,15 +8203,22 @@ <h2 id="chapter-3.2" data-target="3.2"><small><a class="small" href="#3.2">3.2.<
81548203
'log ... len yyy' parameter. Your syslog daemon may also need specific
81558204
configuration directives too.
81568205
The default value is 1024.
8157-
</pre><a class="anchor" name="tune.http.maxhdr"></a><a class="anchor" name="3-tune.http.maxhdr"></a><a class="anchor" name="3.2-tune.http.maxhdr"></a><a class="anchor" name="tune.http.maxhdr (Global parameters)"></a><a class="anchor" name="tune.http.maxhdr (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.http.maxhdr"></a><a href="#3.2-tune.http.maxhdr">tune.http.maxhdr</a></b> <span style="color: #080">&lt;number&gt;</span></div><pre class="text">Sets the maximum number of headers in a request. When a request comes with a
8158-
number of headers greater than this value (including the first line), it is
8159-
rejected with a &quot;400 Bad Request&quot; status code. Similarly, too large responses
8160-
are blocked with &quot;502 Bad Gateway&quot;. The default value is 101, which is enough
8161-
for all usages, considering that the widely deployed Apache server uses the
8162-
same limit. It can be useful to push this limit further to temporarily allow
8163-
a buggy application to work by the time it gets fixed. The accepted range is
8164-
1..32767. Keep in mind that each new header consumes 32bits of memory for
8165-
each stream, so don't push this limit too high.
8206+
</pre><a class="anchor" name="tune.http.maxhdr"></a><a class="anchor" name="3-tune.http.maxhdr"></a><a class="anchor" name="3.2-tune.http.maxhdr"></a><a class="anchor" name="tune.http.maxhdr (Global parameters)"></a><a class="anchor" name="tune.http.maxhdr (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.http.maxhdr"></a><a href="#3.2-tune.http.maxhdr">tune.http.maxhdr</a></b> <span style="color: #080">&lt;number&gt;</span></div><pre class="text">Sets the maximum number of headers allowed in received HTTP messages. When a
8207+
message comes with a number of headers greater than this value (including the
8208+
first line), it is rejected with a &quot;400 Bad Request&quot; status code for a
8209+
request, or &quot;502 Bad Gateway&quot; for a response. The default value is 101, which
8210+
is enough for all usages, considering that the widely deployed Apache server
8211+
uses the same limit. It can be useful to push this limit further to
8212+
temporarily allow a buggy application to work by the time it gets fixed. The
8213+
accepted range is 1..32767. Keep in mind that each new header consumes 32bits
8214+
of memory for each stream, so don't push this limit too high.
8215+
8216+
Note that HTTP/1.1 is a text protocol, so there is no special limit when the
8217+
message is sent. The limit during the message parsing is sufficient. HTTP/2
8218+
and HTTP/3 are binary protocols and require an encoding step. A limit is set
8219+
too when headers are encoded to comply to limitation imposed by the
8220+
protocols. This limit is large enough but not documented on purpose. The same
8221+
limit is applied on the first steps of the decoding for the same reason.
81668222
</pre><a class="anchor" name="tune.idle-pool.shared"></a><a class="anchor" name="3-tune.idle-pool.shared"></a><a class="anchor" name="3.2-tune.idle-pool.shared"></a><a class="anchor" name="tune.idle-pool.shared (Global parameters)"></a><a class="anchor" name="tune.idle-pool.shared (Performance tuning)"></a><div class="keyword"><b><a class="anchor" name="tune.idle-pool.shared"></a><a href="#3.2-tune.idle-pool.shared">tune.idle-pool.shared</a></b> <span style="color: #800">{ on | off }</span></div><pre class="text">Enables ('on') or disables ('off') sharing of idle connection pools between
81678223
threads for a same server. The default is to share them between threads in
81688224
order to minimize the number of persistent connections to a server, and to
@@ -23698,6 +23754,7 @@ <h3 id="chapter-7.3.2" data-target="7.3.2"><small><a class="small" href="#7.3.2"
2369823754
<tr><td ><a href="#7-txn.sess_term_state">txn.sess_term_state</a></td><td >string</td></tr>
2369923755
<tr><td ><a href="#7-uuid">uuid([&lt;version&gt;])</a></td><td >string</td></tr>
2370023756
<tr><td ><a href="#7-var">var(&lt;var-name&gt;[,&lt;default&gt;])</a></td><td >undefined</td></tr>
23757+
<tr><td ><a href="#7-wait_end">wait_end</a></td><td >boolean</td></tr>
2370123758
</table><pre class="text">Detailed list:
2370223759
</pre><a class="anchor" name="act_conn"></a><a class="anchor" name="7-act_conn"></a><a class="anchor" name="7.3.2-act_conn"></a><a class="anchor" name="act_conn (Using ACLs and fetching samples)"></a><a class="anchor" name="act_conn (Fetching samples from internal states)"></a><div class="keyword"><b><a class="anchor" name="act_conn"></a><a href="#7.3.2-act_conn">act_conn</a></b> : integer</div><pre class="text">Returns the total number of active concurrent connections on the process.
2370323760
</pre><a class="anchor" name="acl"></a><a class="anchor" name="7-acl"></a><a class="anchor" name="7.3.2-acl"></a><a class="anchor" name="acl (Using ACLs and fetching samples)"></a><a class="anchor" name="acl (Fetching samples from internal states)"></a><div class="keyword"><b><a class="anchor" name="acl"></a><a href="#7.3.2-acl">acl</a></b>(<span style="color: #008">[!]</span><span style="color: #080">&lt;name&gt;</span><span style="color: #008">[,...]</span>) : boolean</div><pre class="text">Returns true if the evaluation of all the named ACL(s) is true, otherwise
@@ -24086,7 +24143,30 @@ <h3 id="chapter-7.3.2" data-target="7.3.2"><small><a class="small" href="#7.3.2"
2408624143
&quot;res&quot; : the variable is shared only during response processing.
2408724144
This prefix is followed by a name. The separator is a '.'. The name may only
2408824145
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
24089-
</pre></div>
24146+
</pre><a class="anchor" name="wait_end"></a><a class="anchor" name="7-wait_end"></a><a class="anchor" name="7.3.2-wait_end"></a><a class="anchor" name="wait_end (Using ACLs and fetching samples)"></a><a class="anchor" name="wait_end (Fetching samples from internal states)"></a><div class="keyword"><b><a class="anchor" name="wait_end"></a><a href="#7.3.2-wait_end">wait_end</a></b> : boolean</div><pre class="text">This fetch either returns true when the inspection period is over, or does
24147+
not fetch. It is only used in ACLs, in conjunction with content analysis to
24148+
avoid returning a wrong verdict early. It may also be used to delay some
24149+
actions, such as a delayed reject for some special addresses. Since it either
24150+
stops the rules evaluation or immediately returns true, it is recommended to
24151+
use this acl as the last one in a rule. Please note that the default ACL
24152+
&quot;WAIT_END&quot; is always usable without prior declaration. This test was designed
24153+
to be used with TCP request content inspection.
24154+
</pre><div class="separator">
24155+
<span class="label label-success">Examples :</span>
24156+
<pre class="prettyprint">
24157+
<code><span class="comment"># delay every incoming request by 2 seconds</span>
24158+
tcp-request inspect-delay 2s
24159+
tcp-request content accept if WAIT_END
24160+
24161+
<span class="comment"># don't immediately tell bad guys they are rejected</span>
24162+
tcp-request inspect-delay 10s
24163+
acl goodguys src 10.0.0.0/24
24164+
acl badguys src 10.0.1.0/24
24165+
tcp-request content accept if goodguys
24166+
tcp-request content reject if badguys WAIT_END
24167+
tcp-request content reject
24168+
</code></pre>
24169+
</div></div>
2409024170
<a class="anchor" id="7.3.3" name="7.3.3"></a>
2409124171
<h3 id="chapter-7.3.3" data-target="7.3.3"><small><a class="small" href="#7.3.3">7.3.3.</a></small> Fetching samples at Layer 4</h3>
2409224172
<div><pre class="text">The layer 4 usually describes just the transport layer which in HAProxy is
@@ -25785,7 +25865,6 @@ <h3 id="chapter-7.3.5" data-target="7.3.5"><small><a class="small" href="#7.3.5"
2578525865
<tr><td ><a href="#7-res.payload_lv">res.payload_lv(&lt;offset1&gt;,&lt;length&gt;[,&lt;offset2&gt;])</a></td><td >binary</td></tr>
2578625866
<tr><td ><a href="#7-res.ssl_hello_type">res.ssl_hello_type</a></td><td >integer</td></tr>
2578725867
<tr><td ><a href="#7-rep_ssl_hello_type">rep_ssl_hello_type</a></td><td >integer</td></tr>
25788-
<tr><td ><a href="#7-wait_end">wait_end</a></td><td >boolean</td></tr>
2578925868
</table><pre class="text">Detailed list:
2579025869
</pre><a class="anchor" name="bs.id"></a><a class="anchor" name="7-bs.id"></a><a class="anchor" name="7.3.5-bs.id"></a><a class="anchor" name="bs.id (Using ACLs and fetching samples)"></a><a class="anchor" name="bs.id (Fetching samples from buffer contents (Layer 6))"></a><div class="keyword"><b><a class="anchor" name="bs.id"></a><a href="#7.3.5-bs.id">bs.id</a></b> : integer</div><pre class="text">Returns the multiplexer's stream ID on the server side. It is the
2579125870
multiplexer's responsibility to return the appropriate information.
@@ -26013,30 +26092,7 @@ <h3 id="chapter-7.3.5" data-target="7.3.5"><small><a class="small" href="#7.3.5"
2601326092
SSL data layer, so this will not work with &quot;<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">server<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#server%20%28Peers%29">Peers</a></li><li><a href="#server%20%28Rings%29">Rings</a></li><li><a href="#server%20%28Alphabetically%20sorted%20keywords%20reference%29">Alphabetically sorted keywords reference</a></li></ul></span>&quot; lines having the &quot;<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">ssl<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#ssl%20%28Bind%20options%29">Bind options</a></li><li><a href="#ssl%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>&quot;
2601426093
option. This is mostly used in ACL to detect presence of an SSL hello message
2601526094
that is supposed to contain an SSL session ID usable for stickiness.
26016-
</pre><a class="anchor" name="wait_end"></a><a class="anchor" name="7-wait_end"></a><a class="anchor" name="7.3.5-wait_end"></a><a class="anchor" name="wait_end (Using ACLs and fetching samples)"></a><a class="anchor" name="wait_end (Fetching samples from buffer contents (Layer 6))"></a><div class="keyword"><b><a class="anchor" name="wait_end"></a><a href="#7.3.5-wait_end">wait_end</a></b> : boolean</div><pre class="text">This fetch either returns true when the inspection period is over, or does
26017-
not fetch. It is only used in ACLs, in conjunction with content analysis to
26018-
avoid returning a wrong verdict early. It may also be used to delay some
26019-
actions, such as a delayed reject for some special addresses. Since it either
26020-
stops the rules evaluation or immediately returns true, it is recommended to
26021-
use this acl as the last one in a rule. Please note that the default ACL
26022-
&quot;WAIT_END&quot; is always usable without prior declaration. This test was designed
26023-
to be used with TCP request content inspection.
26024-
</pre><div class="separator">
26025-
<span class="label label-success">Examples :</span>
26026-
<pre class="prettyprint">
26027-
<code><span class="comment"># delay every incoming request by 2 seconds</span>
26028-
tcp-request inspect-delay 2s
26029-
tcp-request content accept if WAIT_END
26030-
26031-
<span class="comment"># don't immediately tell bad guys they are rejected</span>
26032-
tcp-request inspect-delay 10s
26033-
acl goodguys src 10.0.0.0/24
26034-
acl badguys src 10.0.1.0/24
26035-
tcp-request content accept if goodguys
26036-
tcp-request content reject if badguys WAIT_END
26037-
tcp-request content reject
26038-
</code></pre>
26039-
</div></div>
26095+
</pre></div>
2604026096
<a class="anchor" id="7.3.6" name="7.3.6"></a>
2604126097
<h3 id="chapter-7.3.6" data-target="7.3.6"><small><a class="small" href="#7.3.6">7.3.6.</a></small> Fetching HTTP samples (Layer 7)</h3>
2604226098
<div><pre class="text">It is possible to fetch samples from HTTP contents, requests and responses.
@@ -27990,9 +28046,10 @@ <h2 id="chapter-8.4" data-target="8.4"><small><a class="small" href="#8.4">8.4.<
2799028046
instance during a POST request, the time already runs, and this can distort
2799128047
apparent response time. For this reason, it's generally wise not to trust
2799228048
too much this field for POST requests initiated from clients behind an
27993-
untrusted network. A value of &quot;-1&quot; here means that the last the response
27994-
header (empty line) was never seen, most likely because the server timeout
27995-
stroke before the server managed to process the request.
28049+
untrusted network. A value of &quot;-1&quot; here means that the last response header
28050+
(empty line) was never seen, most likely because the server timeout stroke
28051+
before the server managed to process the request or because the server
28052+
returned an invalid response.
2799628053

2799728054
This timer is named %Tr as a log-format tag, and res.timer.hdr as a
2799828055
sample fetch.
@@ -29379,7 +29436,7 @@ <h2 id="chapter-11.3" data-target="11.3"><small><a class="small" href="#11.3">11
2937929436
<br>
2938029437
<hr>
2938129438
<div class="text-right">
29382-
HAProxy 2.9.12-2 &ndash; Configuration Manual<br>
29439+
HAProxy 2.9.12-27 &ndash; Configuration Manual<br>
2938329440
<small>, 2024/11/08</small>
2938429441
</div>
2938529442
</div>

docs/2.9/intro.html

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<html lang="en">
33
<head>
44
<meta charset="utf-8" />
5-
<title>HAProxy version 2.9.12-2 - Starter Guide</title>
5+
<title>HAProxy version 2.9.12-27 - Starter Guide</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" />
@@ -484,7 +484,7 @@
484484
You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
485485
</p>
486486
<p class="text-right">
487-
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/11/08</b></small>
487+
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/11/22</b></small>
488488
</p>
489489
</div>
490490
<!-- /.sidebar -->
@@ -495,7 +495,7 @@
495495
<div class="text-center">
496496
<h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
497497
<h2>Starter Guide</h2>
498-
<p><strong>version 2.9.12-2</strong></p>
498+
<p><strong>version 2.9.12-27</strong></p>
499499
<p>
500500
<br>
501501

@@ -2515,7 +2515,7 @@ <h2 id="chapter-4.4" data-target="4.4"><small><a class="small" href="#4.4">4.4.<
25152515
<br>
25162516
<hr>
25172517
<div class="text-right">
2518-
HAProxy 2.9.12-2 &ndash; Starter Guide<br>
2518+
HAProxy 2.9.12-27 &ndash; Starter Guide<br>
25192519
<small>, </small>
25202520
</div>
25212521
</div>

0 commit comments

Comments
 (0)