CTDB-TUNABLES(7)
🌸 CTDB-TUNABLES(7) 🌸
ok so this is the manual page for ctdb-tunables from the CTDB - clustered TDB database corner of the universe, and it is literally the master list of every knob you can turn. buckle up bestie 💖
✨ NAME ✨
ctdb-tunables — CTDB tunable configuration variables 🎀
🦋 DESCRIPTION 🦋
CTDB's whole personality is configurable, and you do it with run-time tunable variables. This page lists and explains every single one of them. For the how, go check the listvars, setvar and getvar commands in ctdb(1). 👑
ok important thing first: unless it says otherwise, set tunables to the same value on all nodes. Setting them differently across nodes can produce unexpected results. Future releases may set (some or most) tunables globally across the cluster, but rn that's a whole manual process, no automation, sorry babes 😭
Tunables can be set at startup through optional config files. The order is very much a thing:
- First,
/etc/ctdb/ctdb.tunablesgets loaded, if this file exists. - After that, all files with names matching
*.tunablesin the directory/etc/ctdb/tunables.d/are loaded, in the current locale's collation order — again, only if the directory exists.
The format of lines in tunables files is:
TUNABLE=VALUEComment lines starting with # are permitted. Whitespace is fine for formatting and alignment, do your lil aesthetic thing 💅. But VALUE must be a non-negative integer and must be the last thing on a line — so no trailing garbage, and trailing comments are not permitted. periodt.
For example:
MonitorInterval=20The available tunable variables are listed alphabetically below. ⬇️
🍓 AllowClientDBAttach
Default: 1
When set to 0, clients are not allowed to attach to any databases. This is your "do not disturb" mode — it temporarily blocks any new processes from attaching to and accessing the databases. Mainly used for detaching a volatile database using ctdb detach.
🧚 AllowMixedVersions
Default: 0
CTDB does not allow incompatible versions to co-exist in a cluster. If a version mismatch is found, then the losing CTDB will shutdown. To disable the incompatible version check, set this tunable to 1.
For version checking, CTDB uses major and minor version. For example, CTDB 4.6.1 and CTDB 4.6.2 are matching versions; CTDB 4.5.x and CTDB 4.6.y do not match.
CTDB with version check support will lose to CTDB without version check support. Between two different CTDB versions with version check support, the one running for less time will lose. If the running time for both CTDB versions with version check support is equal (to seconds), then the older version will lose. The losing CTDB daemon will shutdown. 💀
🌸 AllowUnhealthyDBRead
Default: 0
When set to 1, ctdb allows database traverses to read unhealthy databases. By default, ctdb does not allow reading records from unhealthy databases.
🎀 ControlTimeout
Default: 60
This is the default setting for timeout when sending a control message to either the local or a remote ctdb daemon.
💜 DatabaseHashSize
Default: 100001
Number of the hash chains for the local store of the tdbs that ctdb manages.
🦋 DatabaseMaxDead
Default: 5
Maximum number of dead records per hash chain for the tdb databases managed by ctdb.
⭐ DBRecordCountWarn
Default: 100000
When set to non-zero, ctdb will log a warning during recovery if a database has more than this many records. This will produce a warning if a database grows uncontrollably with orphaned records.
💖 DBRecordSizeWarn
Default: 10000000
When set to non-zero, ctdb will log a warning during recovery if a single record is bigger than this size. This will produce a warning if a database record grows uncontrollably.
🌈 DBSizeWarn
Default: 1000000000
When set to non-zero, ctdb will log a warning during recovery if a database size is bigger than this. This will produce a warning if a database grows uncontrollably.
🫶 DeferredAttachTO
Default: 120
When databases are frozen we do not allow clients to attach to the databases. Instead of returning an error immediately to the client, the attach request from the client is deferred until the database becomes available again — at which stage we respond to the client. so polite of us, honestly.
This timeout controls how long we will defer the request from the client before timing it out and returning an error to the client.
👑 ElectionTimeout
Default: 3
The number of seconds to wait for the election of recovery master to complete. If the election is not completed during this interval, then that round of election fails and ctdb starts a new election. it's giving chaotic democracy, but it works 🔥
🌸 EnableBans
Default: 1
This parameter allows ctdb to ban a node if the node is misbehaving.
When set to 0, this disables banning completely in the cluster, and thus nodes can not get banned, even if they break.
Don't set to 0 unless you know what you are doing. fr fr. no take-backs on this one.
✨ EventScriptTimeout
Default: 30
Maximum time in seconds to allow an event to run before timing out. This is the total time for all enabled scripts that are run for an event, not just a single event script — so it's a group budget, not a per-script one.
Note that timeouts are ignored for some events ("takeip", "releaseip", "startrecovery", "recovered") and converted to success. The logic here is that the callers of these events implement their own additional timeout. iykyk.
🦋 FetchCollapse
Default: 1
This parameter is used to avoid multiple migration requests for the same record from a single node. All the record requests for the same record are queued up and processed when the record is migrated to the current node.
When many clients across many nodes try to access the same record at the same time this can lead to a fetch storm where the record becomes very active and bounces between nodes very fast. This leads to high CPU utilization of the ctdbd daemon, trying to bounce that record around very fast, and poor performance. This can improve performance and reduce CPU utilization for certain workloads. 🚀
🧚 HopcountMakeSticky
Default: 50
For database(s) marked STICKY (using ctdb setdbsticky), any record that is migrating so fast that hopcount exceeds this limit is marked as STICKY record for StickyDuration seconds. This means that after each migration the sticky record will be kept on the node StickyPindownmilliseconds and prevented from being migrated off the node.
This will improve performance for certain workloads, such as locking.tdb if many clients are opening/closing the same file concurrently. iconic behavior honestly.
💅 IPAllocAlgorithm
Default: 2
Selects the algorithm that CTDB should use when doing public IP address allocation. Meaningful values are:
0— Deterministic IP address allocation.
This is a simple and fast option. However, it can cause unnecessary address movement during fail-over because each address has a "home" node. Works badly when some nodes do not have any addresses defined. Should be used with care when addresses are defined across multiple networks.
You can override the automatic "home" node allocation by creating a file "home_nodes" next to the "public_addresses" file. As an example the following "home_nodes" file assigns the address 192.168.1.1 to node 0 and 192.168.1.2 to node 2:
192.168.1.1 0
192.168.1.2 21— Non-deterministic IP address allocation.
This is a relatively fast option that attempts to do a minimise unnecessary address movements. Addresses do not have a "home" node. Rebalancing is limited but it usually adequate. Works badly when addresses are defined across multiple networks.
2— LCP2 IP address allocation.
Uses a heuristic to assign addresses defined across multiple networks, usually balancing addresses on each network evenly across nodes. Addresses do not have a "home" node. Minimises unnecessary address movements. The algorithm is complex, so is slower than other choices for a large number of addresses. However, it can calculate an optimal assignment of 900 addresses in under 10 seconds on modern hardware. okay that's actually wild 🤯
If the specified value is not one of these then the default will be used.
🎀 KeepaliveInterval
Default: 5
How often in seconds should the nodes send keep-alive packets to each other. it's the group chat "u up?" of networking 💖
💜 KeepaliveLimit
Default: 5
After how many keepalive intervals without any traffic should a node wait until marking the peer as DISCONNECTED.
If a node has hung, it can take KeepaliveInterval * (KeepaliveLimit + 1) seconds before ctdb determines that the node is DISCONNECTED and performs a recovery. This limit should not be set too high to enable early detection and avoid any application timeouts (e.g. SMB1) to kick in before the fail over is completed.
🍓 LockProcessesPerDB
Default: 200
This is the maximum number of lock helper processes ctdb will create for obtaining record locks. When ctdb cannot get a record lock without blocking, it creates a helper process that waits for the lock to be obtained.
⭐ LogLatencyMs
Default: 0
When set to non-zero, ctdb will log if certains operations take longer than this value, in milliseconds, to complete. These operations include "process a record request from client", "take a record or database lock", "update a persistent database record" and "vacuum a database". (yes the original says "certains", we keep it, we don't police the manpage 😌)
🌈 MaxQueueDropMsg
Default: 1000000
This is the maximum number of messages to be queued up for a client before ctdb will treat the client as hung and will terminate the client connection.
🦋 MonitorInterval
Default: 15
How often should ctdb run the 'monitor' event in seconds to check for a node's health.
💖 MonitorTimeoutCount
Default: 20
How many 'monitor' events in a row need to timeout before a node is flagged as UNHEALTHY. This setting is useful if scripts can not be written so that they do not hang for benign reasons.
✨ NoIPFailback
Default: 0
When set to 1, ctdb will not perform failback of IP addresses when a node becomes healthy. When a node becomes UNHEALTHY, ctdb WILL perform failover of public IP addresses, but when the node becomes HEALTHY again, ctdb will not fail the addresses back.
Use with caution! 🚨 Normally when a node becomes available to the cluster ctdb will try to reassign public IP addresses onto the new node as a way to distribute the workload evenly across the clusternode. Ctdb tries to make sure that all running nodes have approximately the same number of public addresses it hosts.
When you enable this tunable, ctdb will no longer attempt to rebalance the cluster by failing IP addresses back to the new nodes. An unbalanced cluster will therefore remain unbalanced until there is manual intervention from the administrator. When this parameter is set, you can manually fail public IP addresses over to the new node(s) using the 'ctdb moveip' command.
🌸 NoIPTakeover
Default: 0
When it's set to 1, ctdb is literally like "nope, we're not failing any IP addresses over to other nodes, periodt." Any IPs that are already chilling on healthy nodes? They stay exactly where they are. But any IPs sitting on unhealthy nodes get released by those unhealthy nodes and become un-hosted. 😭
💖 PullDBPreallocation 💖
Default: 10*1024*1024
This is the size of a record buffer that ctdb pre-allocates so it can send a reply to the PULLDB control. Normally the record buffer starts out at the size of the first record and then gets reallocated every single time a new record gets added to it — which, for a large number of records, is so inefficient, bestie. Like growing a buffer one record at a time? Not the vibe. 🫠
💖 QueueBufferSize 💖
Default: 1024
This is the maximum amount of data (in bytes) that ctdb will read from a socket at one time.
For a busy setup, if ctdb can't process the TCP sockets fast enough — which looks like a large amount of data in Recv-Q for tcp sockets — then you should bump this tunable value up. But watch out: big values can keep ctdb busy processing packets and stop it from handling other events. Highkey a trade-off, ngl.
💖 RecBufferSizeLimit 💖
Default: 1000000
This is the limit on the size of the record buffer that gets sent in various controls. This limit is used by the new controls used for recovery, and by the controls used in vacuuming. 🧹
💖 RecdFailCount 💖
Default: 10
If the recovery daemon has failed to ping the main daemon for this many consecutive intervals, the main daemon decides the recovery daemon is hung and tries to restart it to recover. It's giving "bestie, you good? no? okay, restarting you." 💀
💖 RecdPingTimeout 💖
Default: 60
If the main daemon hasn't heard a "ping" from the recovery daemon for this many seconds, it logs a message saying the recovery daemon is potentially hung. It also increments a counter, which gets checked against RecdFailCount to detect a hung recovery daemon.
💖 RecLockLatencyMs 💖
Default: 1000
When you're using a reclock file for split brain prevention, setting this tunable to non-zero makes the recovery daemon log a message if the fcntl() call to lock/testlock the recovery file takes longer than this number of milliseconds. ✨
💖 RecoverInterval 💖
Default: 1
How frequently, in seconds, the recovery daemon should run its consistency checks to figure out whether it should perform a recovery.
💖 RecoverTimeout 💖
Default: 120
This is the default setting for control timeouts when the controls are sent from the recovery daemon. We allow longer control timeouts from the recovery daemon than from normal use, because the recovery daemon often uses controls that can take a whole lot longer than normal controls do. Main character privileges, honestly. 👑
💖 RecoveryBanPeriod 💖
Default: 300
The duration in seconds that a node stays banned if it fails during recovery. Once this time is up, the node automatically gets unbanned and will try to rejoin the cluster.
A node usually gets banned because of real problems with the node, so don't set this value too small. Otherwise a problematic node will try to re-join the cluster way too soon and cause unnecessary recoveries. 🙈
💖 RecoveryDropAllIPs 💖
Default: 120
If a node is stuck in recovery, or stopped, or banned, for this many seconds, then ctdb will release all public addresses on that node. Bye bestie 👋
💖 RecoveryGracePeriod 💖
Default: 120
During recoveries, if a node has not caused any recovery failures during the last grace period (in seconds), then any records of transgressions from that node causing recovery failures get forgiven. This resets the ban-counter back to zero for that node. ✨ A clean slate, we love to see it.
💖 RepackLimit 💖
Default: 10000
During vacuuming, if the number of freelist records is more than RepackLimit, then the database is repacked to get rid of the freelist records and avoid fragmentation. 🧼
💖 RerecoveryTimeout 💖
Default: 10
Once a recovery has completed, no additional recoveries are permitted until this timeout (in seconds) has expired. Chill for a sec, damn. 😌
💖 SeqnumInterval 💖
Default: 1000
Some databases have seqnum tracking enabled, so that samba can detect asynchronously when there have been updates to the database. Every time a database is updated, its sequence number goes up.
This tunable specifies, in milliseconds, how frequently ctdb sends out updates to remote nodes to let them know the sequence number has increased. 📢
💖 StatHistoryInterval 💖
Default: 1
Granularity of the statistics collected in the statistics history. This is what gets reported by the ctdb stats command.
💖 StickyDuration 💖
Default: 600
Once a record has been marked STICKY, this is the duration in seconds that the record will be flagged as a STICKY record. 🍯
💖 StickyPindown 💖
Default: 200
Once a STICKY record has been migrated onto a node, it gets pinned down on that node for this number of milliseconds. Any request from other nodes to migrate the record off the node gets deferred. Not on my watch. 💅
💖 TakeoverTimeout 💖
Default: 9
This is the duration in seconds in which ctdb tries to complete IP failover.
💖 TickleUpdateInterval 💖
Default: 20
Every TickleUpdateInterval seconds, ctdb synchronizes the client connection information across nodes. 🦋
💖 TraverseTimeout 💖
Default: 20
This is the duration in seconds that a database traverse is allowed to run for. If the traverse doesn't complete during this interval, ctdb will abort the traverse. Sorry, time's up! ⏰
💖 VacuumFastPathCount 💖
Default: 60
During a vacuuming run, ctdb usually processes only the records marked for deletion — also known as fast path vacuuming. After finishing VacuumFastPathCount number of fast path vacuuming runs, ctdb will trigger a scan of the complete database for any empty records that need to be deleted. 🧹✨
💖 VacuumInterval 💖
Default: 10
Periodic interval, in seconds, when vacuuming is triggered for volatile databases.
💖 VacuumMaxRunTime 💖
Default: 120
The maximum time in seconds that the vacuuming process is allowed to run for. If the vacuuming process takes longer than this value, then it gets terminated. 🛑
💖 VerboseMemoryNames 💖
Default: 0
When set to non-zero, ctdb assigns verbose names to some of the talloc allocated memory objects. These names are visible in the talloc memory report generated by ctdb dumpmemory. Very slay for debugging. 🔍
🌈 FILES 🌈
/etc/ctdb/ctdb.tunables/etc/ctdb/tunables.d/*.tunables
🫶 SEE ALSO 🫶
ctdb(1), ctdbd(1), ctdb.conf(5), ctdb(7), http://ctdb.samba.org/
👑 AUTHOR 👑
This documentation was written by Ronnie Sahlberg, Amitay Isaacs, Martin Schwenke. Legends, fr fr. 💖
🎀 COPYRIGHT 🎀
Copyright © 2007 Andrew Tridgell, Ronnie Sahlberg
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses.
And that's a wrap on CTDB-TUNABLES(7), bestie — courtesy of ctdb, dated 09/13/2026. Tune responsibly, mwah 💅🌸
📦 where this page comes from
- ubuntu stonking: ctdb 2:4.24.7+dfsg-1ubuntu1 · GPL-3.0-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms