man: document journal rate limit burst multiplier

The actual burst limit is modified by the remaining disk space. This
isn't mentioned anywhere in the available documentation and might be a
source of surprise for an end user expecting certain behaviors.

diff --git a/man/journald.conf.xml b/man/journald.conf.xml
index 44fd0d2f3d7165e61a52bc7499e83c52368a85c7..6c9268f4dc319caa9538a5abe1450d18846ab040 100644 (file)
--- a/man/journald.conf.xml
+++ b/man/journald.conf.xml
@@ -139,6 +139,51 @@
         <literal>us</literal>. To turn off any kind of rate limiting,
         set either value to 0.</para>
 
+        <para>Note that the effective rate limit is multiplied with a
+        factor derived from the available free disk space for the journal.
+        Currently, this factor is calculated using the base 2 logarithm.</para>
+
+        <table>
+          <title>Example <varname>RateLimitBurst=</varname> rate
+            modifications by the available disk space</title>
+          <tgroup cols='2'>
+            <colspec colname='freespace' />
+            <colspec colname='multiplier' />
+            <thead>
+              <row>
+                <entry>Available Disk Space</entry>
+                <entry>Burst Multiplier</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>&lt;= 1MB</entry>
+                <entry>1</entry>
+              </row>
+              <row>
+                <entry>&lt;= 16MB</entry>
+                <entry>2</entry>
+              </row>
+              <row>
+                <entry>&lt;= 256MB</entry>
+                <entry>3</entry>
+              </row>
+              <row>
+                <entry>&lt;= 4GB</entry>
+                <entry>4</entry>
+              </row>
+              <row>
+                <entry>&lt;= 64GB</entry>
+                <entry>5</entry>
+              </row>
+              <row>
+                <entry>&lt;= 1TB</entry>
+                <entry>6</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+
         <para>If a service provides rate limits for itself through
         <varname>LogRateLimitIntervalSec=</varname> and/or <varname>LogRateLimitBurst=</varname>
         in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,