torture: convert torture_comment() -> torture_result() so we can knownfail flapping...
[Samba/wip.git] / ctdb / doc / ctdb-tunables.7.xml
blob456e856355c4df143961fd72c4345abb5ab1df83
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry
3         PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4         "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
6 <refentry id="ctdb-tunables.7">
8   <refmeta>
9     <refentrytitle>ctdb-tunables</refentrytitle>
10     <manvolnum>7</manvolnum>
11     <refmiscinfo class="source">ctdb</refmiscinfo>
12     <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
13   </refmeta>
15   <refnamediv>
16     <refname>ctdb-tunables</refname>
17     <refpurpose>CTDB tunable configuration variables</refpurpose>
18   </refnamediv>
20   <refsect1>
21     <title>DESCRIPTION</title>
23     <para>
24       CTDB's behaviour can be configured by setting run-time tunable
25       variables.  This lists and describes all tunables.  See the
26       <citerefentry><refentrytitle>ctdb</refentrytitle>
27       <manvolnum>1</manvolnum></citerefentry>
28       <command>listvars</command>, <command>setvar</command> and
29       <command>getvar</command> commands for more details.
30     </para>
32     <refsect2>
33       <title>MaxRedirectCount</title>
34       <para>Default: 3</para>
35       <para>
36         If we are not the DMASTER and need to fetch a record across the network
37         we first send the request to the LMASTER after which the record
38         is passed onto the current DMASTER. If the DMASTER changes before
39         the request has reached that node, the request will be passed onto the
40         "next" DMASTER. For very hot records that migrate rapidly across the
41         cluster this can cause a request to "chase" the record for many hops
42         before it catches up with the record.
44         this is how many hops we allow trying to chase the DMASTER before we
45         switch back to the LMASTER again to ask for new directions.
46       </para>
47       <para>
48         When chasing a record, this is how many hops we will chase the record
49         for before going back to the LMASTER to ask for new guidance.
50       </para>
51     </refsect2>
53     <refsect2>
54       <title>SeqnumInterval</title>
55       <para>Default: 1000</para>
56       <para>
57         Some databases have seqnum tracking enabled, so that samba will be able
58         to detect asynchronously when there has been updates to the database.
59         Everytime a database is updated its sequence number is increased.
60       </para>
61       <para>
62         This tunable is used to specify in 'ms' how frequently ctdb will
63         send out updates to remote nodes to inform them that the sequence
64         number is increased.
65       </para>
66     </refsect2>
68     <refsect2>
69       <title>ControlTimeout</title>
70       <para>Default: 60</para>
71       <para>
72         This is the default
73         setting for timeout for when sending a control message to either the
74         local or a remote ctdb daemon.
75       </para>
76     </refsect2>
78     <refsect2>
79       <title>TraverseTimeout</title>
80       <para>Default: 20</para>
81       <para>
82         This setting controls how long we allow a traverse process to run.
83         After this timeout triggers, the main ctdb daemon will abort the
84         traverse if it has not yet finished.
85       </para>
86     </refsect2>
88     <refsect2>
89       <title>KeepaliveInterval</title>
90       <para>Default: 5</para>
91       <para>
92         How often in seconds should the nodes send keepalives to eachother.
93       </para>
94     </refsect2>
96     <refsect2>
97       <title>KeepaliveLimit</title>
98       <para>Default: 5</para>
99       <para>
100         After how many keepalive intervals without any traffic should a node
101         wait until marking the peer as DISCONNECTED.
102       </para>
103       <para>
104         If a node has hung, it can thus take KeepaliveInterval*(KeepaliveLimit+1)
105         seconds before we determine that the node is DISCONNECTED and that we
106         require a recovery. This limitshould not be set too high since we want
107         a hung node to be detectec, and expunged from the cluster well before
108         common CIFS timeouts (45-90 seconds) kick in.
109       </para>
110     </refsect2>
112     <refsect2>
113       <title>RecoverTimeout</title>
114       <para>Default: 20</para>
115       <para>
116         This is the default setting for timeouts for controls when sent from the
117         recovery daemon. We allow longer control timeouts from the recovery daemon
118         than from normal use since the recovery dameon often use controls that 
119         can take a lot longer than normal controls.
120       </para>
121     </refsect2>
123     <refsect2>
124       <title>RecoverInterval</title>
125       <para>Default: 1</para>
126       <para>
127         How frequently in seconds should the recovery daemon perform the
128         consistency checks that determine if we need to perform a recovery or not.
129       </para>
130     </refsect2>
132     <refsect2>
133       <title>ElectionTimeout</title>
134       <para>Default: 3</para>
135       <para>
136         When electing a new recovery master, this is how many seconds we allow
137         the election to take before we either deem the election finished
138         or we fail the election and start a new one.
139       </para>
140     </refsect2>
142     <refsect2>
143       <title>TakeoverTimeout</title>
144       <para>Default: 9</para>
145       <para>
146         This is how many seconds we allow controls to take for IP failover events.
147       </para>
148     </refsect2>
150     <refsect2>
151       <title>MonitorInterval</title>
152       <para>Default: 15</para>
153       <para>
154         How often should ctdb run the event scripts to check for a nodes health.
155       </para>
156     </refsect2>
158     <refsect2>
159       <title>TickleUpdateInterval</title>
160       <para>Default: 20</para>
161       <para>
162         How often will ctdb record and store the "tickle" information used to
163         kickstart stalled tcp connections after a recovery.
164       </para>
165     </refsect2>
167     <refsect2>
168       <title>EventScriptTimeout</title>
169       <para>Default: 20</para>
170       <para>
171         How long should ctdb let an event script run before aborting it and
172         marking the node unhealthy.
173       </para>
174     </refsect2>
176     <refsect2>
177       <title>EventScriptTimeoutCount</title>
178       <para>Default: 1</para>
179       <para>
180         How many events in a row needs to timeout before we flag the node UNHEALTHY.
181         This setting is useful if your scripts can not be written so that they
182         do not hang for benign reasons.
183       </para>
184     </refsect2>
186     <refsect2>
187       <title>EventScriptUnhealthyOnTimeout</title>
188       <para>Default: 0</para>
189       <para>
190         This setting can be be used to make ctdb never become UNHEALTHY if your
191         eventscripts keep hanging/timing out.
192       </para>
193     </refsect2>
195     <refsect2>
196       <title>RecoveryGracePeriod</title>
197       <para>Default: 120</para>
198       <para>
199         During recoveries, if a node has not caused recovery failures during the
200         last grace period, any records of transgressions that the node has caused
201         recovery failures will be forgiven. This resets the ban-counter back to 
202         zero for that node.
203       </para>
204     </refsect2>
206     <refsect2>
207       <title>RecoveryBanPeriod</title>
208       <para>Default: 300</para>
209       <para>
210         If a node becomes banned causing repetitive recovery failures. The node will
211         eventually become banned from the cluster.
212         This controls how long the culprit node will be banned from the cluster
213         before it is allowed to try to join the cluster again.
214         Don't set to small. A node gets banned for a reason and it is usually due
215         to real problems with the node.
216       </para>
217     </refsect2>
219     <refsect2>
220       <title>DatabaseHashSize</title>
221       <para>Default: 100001</para>
222       <para>
223         Size of the hash chains for the local store of the tdbs that ctdb manages.
224       </para>
225     </refsect2>
227     <refsect2>
228       <title>DatabaseMaxDead</title>
229       <para>Default: 5</para>
230       <para>
231         How many dead records per hashchain in the TDB database do we allow before
232         the freelist needs to be processed.
233       </para>
234     </refsect2>
236     <refsect2>
237       <title>RerecoveryTimeout</title>
238       <para>Default: 10</para>
239       <para>
240         Once a recovery has completed, no additional recoveries are permitted
241         until this timeout has expired.
242       </para>
243     </refsect2>
245     <refsect2>
246       <title>EnableBans</title>
247       <para>Default: 1</para>
248       <para>
249         When set to 0, this disables BANNING completely in the cluster and thus
250         nodes can not get banned, even it they break. Don't set to 0 unless you
251         know what you are doing.  You should set this to the same value on
252         all nodes to avoid unexpected behaviour.
253       </para>
254     </refsect2>
256     <refsect2>
257       <title>DeterministicIPs</title>
258       <para>Default: 0</para>
259       <para>
260         When enabled, this tunable makes ctdb try to keep public IP addresses
261         locked to specific nodes as far as possible. This makes it easier for
262         debugging since you can know that as long as all nodes are healthy
263         public IP X will always be hosted by node Y. 
264       </para>
265       <para>
266         The cost of using deterministic IP address assignment is that it
267         disables part of the logic where ctdb tries to reduce the number of
268         public IP assignment changes in the cluster. This tunable may increase
269         the number of IP failover/failbacks that are performed on the cluster
270         by a small margin.
271       </para>
273     </refsect2>
274     <refsect2>
275       <title>LCP2PublicIPs</title>
276       <para>Default: 1</para>
277       <para>
278         When enabled this switches ctdb to use the LCP2 ip allocation
279         algorithm.
280       </para>
281     </refsect2>
283     <refsect2>
284       <title>ReclockPingPeriod</title>
285       <para>Default: x</para>
286       <para>
287         Obsolete
288       </para>
289     </refsect2>
291     <refsect2>
292       <title>NoIPFailback</title>
293       <para>Default: 0</para>
294       <para>
295         When set to 1, ctdb will not perform failback of IP addresses when a node
296         becomes healthy. Ctdb WILL perform failover of public IP addresses when a
297         node becomes UNHEALTHY, but when the node becomes HEALTHY again, ctdb
298         will not fail the addresses back.
299       </para>
300       <para>
301         Use with caution! Normally when a node becomes available to the cluster
302         ctdb will try to reassign public IP addresses onto the new node as a way
303         to distribute the workload evenly across the clusternode. Ctdb tries to
304         make sure that all running nodes have approximately the same number of
305         public addresses it hosts.
306       </para>
307       <para>
308         When you enable this tunable, CTDB will no longer attempt to rebalance
309         the cluster by failing IP addresses back to the new nodes. An unbalanced
310         cluster will therefore remain unbalanced until there is manual
311         intervention from the administrator. When this parameter is set, you can
312         manually fail public IP addresses over to the new node(s) using the
313         'ctdb moveip' command.
314       </para>
315     </refsect2>
317     <refsect2>
318       <title>DisableIPFailover</title>
319       <para>Default: 0</para>
320       <para>
321         When enabled, ctdb will not perform failover or failback. Even if a
322         node fails while holding public IPs, ctdb will not recover the IPs or
323         assign them to another node.
324       </para>
325       <para>
326         When you enable this tunable, CTDB will no longer attempt to recover
327         the cluster by failing IP addresses over to other nodes. This leads to
328         a service outage until the administrator has manually performed failover
329         to replacement nodes using the 'ctdb moveip' command.
330       </para>
331     </refsect2>
333     <refsect2>
334       <title>NoIPTakeover</title>
335       <para>Default: 0</para>
336       <para>
337         When set to 1, ctdb will not allow IP addresses to be failed over
338         onto this node. Any IP addresses that the node currently hosts
339         will remain on the node but no new IP addresses can be failed over
340         to the node.
341       </para>
342     </refsect2>
344     <refsect2>
345       <title>NoIPHostOnAllDisabled</title>
346       <para>Default: 0</para>
347       <para>
348         If no nodes are healthy then by default ctdb will happily host
349         public IPs on disabled (unhealthy or administratively disabled)
350         nodes.  This can cause problems, for example if the underlying
351         cluster filesystem is not mounted.  When set to 1 on a node and
352         that node is disabled it, any IPs hosted by this node will be
353         released and the node will not takeover any IPs until it is no
354         longer disabled.
355       </para>
356     </refsect2>
358     <refsect2>
359       <title>DBRecordCountWarn</title>
360       <para>Default: 100000</para>
361       <para>
362         When set to non-zero, ctdb will log a warning when we try to recover a
363         database with more than this many records. This will produce a warning
364         if a database grows uncontrollably with orphaned records.
365       </para>
366     </refsect2>
368     <refsect2>
369       <title>DBRecordSizeWarn</title>
370       <para>Default: 10000000</para>
371       <para>
372         When set to non-zero, ctdb will log a warning when we try to recover a
373         database where a single record is bigger than this. This will produce
374         a warning if a database record grows uncontrollably with orphaned
375         sub-records.
376       </para>
377     </refsect2>
379     <refsect2>
380       <title>DBSizeWarn</title>
381       <para>Default: 1000000000</para>
382       <para>
383         When set to non-zero, ctdb will log a warning when we try to recover a
384         database bigger than this. This will produce
385         a warning if a database grows uncontrollably.
386       </para>
387     </refsect2>
389     <refsect2>
390       <title>VerboseMemoryNames</title>
391       <para>Default: 0</para>
392       <para>
393         This feature consumes additional memory. when used the talloc library
394         will create more verbose names for all talloc allocated objects.
395       </para>
396     </refsect2>
398     <refsect2>
399       <title>RecdPingTimeout</title>
400       <para>Default: 60</para>
401       <para>
402         If the main dameon has not heard a "ping" from the recovery dameon for
403         this many seconds, the main dameon will log a message that the recovery
404         daemon is potentially hung.
405       </para>
406     </refsect2>
408     <refsect2>
409       <title>RecdFailCount</title>
410       <para>Default: 10</para>
411       <para>
412         If the recovery daemon has failed to ping the main dameon for this many
413         consecutive intervals, the main daemon will consider the recovery daemon
414         as hung and will try to restart it to recover.
415       </para>
416     </refsect2>
418     <refsect2>
419       <title>LogLatencyMs</title>
420       <para>Default: 0</para>
421       <para>
422         When set to non-zero, this will make the main daemon log any operation that
423         took longer than this value, in 'ms', to complete.
424         These include "how long time a lockwait child process needed", 
425         "how long time to write to a persistent database" but also
426         "how long did it take to get a response to a CALL from a remote node".
427       </para>
428     </refsect2>
430     <refsect2>
431       <title>RecLockLatencyMs</title>
432       <para>Default: 1000</para>
433       <para>
434         When using a reclock file for split brain prevention, if set to non-zero
435         this tunable will make the recovery dameon log a message if the fcntl()
436         call to lock/testlock the recovery file takes longer than this number of 
437         ms.
438       </para>
439     </refsect2>
441     <refsect2>
442       <title>RecoveryDropAllIPs</title>
443       <para>Default: 120</para>
444       <para>
445         If we have been stuck in recovery, or stopped, or banned, mode for
446         this many seconds we will force drop all held public addresses.
447       </para>
448     </refsect2>
450     <refsect2>
451       <title>VerifyRecoveryLock</title>
452       <para>Default: 1</para>
453       <para>
454         Should we take a fcntl() lock on the reclock file to verify that we are the
455         sole recovery master node on the cluster or not.
456       </para>
457     </refsect2>
459     <refsect2>
460       <title>VacuumInterval</title>
461       <para>Default: 10</para>
462       <para>
463         Periodic interval in seconds when vacuuming is triggered for
464         volatile databases.
465       </para>
466     </refsect2>
468     <refsect2>
469       <title>VacuumMaxRunTime</title>
470       <para>Default: 120</para>
471       <para>
472         The maximum time in seconds for which the vacuuming process is
473         allowed to run.  If vacuuming process takes longer than this
474         value, then the vacuuming process is terminated.
475       </para>
476     </refsect2>
478     <refsect2>
479       <title>RepackLimit</title>
480       <para>Default: 10000</para>
481       <para>
482         During vacuuming, if the number of freelist records are more
483         than <varname>RepackLimit</varname>, then databases are
484         repacked to get rid of the freelist records to avoid
485         fragmentation.
486       </para>
487       <para>
488         Databases are repacked only if both
489         <varname>RepackLimit</varname> and
490         <varname>VacuumLimit</varname> are exceeded.
491       </para>
492     </refsect2>
494     <refsect2>
495       <title>VacuumLimit</title>
496       <para>Default: 5000</para>
497       <para>
498         During vacuuming, if the number of deleted records are more
499         than <varname>VacuumLimit</varname>, then databases are
500         repacked to avoid fragmentation.
501       </para>
502       <para>
503         Databases are repacked only if both
504         <varname>RepackLimit</varname> and
505         <varname>VacuumLimit</varname> are exceeded.
506       </para>
507     </refsect2>
509     <refsect2>
510       <title>VacuumFastPathCount</title>
511       <para>Default: 60</para>
512       <para>
513         When a record is deleted, it is marked for deletion during
514         vacuuming.  Vacuuming process usually processes this list to purge
515         the records from the database.  If the number of records marked
516         for deletion are more than VacuumFastPathCount, then vacuuming
517         process will scan the complete database for empty records instead
518         of using the list of records marked for deletion.
519       </para>
520     </refsect2>
522     <refsect2>
523       <title>DeferredAttachTO</title>
524       <para>Default: 120</para>
525       <para>
526         When databases are frozen we do not allow clients to attach to the
527         databases. Instead of returning an error immediately to the application
528         the attach request from the client is deferred until the database
529         becomes available again at which stage we respond to the client.
530       </para>
531       <para>
532         This timeout controls how long we will defer the request from the client
533         before timing it out and returning an error to the client.
534       </para>
535     </refsect2>
537     <refsect2>
538       <title>HopcountMakeSticky</title>
539       <para>Default: 50</para>
540       <para>
541         If the database is set to 'STICKY' mode, using the 'ctdb setdbsticky' 
542         command, any record that is seen as very hot and migrating so fast that
543         hopcount surpasses 50 is set to become a STICKY record for StickyDuration
544         seconds. This means that after each migration the record will be kept on
545         the node and prevented from being migrated off the node.
546       </para>
547       <para>
548         This setting allows one to try to identify such records and stop them from
549         migrating across the cluster so fast. This will improve performance for
550         certain workloads, such as locking.tdb if many clients are opening/closing
551         the same file concurrently.
552       </para>
553     </refsect2>
555     <refsect2>
556       <title>StickyDuration</title>
557       <para>Default: 600</para>
558       <para>
559         Once a record has been found to be fetch-lock hot and has been flagged to
560         become STICKY, this is for how long, in seconds, the record will be 
561         flagged as a STICKY record.
562       </para>
563     </refsect2>
565     <refsect2>
566       <title>StickyPindown</title>
567       <para>Default: 200</para>
568       <para>
569         Once a STICKY record has been migrated onto a node, it will be pinned down
570         on that node for this number of ms. Any request from other nodes to migrate
571         the record off the node will be deferred until the pindown timer expires.
572       </para>
573     </refsect2>
575     <refsect2>
576       <title>StatHistoryInterval</title>
577       <para>Default: 1</para>
578       <para>
579         Granularity of the statistics collected in the statistics history.
580       </para>
581     </refsect2>
583     <refsect2>
584       <title>AllowClientDBAttach</title>
585       <para>Default: 1</para>
586       <para>
587         When set to 0, clients are not allowed to attach to any databases.
588         This can be used to temporarily block any new processes from attaching
589         to and accessing the databases.
590       </para>
591     </refsect2>
593     <refsect2>
594       <title>RecoverPDBBySeqNum</title>
595       <para>Default: 1</para>
596       <para>
597         When set to zero, database recovery for persistent databases
598         is record-by-record and recovery process simply collects the
599         most recent version of every individual record.
600       </para>
601       <para>
602         When set to non-zero, persistent databases will instead be
603         recovered as a whole db and not by individual records. The
604         node that contains the highest value stored in the record
605         "__db_sequence_number__" is selected and the copy of that
606         nodes database is used as the recovered database.
607       </para>
608       <para>
609         By default, recovery of persistent databses is done using
610         __db_sequence_number__ record.
611       </para>
612     </refsect2>
614     <refsect2>
615       <title>FetchCollapse</title>
616       <para>Default: 1</para>
617       <para>
618         When many clients across many nodes try to access the same record at the
619         same time this can lead to a fetch storm where the record becomes very
620         active and bounces between nodes very fast. This leads to high CPU
621         utilization of the ctdbd daemon, trying to bounce that record around
622         very fast, and poor performance.
623       </para>
624       <para>
625         This parameter is used to activate a fetch-collapse. A fetch-collapse
626         is when we track which records we have requests in flight so that we only
627         keep one request in flight from a certain node, even if multiple smbd
628         processes are attemtping to fetch the record at the same time. This 
629         can improve performance and reduce CPU utilization for certain
630         workloads.
631       </para>
632       <para>
633         This timeout controls if we should collapse multiple fetch operations
634         of the same record into a single request and defer all duplicates or not.
635       </para>
636     </refsect2>
638     <refsect2>
639       <title>Samba3AvoidDeadlocks</title>
640       <para>Default: 0</para>
641       <para>
642         Enable code that prevents deadlocks with Samba (only for Samba 3.x).
643       </para>
644       <para>
645         This should be set to 1 when using Samba version 3.x to enable special
646         code in CTDB to avoid deadlock with Samba version 3.x.  This code
647         is not required for Samba version 4.x and must not be enabled for
648         Samba 4.x.
649       </para>
650     </refsect2>
651   </refsect1>
653   <refsect1>
654     <title>SEE ALSO</title>
655     <para>
656       <citerefentry><refentrytitle>ctdb</refentrytitle>
657       <manvolnum>1</manvolnum></citerefentry>,
659       <citerefentry><refentrytitle>ctdbd</refentrytitle>
660       <manvolnum>1</manvolnum></citerefentry>,
662       <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
663       <manvolnum>5</manvolnum></citerefentry>,
665       <citerefentry><refentrytitle>ctdb</refentrytitle>
666       <manvolnum>7</manvolnum></citerefentry>,
668       <ulink url="http://ctdb.samba.org/"/>
669     </para>
670   </refsect1>
672   <refentryinfo>
673     <author>
674       <contrib>
675         This documentation was written by
676         Ronnie Sahlberg,
677         Amitay Isaacs,
678         Martin Schwenke
679       </contrib>
680     </author>
682     <copyright>
683       <year>2007</year>
684       <holder>Andrew Tridgell</holder>
685       <holder>Ronnie Sahlberg</holder>
686     </copyright>
687     <legalnotice>
688       <para>
689         This program is free software; you can redistribute it and/or
690         modify it under the terms of the GNU General Public License as
691         published by the Free Software Foundation; either version 3 of
692         the License, or (at your option) any later version.
693       </para>
694       <para>
695         This program is distributed in the hope that it will be
696         useful, but WITHOUT ANY WARRANTY; without even the implied
697         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
698         PURPOSE.  See the GNU General Public License for more details.
699       </para>
700       <para>
701         You should have received a copy of the GNU General Public
702         License along with this program; if not, see
703         <ulink url="http://www.gnu.org/licenses"/>.
704       </para>
705     </legalnotice>
706   </refentryinfo>
708 </refentry>