Add new overload mode to man page

quinox · May 3, 2024 · ffef443 · ffef443
1 parent f3918f1
commit ffef443
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 1 deletion.
diff --git a/man/flashmq.conf.5 b/man/flashmq.conf.5
@@ -5,7 +5,7 @@
 \\$2 \(la\\$1\(ra\\$3
 ..
 .if \n(.g .mso www.tmac
-.TH flashmq.conf 5 "21 April 2024" "" ""
+.TH flashmq.conf 5 "3 May 2024" "" ""
 .SH NAME
 flashmq.conf \- FlashMQ configuration file format
 .SH SYNOPSIS
@@ -255,6 +255,24 @@ For \*(T<\fBminimum_wildcard_subscription_depth\fR\*(T>, specify what you want t
 
 Default: \*(T<deny_all\*(T>
 .TP 
+\*(T<\fBoverload_mode\fR\*(T> \fIlog/close_new_clients\fR 
+Define the action to perform when the value defined with \*(T<\fBmax_event_loop_drift\fR\*(T> is exceeded.
+
+When a server is (re)started, and hundreds of thousands of clients connect, the SSL handshaking and authenticating can be so heavy that it doesn't get to clients in time. They will then reconnect and try again, and get stuck in a loop. This option is to mitigate that. With \*(T<close_new_clients\*(T>, new clients will be closed immediately after connecting while the server is overloaded. This will allow the worker threads to process the new clients in a controlled manner.
+
+For really large deployments, this can be augmented with extra rate limiting in iptables, or other firewalls. A stateless method is preferred, like: \*(T<iptables \-I INPUT \-p tcp \-m multiport \-\-dports 8883,1883 \-\-syn \-m hashlimit \-\-hashlimit\-name newmqttconns \-\-hashlimit\-above 10000/second \-\-hashlimit\-burst 15000 \-j DROP\*(T>
+
+The current default is \*(T<log\*(T>, but that will likely change in the future.
+
+Default: \*(T<log\*(T>
+.TP 
+\*(T<\fBmax_event_loop_drift\fR\*(T> \fImilliseconds\fR 
+For \*(T<\fBoverload_mode\fR\*(T>, the maximum permissible thread drift before the overload action is taken.
+
+The drift values considered are those of the main loop, in which clients are accepted, and the median of all worker threads.
+
+Default: \*(T<2000\*(T>
+.TP 
 \*(T<\fBinclude_dir\fR\*(T> \fI/path/to/dir\fR 
 Load *.conf files from the specified directory, to merge with the main configuration file.
 

diff --git a/man/flashmq.conf.5.dbk5 b/man/flashmq.conf.5.dbk5
@@ -518,6 +518,42 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry xml:id="overload_mode">
+        <term><option>overload_mode</option> <replaceable>log/close_new_clients</replaceable></term>
+        <listitem>
+          <para>
+            Define the action to perform when the value defined with <option>max_event_loop_drift</option> is exceeded.
+          </para>
+          <para>
+            When a server is (re)started, and hundreds of thousands of clients connect, the SSL handshaking and authenticating can be so heavy that it doesn't get to clients in time. They will then reconnect and try again, and get stuck in a loop. This option is to mitigate that. With <literal>close_new_clients</literal>, new clients will be closed immediately after connecting while the server is overloaded. This will allow the worker threads to process the new clients in a controlled manner.
+          </para>
+          <para>
+              For really large deployments, this can be augmented with extra rate limiting in iptables, or other firewalls. A stateless method is preferred, like: <literal>iptables -I INPUT -p tcp -m multiport --dports 8883,1883 --syn -m hashlimit --hashlimit-name newmqttconns --hashlimit-above 10000/second --hashlimit-burst 15000 -j DROP</literal>
+          </para>
+          <para>
+            The current default is <literal>log</literal>, but that will likely change in the future.
+          </para>
+          <para>
+            Default: <literal>log</literal>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry xml:id="max_event_loop_drift">
+        <term><option>max_event_loop_drift</option> <replaceable>milliseconds</replaceable></term>
+        <listitem>
+          <para>
+            For <option>overload_mode</option>, the maximum permissible thread drift before the overload action is taken.
+          </para>
+          <para>
+            The drift values considered are those of the main loop, in which clients are accepted, and the median of all worker threads.
+          </para>
+          <para>
+            Default: <literal>2000</literal>
+          </para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry xml:id="include_dir">
         <term><option>include_dir</option> <replaceable>/path/to/dir</replaceable></term>
         <listitem>

diff --git a/man/flashmq.conf.5.html b/man/flashmq.conf.5.html
@@ -574,6 +574,42 @@
 
 
 
+        <dt id="overload_mode"><code class="option">overload_mode</code> <code class="replaceable">log/close_new_clients</code><a class="hash-anchor" href="#overload_mode">#</a></dt>
+        <dd>
+          <p>
+            Define the action to perform when the value defined with <code class="option">max_event_loop_drift</code> is exceeded.
+          </p>
+          <p>
+            When a server is (re)started, and hundreds of thousands of clients connect, the SSL handshaking and authenticating can be so heavy that it doesn't get to clients in time. They will then reconnect and try again, and get stuck in a loop. This option is to mitigate that. With <code class="literal">close_new_clients</code>, new clients will be closed immediately after connecting while the server is overloaded. This will allow the worker threads to process the new clients in a controlled manner.
+          </p>
+          <p>
+              For really large deployments, this can be augmented with extra rate limiting in iptables, or other firewalls. A stateless method is preferred, like: <code class="literal">iptables -I INPUT -p tcp -m multiport --dports 8883,1883 --syn -m hashlimit --hashlimit-name newmqttconns --hashlimit-above 10000/second --hashlimit-burst 15000 -j DROP</code>
+          </p>
+          <p>
+            The current default is <code class="literal">log</code>, but that will likely change in the future.
+          </p>
+          <p>
+            Default: <code class="literal">log</code>
+          </p>
+        </dd>
+
+
+
+        <dt id="max_event_loop_drift"><code class="option">max_event_loop_drift</code> <code class="replaceable">milliseconds</code><a class="hash-anchor" href="#max_event_loop_drift">#</a></dt>
+        <dd>
+          <p>
+            For <code class="option">overload_mode</code>, the maximum permissible thread drift before the overload action is taken.
+          </p>
+          <p>
+            The drift values considered are those of the main loop, in which clients are accepted, and the median of all worker threads.
+          </p>
+          <p>
+            Default: <code class="literal">2000</code>
+          </p>
+        </dd>
+
+
+
         <dt id="include_dir"><code class="option">include_dir</code> <code class="replaceable">/path/to/dir</code><a class="hash-anchor" href="#include_dir">#</a></dt>
         <dd>
           <p>