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

1 files changed, 19 insertions, 7 deletions

diff --git a/docs-xml/smbdotconf/misc/ctdblocktimewarnthreshold.xml b/docs-xml/smbdotconf/misc/ctdblocktimewarnthreshold.xml
index 149d8d67e3..a3289a93bc 100644
--- 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>