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 The tunable variables are listed alphabetically.
37 <title>AllowClientDBAttach</title>
38 <para>Default: 1</para>
40 When set to 0, clients are not allowed to attach to any databases.
41 This can be used to temporarily block any new processes from
42 attaching to and accessing the databases. This is mainly used
43 for detaching a volatile database using 'ctdb detach'.
48 <title>AllowUnhealthyDBRead</title>
49 <para>Default: 0</para>
51 When set to 1, ctdb allows database traverses to read unhealthy
52 databases. By default, ctdb does not allow reading records from
58 <title>ControlTimeout</title>
59 <para>Default: 60</para>
61 This is the default setting for timeout for when sending a
62 control message to either the local or a remote ctdb daemon.
67 <title>DatabaseHashSize</title>
68 <para>Default: 100001</para>
70 Number of the hash chains for the local store of the tdbs that
76 <title>DatabaseMaxDead</title>
77 <para>Default: 5</para>
79 Maximum number of dead records per hash chain for the tdb databses
85 <title>DBRecordCountWarn</title>
86 <para>Default: 100000</para>
88 When set to non-zero, ctdb will log a warning during recovery if
89 a database has more than this many records. This will produce a
90 warning if a database grows uncontrollably with orphaned records.
95 <title>DBRecordSizeWarn</title>
96 <para>Default: 10000000</para>
98 When set to non-zero, ctdb will log a warning during recovery
99 if a single record is bigger than this size. This will produce
100 a warning if a database record grows uncontrollably.
105 <title>DBSizeWarn</title>
106 <para>Default: 1000000000</para>
108 When set to non-zero, ctdb will log a warning during recovery if
109 a database size is bigger than this. This will produce a warning
110 if a database grows uncontrollably.
115 <title>DeferredAttachTO</title>
116 <para>Default: 120</para>
118 When databases are frozen we do not allow clients to attach to
119 the databases. Instead of returning an error immediately to the
120 client, the attach request from the client is deferred until
121 the database becomes available again at which stage we respond
125 This timeout controls how long we will defer the request from the
126 client before timing it out and returning an error to the client.
131 <title>DeterministicIPs</title>
132 <para>Default: 0</para>
134 When set to 1, ctdb will try to keep public IP addresses locked
135 to specific nodes as far as possible. This makes it easier
136 for debugging since you can know that as long as all nodes are
137 healthy public IP X will always be hosted by node Y.
140 The cost of using deterministic IP address assignment is that it
141 disables part of the logic where ctdb tries to reduce the number
142 of public IP assignment changes in the cluster. This tunable may
143 increase the number of IP failover/failbacks that are performed
144 on the cluster by a small margin.
149 <title>DisableIPFailover</title>
150 <para>Default: 0</para>
152 When set to non-zero, ctdb will not perform failover or
153 failback. Even if a node fails while holding public IPs, ctdb
154 will not recover the IPs or assign them to another node.
157 When this tunable is enabled, ctdb will no longer attempt
158 to recover the cluster by failing IP addresses over to other
159 nodes. This leads to a service outage until the administrator
160 has manually performed IP failover to replacement nodes using the
161 'ctdb moveip' command.
166 <title>ElectionTimeout</title>
167 <para>Default: 3</para>
169 The number of seconds to wait for the election of recovery
170 master to complete. If the election is not completed during this
171 interval, then that round of election fails and ctdb starts a
177 <title>EnableBans</title>
178 <para>Default: 1</para>
180 This parameter allows ctdb to ban a node if the node is misbehaving.
183 When set to 0, this disables banning completely in the cluster
184 and thus nodes can not get banned, even it they break. Don't
185 set to 0 unless you know what you are doing. You should set
186 this to the same value on all nodes to avoid unexpected behaviour.
191 <title>EventScriptTimeout</title>
192 <para>Default: 30</para>
194 Maximum time in seconds to allow an event to run before timing
195 out. This is the total time for all enabled scripts that are
196 run for an event, not just a single event script.
199 Note that timeouts are ignored for some events ("takeip",
200 "releaseip", "startrecovery", "recovered") and converted to
201 success. The logic here is that the callers of these events
202 implement their own additional timeout.
207 <title>FetchCollapse</title>
208 <para>Default: 1</para>
210 This parameter is used to avoid multiple migration requests for
211 the same record from a single node. All the record requests for
212 the same record are queued up and processed when the record is
213 migrated to the current node.
216 When many clients across many nodes try to access the same record
217 at the same time this can lead to a fetch storm where the record
218 becomes very active and bounces between nodes very fast. This
219 leads to high CPU utilization of the ctdbd daemon, trying to
220 bounce that record around very fast, and poor performance.
221 This can improve performance and reduce CPU utilization for
227 <title>HopcountMakeSticky</title>
228 <para>Default: 50</para>
230 For database(s) marked STICKY (using 'ctdb setdbsticky'),
231 any record that is migrating so fast that hopcount
232 exceeds this limit is marked as STICKY record for
233 <varname>StickyDuration</varname> seconds. This means that
234 after each migration the sticky record will be kept on the node
235 <varname>StickyPindown</varname>milliseconds and prevented from
236 being migrated off the node.
239 This will improve performance for certain workloads, such as
240 locking.tdb if many clients are opening/closing the same file
246 <title>KeepaliveInterval</title>
247 <para>Default: 5</para>
249 How often in seconds should the nodes send keep-alive packets to
255 <title>KeepaliveLimit</title>
256 <para>Default: 5</para>
258 After how many keepalive intervals without any traffic should
259 a node wait until marking the peer as DISCONNECTED.
262 If a node has hung, it can take
263 <varname>KeepaliveInterval</varname> *
264 (<varname>KeepaliveLimit</varname> + 1) seconds before
265 ctdb determines that the node is DISCONNECTED and performs
266 a recovery. This limit should not be set too high to enable
267 early detection and avoid any application timeouts (e.g. SMB1)
268 to kick in before the fail over is completed.
273 <title>LCP2PublicIPs</title>
274 <para>Default: 1</para>
276 When set to 1, ctdb uses the LCP2 ip allocation algorithm.
281 <title>LockProcessesPerDB</title>
282 <para>Default: 200</para>
284 This is the maximum number of lock helper processes ctdb will
285 create for obtaining record locks. When ctdb cannot get a record
286 lock without blocking, it creates a helper process that waits
287 for the lock to be obtained.
292 <title>LogLatencyMs</title>
293 <para>Default: 0</para>
295 When set to non-zero, ctdb will log if certains operations
296 take longer than this value, in milliseconds, to complete.
297 These operations include "process a record request from client",
298 "take a record or database lock", "update a persistent database
299 record" and "vaccum a database".
304 <title>MaxQueueDropMsg</title>
305 <para>Default: 1000000</para>
307 This is the maximum number of messages to be queued up for
308 a client before ctdb will treat the client as hung and will
309 terminate the client connection.
314 <title>MonitorInterval</title>
315 <para>Default: 15</para>
317 How often should ctdb run the 'monitor' event in seconds to check
323 <title>MonitorTimeoutCount</title>
324 <para>Default: 20</para>
326 How many 'monitor' events in a row need to timeout before a node
327 is flagged as UNHEALTHY. This setting is useful if scripts can
328 not be written so that they do not hang for benign reasons.
333 <title>NoIPFailback</title>
334 <para>Default: 0</para>
336 When set to 1, ctdb will not perform failback of IP addresses
337 when a node becomes healthy. When a node becomes UNHEALTHY,
338 ctdb WILL perform failover of public IP addresses, but when the
339 node becomes HEALTHY again, ctdb will not fail the addresses back.
342 Use with caution! Normally when a node becomes available to the
343 cluster ctdb will try to reassign public IP addresses onto the
344 new node as a way to distribute the workload evenly across the
345 clusternode. Ctdb tries to make sure that all running nodes have
346 approximately the same number of public addresses it hosts.
349 When you enable this tunable, ctdb will no longer attempt to
350 rebalance the cluster by failing IP addresses back to the new
351 nodes. An unbalanced cluster will therefore remain unbalanced
352 until there is manual intervention from the administrator. When
353 this parameter is set, you can manually fail public IP addresses
354 over to the new node(s) using the 'ctdb moveip' command.
359 <title>NoIPHostOnAllDisabled</title>
360 <para>Default: 0</para>
362 If no nodes are HEALTHY then by default ctdb will happily host
363 public IPs on disabled (unhealthy or administratively disabled)
364 nodes. This can cause problems, for example if the underlying
365 cluster filesystem is not mounted. When set to 1 on a node and
366 that node is disabled, any IPs hosted by this node will be
367 released and the node will not takeover any IPs until it is no
373 <title>NoIPTakeover</title>
374 <para>Default: 0</para>
376 When set to 1, ctdb will not allow IP addresses to be failed
377 over onto this node. Any IP addresses that the node currently
378 hosts will remain on the node but no new IP addresses can be
379 failed over to the node.
384 <title>PullDBPreallocation</title>
385 <para>Default: 10*1024*1024</para>
387 This is the size of a record buffer to pre-allocate for sending
388 reply to PULLDB control. Usually record buffer starts with size
389 of the first record and gets reallocated every time a new record
390 is added to the record buffer. For a large number of records,
391 this can be very inefficient to grow the record buffer one record
397 <title>QueueBufferSize</title>
398 <para>Default: 1024</para>
400 This is the maximum amount of data (in bytes) ctdb will read
401 from a socket at a time.
404 For a busy setup, if ctdb is not able to process the TCP sockets
405 fast enough (large amount of data in Recv-Q for tcp sockets),
406 then this tunable value should be increased. However, large
407 values can keep ctdb busy processing packets and prevent ctdb
408 from handling other events.
413 <title>RecBufferSizeLimit</title>
414 <para>Default: 1000000</para>
416 This is the limit on the size of the record buffer to be sent
417 in various controls. This limit is used by new controls used
418 for recovery and controls used in vacuuming.
423 <title>RecdFailCount</title>
424 <para>Default: 10</para>
426 If the recovery daemon has failed to ping the main dameon for
427 this many consecutive intervals, the main daemon will consider
428 the recovery daemon as hung and will try to restart it to recover.
433 <title>RecdPingTimeout</title>
434 <para>Default: 60</para>
436 If the main dameon has not heard a "ping" from the recovery dameon
437 for this many seconds, the main dameon will log a message that
438 the recovery daemon is potentially hung. This also increments a
439 counter which is checked against <varname>RecdFailCount</varname>
440 for detection of hung recovery daemon.
445 <title>RecLockLatencyMs</title>
446 <para>Default: 1000</para>
448 When using a reclock file for split brain prevention, if set
449 to non-zero this tunable will make the recovery dameon log a
450 message if the fcntl() call to lock/testlock the recovery file
451 takes longer than this number of milliseconds.
456 <title>RecoverInterval</title>
457 <para>Default: 1</para>
459 How frequently in seconds should the recovery daemon perform the
460 consistency checks to determine if it should perform a recovery.
465 <title>RecoverPDBBySeqNum</title>
466 <para>Default: 1</para>
468 When set to zero, database recovery for persistent databases is
469 record-by-record and recovery process simply collects the most
470 recent version of every individual record.
473 When set to non-zero, persistent databases will instead be
474 recovered as a whole db and not by individual records. The
475 node that contains the highest value stored in the record
476 "__db_sequence_number__" is selected and the copy of that nodes
477 database is used as the recovered database.
480 By default, recovery of persistent databses is done using
481 __db_sequence_number__ record.
486 <title>RecoverTimeout</title>
487 <para>Default: 120</para>
489 This is the default setting for timeouts for controls when sent
490 from the recovery daemon. We allow longer control timeouts from
491 the recovery daemon than from normal use since the recovery
492 dameon often use controls that can take a lot longer than normal
498 <title>RecoveryBanPeriod</title>
499 <para>Default: 300</para>
501 The duration in seconds for which a node is banned if the node
502 fails during recovery. After this time has elapsed the node will
503 automatically get unbanned and will attempt to rejoin the cluster.
506 A node usually gets banned due to real problems with the node.
507 Don't set this value too small. Otherwise, a problematic node
508 will try to re-join cluster too soon causing unnecessary recoveries.
513 <title>RecoveryDropAllIPs</title>
514 <para>Default: 120</para>
516 If a node is stuck in recovery, or stopped, or banned, for this
517 many seconds, then ctdb will release all public addresses on
523 <title>RecoveryGracePeriod</title>
524 <para>Default: 120</para>
526 During recoveries, if a node has not caused recovery failures
527 during the last grace period in seconds, any records of
528 transgressions that the node has caused recovery failures will be
529 forgiven. This resets the ban-counter back to zero for that node.
534 <title>RepackLimit</title>
535 <para>Default: 10000</para>
537 During vacuuming, if the number of freelist records are more than
538 <varname>RepackLimit</varname>, then the database is repacked
539 to get rid of the freelist records to avoid fragmentation.
542 Databases are repacked only if both <varname>RepackLimit</varname>
543 and <varname>VacuumLimit</varname> are exceeded.
548 <title>RerecoveryTimeout</title>
549 <para>Default: 10</para>
551 Once a recovery has completed, no additional recoveries are
552 permitted until this timeout in seconds has expired.
557 <title>SeqnumInterval</title>
558 <para>Default: 1000</para>
560 Some databases have seqnum tracking enabled, so that samba will
561 be able to detect asynchronously when there has been updates
562 to the database. Everytime a database is updated its sequence
566 This tunable is used to specify in milliseconds how frequently
567 ctdb will send out updates to remote nodes to inform them that
568 the sequence number is increased.
573 <title>StatHistoryInterval</title>
574 <para>Default: 1</para>
576 Granularity of the statistics collected in the statistics
577 history. This is reported by 'ctdb stats' command.
582 <title>StickyDuration</title>
583 <para>Default: 600</para>
585 Once a record has been marked STICKY, this is the duration in
586 seconds, the record will be flagged as a STICKY record.
591 <title>StickyPindown</title>
592 <para>Default: 200</para>
594 Once a STICKY record has been migrated onto a node, it will be
595 pinned down on that node for this number of milliseconds. Any
596 request from other nodes to migrate the record off the node will
602 <title>TakeoverTimeout</title>
603 <para>Default: 9</para>
605 This is the duration in seconds in which ctdb tries to complete IP
611 <title>TDBMutexEnabled</title>
612 <para>Default: 0</para>
614 This paramter enables TDB_MUTEX_LOCKING feature on volatile
615 databases if the robust mutexes are supported. This optimizes the
616 record locking using robust mutexes and is much more efficient
617 that using posix locks.
622 <title>TickleUpdateInterval</title>
623 <para>Default: 20</para>
625 Every <varname>TickleUpdateInterval</varname> seconds, ctdb
626 synchronizes the client connection information across nodes.
631 <title>TraverseTimeout</title>
632 <para>Default: 20</para>
634 This is the duration in seconds for which a database traverse
635 is allowed to run. If the traverse does not complete during
636 this interval, ctdb will abort the traverse.
641 <title>VacuumFastPathCount</title>
642 <para>Default: 60</para>
644 During a vacuuming run, ctdb usually processes only the records
645 marked for deletion also called the fast path vacuuming. After
646 finishing <varname>VacuumFastPathCount</varname> number of fast
647 path vacuuming runs, ctdb will trigger a scan of complete database
648 for any empty records that need to be deleted.
653 <title>VacuumInterval</title>
654 <para>Default: 10</para>
656 Periodic interval in seconds when vacuuming is triggered for
662 <title>VacuumLimit</title>
663 <para>Default: 5000</para>
665 During vacuuming, if the number of deleted records are more than
666 <varname>VacuumLimit</varname>, then databases are repacked to
670 Databases are repacked only if both <varname>RepackLimit</varname>
671 and <varname>VacuumLimit</varname> are exceeded.
676 <title>VacuumMaxRunTime</title>
677 <para>Default: 120</para>
679 The maximum time in seconds for which the vacuuming process is
680 allowed to run. If vacuuming process takes longer than this
681 value, then the vacuuming process is terminated.
686 <title>VerboseMemoryNames</title>
687 <para>Default: 0</para>
689 When set to non-zero, ctdb assigns verbose names for some of
690 the talloc allocated memory objects. These names are visible
691 in the talloc memory report generated by 'ctdb dumpmemory'.
698 <title>SEE ALSO</title>
700 <citerefentry><refentrytitle>ctdb</refentrytitle>
701 <manvolnum>1</manvolnum></citerefentry>,
703 <citerefentry><refentrytitle>ctdbd</refentrytitle>
704 <manvolnum>1</manvolnum></citerefentry>,
706 <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
707 <manvolnum>5</manvolnum></citerefentry>,
709 <citerefentry><refentrytitle>ctdb</refentrytitle>
710 <manvolnum>7</manvolnum></citerefentry>,
712 <ulink url="http://ctdb.samba.org/"/>
719 This documentation was written by
728 <holder>Andrew Tridgell</holder>
729 <holder>Ronnie Sahlberg</holder>
733 This program is free software; you can redistribute it and/or
734 modify it under the terms of the GNU General Public License as
735 published by the Free Software Foundation; either version 3 of
736 the License, or (at your option) any later version.
739 This program is distributed in the hope that it will be
740 useful, but WITHOUT ANY WARRANTY; without even the implied
741 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
742 PURPOSE. See the GNU General Public License for more details.
745 You should have received a copy of the GNU General Public
746 License along with this program; if not, see
747 <ulink url="http://www.gnu.org/licenses"/>.