1 <?xml version="1.0" encoding="iso-8859-1"?>
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">
9 <refentrytitle>ctdb-tunables</refentrytitle>
10 <manvolnum>7</manvolnum>
11 <refmiscinfo class="source">ctdb</refmiscinfo>
12 <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
16 <refname>ctdb-tunables</refname>
17 <refpurpose>CTDB tunable configuration variables</refpurpose>
21 <title>DESCRIPTION</title>
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.
33 <title>MaxRedirectCount</title>
34 <para>Default: 3</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.
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.
54 <title>SeqnumInterval</title>
55 <para>Default: 1000</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.
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
69 <title>ControlTimeout</title>
70 <para>Default: 60</para>
73 setting for timeout for when sending a control message to either the
74 local or a remote ctdb daemon.
79 <title>TraverseTimeout</title>
80 <para>Default: 20</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.
89 <title>KeepaliveInterval</title>
90 <para>Default: 5</para>
92 How often in seconds should the nodes send keepalives to eachother.
97 <title>KeepaliveLimit</title>
98 <para>Default: 5</para>
100 After how many keepalive intervals without any traffic should a node
101 wait until marking the peer as DISCONNECTED.
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.
113 <title>RecoverTimeout</title>
114 <para>Default: 20</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.
124 <title>RecoverInterval</title>
125 <para>Default: 1</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.
133 <title>ElectionTimeout</title>
134 <para>Default: 3</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.
143 <title>TakeoverTimeout</title>
144 <para>Default: 9</para>
146 This is how many seconds we allow controls to take for IP failover events.
151 <title>MonitorInterval</title>
152 <para>Default: 15</para>
154 How often should ctdb run the event scripts to check for a nodes health.
159 <title>TickleUpdateInterval</title>
160 <para>Default: 20</para>
162 How often will ctdb record and store the "tickle" information used to
163 kickstart stalled tcp connections after a recovery.
168 <title>EventScriptTimeout</title>
169 <para>Default: 20</para>
171 How long should ctdb let an event script run before aborting it and
172 marking the node unhealthy.
177 <title>EventScriptTimeoutCount</title>
178 <para>Default: 1</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.
187 <title>EventScriptUnhealthyOnTimeout</title>
188 <para>Default: 0</para>
190 This setting can be be used to make ctdb never become UNHEALTHY if your
191 eventscripts keep hanging/timing out.
196 <title>RecoveryGracePeriod</title>
197 <para>Default: 120</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
207 <title>RecoveryBanPeriod</title>
208 <para>Default: 300</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.
220 <title>DatabaseHashSize</title>
221 <para>Default: 100001</para>
223 Size of the hash chains for the local store of the tdbs that ctdb manages.
228 <title>DatabaseMaxDead</title>
229 <para>Default: 5</para>
231 How many dead records per hashchain in the TDB database do we allow before
232 the freelist needs to be processed.
237 <title>RerecoveryTimeout</title>
238 <para>Default: 10</para>
240 Once a recovery has completed, no additional recoveries are permitted
241 until this timeout has expired.
246 <title>EnableBans</title>
247 <para>Default: 1</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.
257 <title>DeterministicIPs</title>
258 <para>Default: 0</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.
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
275 <title>LCP2PublicIPs</title>
276 <para>Default: 1</para>
278 When enabled this switches ctdb to use the LCP2 ip allocation
284 <title>ReclockPingPeriod</title>
285 <para>Default: x</para>
292 <title>NoIPFailback</title>
293 <para>Default: 0</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.
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.
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.
318 <title>DisableIPFailover</title>
319 <para>Default: 0</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.
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.
334 <title>NoIPTakeover</title>
335 <para>Default: 0</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
345 <title>NoIPHostOnAllDisabled</title>
346 <para>Default: 0</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
359 <title>DBRecordCountWarn</title>
360 <para>Default: 100000</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.
369 <title>DBRecordSizeWarn</title>
370 <para>Default: 10000000</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
380 <title>DBSizeWarn</title>
381 <para>Default: 1000000000</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.
390 <title>VerboseMemoryNames</title>
391 <para>Default: 0</para>
393 This feature consumes additional memory. when used the talloc library
394 will create more verbose names for all talloc allocated objects.
399 <title>RecdPingTimeout</title>
400 <para>Default: 60</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.
409 <title>RecdFailCount</title>
410 <para>Default: 10</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.
419 <title>LogLatencyMs</title>
420 <para>Default: 0</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".
431 <title>RecLockLatencyMs</title>
432 <para>Default: 1000</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
442 <title>RecoveryDropAllIPs</title>
443 <para>Default: 120</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.
451 <title>VerifyRecoveryLock</title>
452 <para>Default: 1</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.
460 <title>VacuumInterval</title>
461 <para>Default: 10</para>
463 Periodic interval in seconds when vacuuming is triggered for
469 <title>VacuumMaxRunTime</title>
470 <para>Default: 120</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.
479 <title>RepackLimit</title>
480 <para>Default: 10000</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
488 Databases are repacked only if both
489 <varname>RepackLimit</varname> and
490 <varname>VacuumLimit</varname> are exceeded.
495 <title>VacuumLimit</title>
496 <para>Default: 5000</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.
503 Databases are repacked only if both
504 <varname>RepackLimit</varname> and
505 <varname>VacuumLimit</varname> are exceeded.
510 <title>VacuumFastPathCount</title>
511 <para>Default: 60</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.
523 <title>DeferredAttachTO</title>
524 <para>Default: 120</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.
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.
538 <title>HopcountMakeSticky</title>
539 <para>Default: 50</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.
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.
556 <title>StickyDuration</title>
557 <para>Default: 600</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.
566 <title>StickyPindown</title>
567 <para>Default: 200</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.
576 <title>StatHistoryInterval</title>
577 <para>Default: 1</para>
579 Granularity of the statistics collected in the statistics history.
584 <title>AllowClientDBAttach</title>
585 <para>Default: 1</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.
594 <title>RecoverPDBBySeqNum</title>
595 <para>Default: 1</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.
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.
609 By default, recovery of persistent databses is done using
610 __db_sequence_number__ record.
615 <title>FetchCollapse</title>
616 <para>Default: 1</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.
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
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.
639 <title>Samba3AvoidDeadlocks</title>
640 <para>Default: 0</para>
642 Enable code that prevents deadlocks with Samba (only for Samba 3.x).
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
654 <title>SEE ALSO</title>
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/"/>
675 This documentation was written by
684 <holder>Andrew Tridgell</holder>
685 <holder>Ronnie Sahlberg</holder>
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.
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.
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"/>.