s3-docs: Add more verbose description of "ctdb locktime warn threshold".

diff --git a/docs-xml/smbdotconf/misc/ctdblocktimewarnthreshold.xml b/docs-xml/smbdotconf/misc/ctdblocktimewarnthreshold.xml
index 149d8d67e3f381de264d6f1e78a3e3f52717d223..a3289a93bc4007edf66b298479f2e851ee2f20e5 100644 (file)
--- a/docs-xml/smbdotconf/misc/ctdblocktimewarnthreshold.xml
+++ b/docs-xml/smbdotconf/misc/ctdblocktimewarnthreshold.xml
@@ -4,13 +4,25 @@
                  advanced="1"
                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
 <description>
-       <para>In a cluster, ctdb is very unhappy if tdb database locks
-       are held for extended periods of time. This parameter adds a
-       warning threshold in milliseconds. If Samba holds a lock for
-       longer that ctdb locktime warn threshold milliseconds, a debug
-       level 0 message is printed when the lock is released. This is
-       mainly a debugging aid for post-mortem analysis.</para>
-       <para>If this parameter is set to 0, no message is printed.</para>
+
+       <para>
+       In a cluster environment using Samba and ctdb it is critical
+       that locks on central ctdb-hosted databases like locking.tdb
+       are not held for long. With the current Samba architecture
+       it happens that Samba takes a lock and while holding that
+       lock makes file system calls into the shared cluster file
+       system. This option makes Samba warn if it detects that it
+       has held locks for the specified number of milliseconds. If
+       this happens, <emphasis>smbd</emphasis> will emit a debug level 0
+       message into its logs and potentially into syslog. The most likely
+       reason for such a log message is that an operation of the cluster
+       file system Samba exports is taking longer than expected.
+       The messages are meant as a debugging aid for potential
+       cluster problems.
+       </para>
+
+       <para>The default value of 0 disables this logging.</para>
+
 </description>
 <value type="default">0</value>
 </samba:parameter>