Add 'subscription_identifiers_enabled' to man page

halfgaar · Nov 11, 2024 · 8c074fa · 8c074fa
1 parent 0702ed1
commit 8c074fa
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 2 deletions.
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 "Nov 08 2024" "" ""
+.TH flashmq.conf 5 "Nov 10 2024" "" ""
 .SH NAME
 flashmq.conf \- FlashMQ configuration file format
 .SH SYNOPSIS
@@ -331,6 +331,15 @@ Default: \fI2000\fR
 Load *.conf files from the specified directory, to merge with the main configuration file.
 
 An error is generated when the directory is not there. This is to protect against running incorrect configurations by accident, when the dir has been renamed, for example.
+.TP
+\*(T<\fB\m[green]subscription_identifiers_enabled\m[] \fI\m[cyan]true\m[]\fR|\fI\m[cyan]false\m[]\fR\fR\*(T>
+Subscription identifiers allow clients to see which subscription was responsible for a message. Publish messages will contain the identifier included in the original subscription.
+
+Enabling will prevent FlashMQ from using optimizations involving packet reuse, because the packets are unique per client when it contains a subscription identifier. Therefore you may want to assess the performance difference in high message volume deployments.
+
+As per the spec, clients sending subscription identifiers when the server reported the feature as unavailable will cause them to be disconnected. This has the side effect that changing this setting on a running server will disconnect clients when they send a subscription with an identifier in it. This was chosen as behavior over the alternatives, because of simplicity and operator control (otherwise it can't be turned off at all for existing clients).
+
+Default value: \fItrue\fR
 .SH LISTEN PARAMETERS
 Listen parameters can only be used within \fIlisten { }\fR blocks.
 .TP

diff --git a/man/flashmq.conf.5.dbk5 b/man/flashmq.conf.5.dbk5
@@ -674,6 +674,24 @@ multi-value-param one 'two' "three" "with ' char"
         </listitem>
       </varlistentry>
 
+      <varlistentry xml:id="subscription_identifiers_enabled" condition="flashmq ≥ 1.18.0">
+        <term><option>subscription_identifiers_enabled</option> <replaceable>true</replaceable>|<replaceable>false</replaceable></term>
+        <listitem>
+          <para>
+            Subscription identifiers allow clients to see which subscription was responsible for a message. Publish messages will contain the identifier included in the original subscription.
+          </para>
+          <para>
+            Enabling will prevent FlashMQ from using optimizations involving packet reuse, because the packets are unique per client when it contains a subscription identifier. Therefore you may want to assess the performance difference in high message volume deployments.
+          </para>
+          <para>
+            As per the spec, clients sending subscription identifiers when the server reported the feature as unavailable will cause them to be disconnected. This has the side effect that changing this setting on a running server will disconnect clients when they send a subscription with an identifier in it. This was chosen as behavior over the alternatives, because of simplicity and operator control (otherwise it can't be turned off at all for existing clients).
+          </para>
+          <para>
+            Default value: <literal>true</literal>
+          </para>
+        </listitem>
+      </varlistentry>
+
     </variablelist>
   </refsect1>
 

diff --git a/man/flashmq.conf.5.html b/man/flashmq.conf.5.html
@@ -242,7 +242,7 @@
           });
         });
       });
-      </script><article id="flashmq.conf.5"><nav xmlns="http://docbook.org/ns/docbook" xmlns:dbk="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:semver="https://semver.org/spec/v2.0.0.html" xmlns:fmq="http://www.flashmq.org/man/" id="flashmq-version-nav"><select id="select-flashmq-version"><option value="" selected>latest</option><option value="1.16.0">≥ v1.16.0</option><option value="1.15.1">≥ v1.15.1</option><option value="1.14.0">≥ v1.14.0</option><option value="1.13.0">≥ v1.13.0</option><option value="1.12.0">≥ v1.12.0</option><option value="1.11.0">≥ v1.11.0</option><option value="1.10.0">≥ v1.10.0</option><option value="1.9.0">≥ v1.9.0</option><option value="1.8.4">≥ v1.8.4</option><option value="1.8.0">≥ v1.8.0</option><option value="1.7.0">≥ v1.7.0</option><option value="1.6.7">≥ v1.6.7</option><option value="1.4.4">≥ v1.4.4</option><option value="1.4.2">≥ v1.4.2</option><option value="1.2.0">≥ v1.2.0</option><option value="1.1.0">≥ v1.1.0</option></select></nav><header><h1>flashmq.conf<code class="manvolnum"> (5)</code></h1><h2 class="refpurpose">FlashMQ configuration file format</h2></header><section class="refsynopsisdiv" id="synopsis"><header><h2>Synopsis</h2></header>
+      </script><article id="flashmq.conf.5"><nav xmlns="http://docbook.org/ns/docbook" xmlns:dbk="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:semver="https://semver.org/spec/v2.0.0.html" xmlns:fmq="http://www.flashmq.org/man/" id="flashmq-version-nav"><select id="select-flashmq-version"><option value="" selected>latest</option><option value="1.18.0">≥ v1.18.0</option><option value="1.16.0">≥ v1.16.0</option><option value="1.15.1">≥ v1.15.1</option><option value="1.14.0">≥ v1.14.0</option><option value="1.13.0">≥ v1.13.0</option><option value="1.12.0">≥ v1.12.0</option><option value="1.11.0">≥ v1.11.0</option><option value="1.10.0">≥ v1.10.0</option><option value="1.9.0">≥ v1.9.0</option><option value="1.8.4">≥ v1.8.4</option><option value="1.8.0">≥ v1.8.0</option><option value="1.7.0">≥ v1.7.0</option><option value="1.6.7">≥ v1.6.7</option><option value="1.4.4">≥ v1.4.4</option><option value="1.4.2">≥ v1.4.2</option><option value="1.2.0">≥ v1.2.0</option><option value="1.1.0">≥ v1.1.0</option></select></nav><header><h1>flashmq.conf<code class="manvolnum"> (5)</code></h1><h2 class="refpurpose">FlashMQ configuration file format</h2></header><section class="refsynopsisdiv" id="synopsis"><header><h2>Synopsis</h2></header>
     <p>
        The <code class="filename">flashmq.conf</code> file is the configuration used for configuring the FlashMQ MQTT broker.
     </p>
@@ -889,6 +889,24 @@
         </dd>
 
 
+
+        <dt id="subscription_identifiers_enabled"><div xmlns="http://docbook.org/ns/docbook" class="flashmq_version_requirement" data-since-flashmq-version="1.18.0">≥ v1.18.0</div><code class="option">subscription_identifiers_enabled</code> <code class="replaceable">true</code>|<code class="replaceable">false</code><a class="hash-anchor" href="#subscription_identifiers_enabled">#</a></dt>
+        <dd>
+          <p>
+            Subscription identifiers allow clients to see which subscription was responsible for a message. Publish messages will contain the identifier included in the original subscription.
+          </p>
+          <p>
+            Enabling will prevent FlashMQ from using optimizations involving packet reuse, because the packets are unique per client when it contains a subscription identifier. Therefore you may want to assess the performance difference in high message volume deployments.
+          </p>
+          <p>
+            As per the spec, clients sending subscription identifiers when the server reported the feature as unavailable will cause them to be disconnected. This has the side effect that changing this setting on a running server will disconnect clients when they send a subscription with an identifier in it. This was chosen as behavior over the alternatives, because of simplicity and operator control (otherwise it can't be turned off at all for existing clients).
+          </p>
+          <p>
+            Default value: <code class="literal">true</code>
+          </p>
+        </dd>
+
+
     </dl>
   </section><section class="refsect1">
     <header><h2>Listen parameters</h2></header>