Skip to content

Commit

Permalink
Update docs for dev
Browse files Browse the repository at this point in the history
  • Loading branch information
HAProxy Community committed Apr 27, 2024
1 parent 82dca3d commit b451ddc
Show file tree
Hide file tree
Showing 3 changed files with 103 additions and 17 deletions.
41 changes: 37 additions & 4 deletions docs/dev/configuration.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>HAProxy version 3.0-dev8-21 - Configuration Manual</title>
<title>HAProxy version 3.0-dev8-81 - Configuration Manual</title>
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" />
<link href="https://raw.githubusercontent.com/thomaspark/bootswatch/v3.3.7/cerulean/bootstrap.min.css" rel="stylesheet" />
<link href="../css/page.css?0.4.2-15" rel="stylesheet" />
Expand Down Expand Up @@ -3686,6 +3686,8 @@

<a class="list-group-item" href="#stats uri">stats uri</a>

<a class="list-group-item" href="#stats-file">stats-file</a>

<a class="list-group-item" href="#status">status</a>

<a class="list-group-item" href="#stick (Alphabetically sorted keywords reference)">stick (Alphabetically sorted keywords reference)</a>
Expand Down Expand Up @@ -4244,7 +4246,7 @@
You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
</p>
<p class="text-right">
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/04/24</b></small>
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/04/26</b></small>
</p>
</div>
<!-- /.sidebar -->
Expand All @@ -4255,7 +4257,7 @@
<div class="text-center">
<h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
<h2>Configuration Manual</h2>
<p><strong>version 3.0-dev8-21</strong></p>
<p><strong>version 3.0-dev8-81</strong></p>
<p>
2024/04/19<br>

Expand Down Expand Up @@ -6612,6 +6614,7 @@ <h2 id="chapter-2.8" data-target="2.8"><small><a class="small" href="#2.8">2.8.<
- <a href="#ssl-server-verify">ssl-server-verify</a>
- <a href="#ssl-skip-self-issued-ca">ssl-skip-self-issued-ca</a>
- <a href="#stats">stats</a>
- <a href="#stats-file">stats-file</a>
- <a href="#strict-limits">strict-limits</a>
- <a href="#uid">uid</a>
- <a href="#ulimit-n">ulimit-n</a>
Expand Down Expand Up @@ -7788,6 +7791,9 @@ <h2 id="chapter-3.1" data-target="3.1"><small><a class="small" href="#3.1">3.1.<
</pre><a class="anchor" name="stats"></a><a class="anchor" name="3-stats"></a><a class="anchor" name="3.1-stats"></a><a class="anchor" name="stats (Global parameters)"></a><a class="anchor" name="stats (Process management and security)"></a><a class="anchor" name="stats timeout"></a><a class="anchor" name="3-stats timeout"></a><a class="anchor" name="3.1-stats timeout"></a><a class="anchor" name="stats timeout (Global parameters)"></a><a class="anchor" name="stats timeout (Process management and security)"></a><div class="keyword"><b><a class="anchor" name="stats timeout"></a><a href="#3.1-stats%20timeout">stats timeout</a></b> <span style="color: #080">&lt;timeout, in milliseconds&gt;</span></div><pre class="text">The default timeout on the stats socket is set to 10 seconds. It is possible
to change this value with &quot;<a href="#stats%20timeout">stats timeout</a>&quot;. The value must be passed in
milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.
</pre><a class="anchor" name="stats-file"></a><a class="anchor" name="3-stats-file"></a><a class="anchor" name="3.1-stats-file"></a><a class="anchor" name="stats-file (Global parameters)"></a><a class="anchor" name="stats-file (Process management and security)"></a><div class="keyword"><b><a class="anchor" name="stats-file"></a><a href="#3.1-stats-file">stats-file</a></b> <span style="color: #080">&lt;path&gt;</span></div><pre class="text">Path to a generated haproxy stats-file. On startup haproxy will preload the
values to its internal counters. Use the CLI command &quot;dump stats-file&quot; to
produce such stats-file. See the management manual for more details.
</pre><a class="anchor" name="strict-limits"></a><a class="anchor" name="3-strict-limits"></a><a class="anchor" name="3.1-strict-limits"></a><a class="anchor" name="strict-limits (Global parameters)"></a><a class="anchor" name="strict-limits (Process management and security)"></a><div class="keyword"><b><a class="anchor" name="strict-limits"></a><a href="#3.1-strict-limits">strict-limits</a></b></div><pre class="text">Makes process fail at startup when a setrlimit fails. HAProxy tries to set the
best setrlimit according to what has been calculated. If it fails, it will
emit a warning. This option is here to guarantee an explicit failure of
Expand Down Expand Up @@ -28273,13 +28279,40 @@ <h3 id="chapter-8.2.6" data-target="8.2.6"><small><a class="small" href="#8.2.6"
* X: hexadecimal representation (IPs, Ports, %Ts, %rt, %pid)
* E: escape characters '&quot;', '\' and ']' in a string with '\' as prefix
(intended purpose is for the RFC5424 structured-data log formats)
* bin: try to preserve binary data, this can be useful with sample
expressions that output binary data in order to preserve the original
data. Be careful however, because it can obviously generate non-
printable chars, including NULL-byte, which most syslog endpoints
don't expect. Thus it is mainly intended for use with set-var-fmt,
rings and binary-capable log endpoints.
This option can only be set globally (with %o), it will be ignored
if set on an individual node's options.
* json: automatically encode value in JSON format
(when set globally, only named format variables are considered)
Incomplete numerical values (e.g.: '%B' when logasap is used),
which are normally prefixed with '+' without encoding, will be
encoded as-is. Also, '+E' option will be ignored.
* cbor: automatically encode value in CBOR format
(when set globally, only named format variables are considered)
By default, cbor encoded data is represented in HEX form so
that it remains printable on stdout an can be used with usual
syslog endpoints.
As with json encoding, incomplete numerical values will be encoded
as-is and '+E' option will be ignored.
When combined with '+bin' option, it will directly generate raw
binary CBOR payload. Be careful, because it will obviously generate
non-printable chars, thus it is mainly intented for use with
set-var-fmt, rings and binary-capable log endpoints.
</pre><div class="separator">
<span class="label label-success">Example:</span>
<pre class="prettyprint">
<code>log-format %T\ %t\ Some\ Text
log-format %{+Q}o\ %t\ %s\ %{-Q}r

log-format-sd %{+Q,+E}o\ [exampleSDID@1234\ header=%[capture.req.hdr(0)]]

log-format &quot;%{+json}o %(request)r %(custom_expr)[str(custom)]&quot;
log-format &quot;%{+cbor}o %(request)r %(custom_expr)[str(custom)]&quot;
</code></pre>
</div><pre class="text">Please refer to the table below for currently defined variables :

Expand Down Expand Up @@ -30036,7 +30069,7 @@ <h2 id="chapter-11.3" data-target="11.3"><small><a class="small" href="#11.3">11
<br>
<hr>
<div class="text-right">
HAProxy 3.0-dev8-21 &ndash; Configuration Manual<br>
HAProxy 3.0-dev8-81 &ndash; Configuration Manual<br>
<small>, 2024/04/19</small>
</div>
</div>
Expand Down
8 changes: 4 additions & 4 deletions docs/dev/intro.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>HAProxy version 3.0-dev8-21 - Starter Guide</title>
<title>HAProxy version 3.0-dev8-81 - Starter Guide</title>
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" />
<link href="https://raw.githubusercontent.com/thomaspark/bootswatch/v3.3.7/cerulean/bootstrap.min.css" rel="stylesheet" />
<link href="../css/page.css?0.4.2-15" rel="stylesheet" />
Expand Down Expand Up @@ -484,7 +484,7 @@
You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
</p>
<p class="text-right">
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/04/24</b></small>
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/04/26</b></small>
</p>
</div>
<!-- /.sidebar -->
Expand All @@ -495,7 +495,7 @@
<div class="text-center">
<h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
<h2>Starter Guide</h2>
<p><strong>version 3.0-dev8-21</strong></p>
<p><strong>version 3.0-dev8-81</strong></p>
<p>
<br>

Expand Down Expand Up @@ -2515,7 +2515,7 @@ <h2 id="chapter-4.4" data-target="4.4"><small><a class="small" href="#4.4">4.4.<
<br>
<hr>
<div class="text-right">
HAProxy 3.0-dev8-21 &ndash; Starter Guide<br>
HAProxy 3.0-dev8-81 &ndash; Starter Guide<br>
<small>, </small>
</div>
</div>
Expand Down
71 changes: 62 additions & 9 deletions docs/dev/management.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>HAProxy version 3.0-dev8-21 - Management Guide</title>
<title>HAProxy version 3.0-dev8-81 - Management Guide</title>
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" />
<link href="https://raw.githubusercontent.com/thomaspark/bootswatch/v3.3.7/cerulean/bootstrap.min.css" rel="stylesheet" />
<link href="../css/page.css?0.4.2-15" rel="stylesheet" />
Expand Down Expand Up @@ -186,6 +186,17 @@



<tr>
<td><small>9.5.</small></td>
<td>
<div class="tab">
<a href="#9.5">Stats-file</a>
</div>
<td>
</tr>



<tr>
<td><br><b><small>10.</small></b></td>
<td>
Expand Down Expand Up @@ -328,6 +339,10 @@

<a class="list-group-item" href="#disable server">disable server</a>

<a class="list-group-item" href="#dump">dump</a>

<a class="list-group-item" href="#dump stats-file">dump stats-file</a>

</div> <!-- /letter -->
<div class="letter" id="letter-E"><h4>E</h4>

Expand Down Expand Up @@ -625,7 +640,7 @@
You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br>
</p>
<p class="text-right">
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/04/24</b></small>
<small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2024/04/26</b></small>
</p>
</div>
<!-- /.sidebar -->
Expand All @@ -636,7 +651,7 @@
<div class="text-center">
<h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1>
<h2>Management Guide</h2>
<p><strong>version 3.0-dev8-21</strong></p>
<p><strong>version 3.0-dev8-81</strong></p>
<p>
<br>

Expand Down Expand Up @@ -796,6 +811,17 @@ <h1 id="chapter-summary" data-target="summary">Summary</h1>



<tr>
<td><small>9.5.</small></td>
<td>
<div class="tab">
<a href="#9.5">Stats-file</a>
</div>
<td>
</tr>



<tr>
<td><br><b><small>10.</small></b></td>
<td>
Expand Down Expand Up @@ -1258,11 +1284,16 @@ <h1 id="chapter-summary" data-target="summary">Summary</h1>
-x &lt;unix_socket&gt; : connect to the specified socket and try to retrieve any
listening sockets from the old process, and use them instead of trying to
bind new ones. This is useful to avoid missing any new connection when
reloading the configuration on Linux. The capability must be enable on the
stats socket using &quot;expose-fd listeners&quot; in your configuration.
In master-worker mode, the master will use this option upon a reload with
the &quot;sockpair@&quot; syntax, which allows the master to connect directly to a
worker without using stats socket declared in the configuration.
reloading the configuration on Linux.

Without master-worker mode, the capability must be enable on the stats
socket using &quot;expose-fd listeners&quot; in your configuration.

In master-worker mode, it does not need &quot;expose-fd listeners&quot;, the master
will use automatically this option upon a reload with the &quot;sockpair@&quot;
syntax, which allows the master to connect directly to a worker without using
any stats socket declared in the configuration. If you want to disable this,
you can pass -x /dev/null.

A safe way to start HAProxy from an init file consists in forcing the daemon
mode, storing existing pids to a pid file and using this pid file to notify
Expand Down Expand Up @@ -2785,6 +2816,8 @@ <h2 id="chapter-9.3" data-target="9.3"><small><a class="small" href="#9.3">9.3.<

This command is restricted and can only be issued on sockets configured for
level &quot;admin&quot;.
</pre><a class="anchor" name="dump"></a><a class="anchor" name="9-dump"></a><a class="anchor" name="9.3-dump"></a><a class="anchor" name="dump (Statistics and monitoring)"></a><a class="anchor" name="dump (Unix Socket commands)"></a><a class="anchor" name="dump stats-file"></a><a class="anchor" name="9-dump stats-file"></a><a class="anchor" name="9.3-dump stats-file"></a><a class="anchor" name="dump stats-file (Statistics and monitoring)"></a><a class="anchor" name="dump stats-file (Unix Socket commands)"></a><div class="keyword"><b><a class="anchor" name="dump stats-file"></a><a href="#9.3-dump%20stats-file">dump stats-file</a></b></div><pre class="text">Generate a stats-file which can be used to preload haproxy counters values on
startup. See &quot;Stats-file&quot; section for more detail.
</pre><a class="anchor" name="enable"></a><a class="anchor" name="9-enable"></a><a class="anchor" name="9.3-enable"></a><a class="anchor" name="enable (Statistics and monitoring)"></a><a class="anchor" name="enable (Unix Socket commands)"></a><a class="anchor" name="enable agent"></a><a class="anchor" name="9-enable agent"></a><a class="anchor" name="9.3-enable agent"></a><a class="anchor" name="enable agent (Statistics and monitoring)"></a><a class="anchor" name="enable agent (Unix Socket commands)"></a><div class="keyword"><b><a class="anchor" name="enable agent"></a><a href="#9.3-enable%20agent">enable agent</a></b> <span style="color: #080">&lt;backend&gt;</span>/<span style="color: #080">&lt;server&gt;</span></div><pre class="text">Resume auxiliary agent check that was temporarily stopped.

See &quot;<a href="#disable%20agent">disable agent</a>&quot; for details of the effect of temporarily starting
Expand Down Expand Up @@ -4757,6 +4790,26 @@ <h3 id="chapter-9.4.1" data-target="9.4.1"><small><a class="small" href="#9.4.1"

Those messages are also dumped with the &quot;<a href="#reload">reload</a>&quot; command.
</pre></div>
<a class="anchor" id="9.5" name="9.5"></a>
<h2 id="chapter-9.5" data-target="9.5"><small><a class="small" href="#9.5">9.5.</a></small> Stats-file</h2>
<div><pre class="text">A so-called stats-file can be used to preload internal haproxy counters on
process startup with non-null values. Its main purpose is to preserve
statistics for worker processes accross reloads. Only an excerpt of all the
exposed haproxy statistics is present in a stats-file as it only makes sense to
preload metric-type values.

For the moment, only proxy counters are supported in stats-file. This allows to
preload values for frontends, backends, servers and listeners. However only
objects instances with a non-empty GUID are stored in a stats-file. This
guarantees that value will be preloaded for object with matching type and GUID,
even if other parameters differ.

The CLI command &quot;<a href="#dump%20stats-file">dump stats-file</a>&quot; purpose is to generate a stats-file. Format
of the stats-file is internally defined and freely subject to future changes
and extension. It is designed to be compatible at least accross adjacent
haproxy stable branch releases, but may require optional extra configuration
when loading a stats-file to a process running on an older version.
</pre></div>
<a class="anchor" id="10" name="10"></a>
<div class="page-header"><h1 id="chapter-10" data-target="10"><small><a class="small" href="#10">10.</a></small> Tricks for easier configuration management</h1>
</div><div><pre class="text">It is very common that two HAProxy nodes constituting a cluster share exactly
Expand Down Expand Up @@ -5153,7 +5206,7 @@ <h3 id="chapter-9.4.1" data-target="9.4.1"><small><a class="small" href="#9.4.1"
<br>
<hr>
<div class="text-right">
HAProxy 3.0-dev8-21 &ndash; Management Guide<br>
HAProxy 3.0-dev8-81 &ndash; Management Guide<br>
<small>, </small>
</div>
</div>
Expand Down

0 comments on commit b451ddc

Please sign in to comment.