CTDB.CONF(5)

📦
version 4.24.7 · 18 versions
, in ubuntu stonking

💖 ctdb.conf — the CTDB configuration file 💖

(this is the CTDB.CONF(5) page, bestie — part of the CTDB - clustered TDB database manual, and yes you're gonna wanna read all of it)

🌸 NAME 🌸

ctdb.conf — the CTDB configuration file. that's it, that's the name, iconic.

✨ DESCRIPTION ✨

okay so. this file holds the CTDB config options that change how CTDB daemons and command-line tools actually behave. lowkey important. the default home for it is /etc/ctdb/ctdb.conf.

heads up tho: this is a Samba-style config file, so the syntax is completely different from the older CTDB config files. do not bring your old habits in here, it will not go well. 💀

if you're looking for event script options, those live somewhere else — go read ctdb-script.options(5).

all the options are grouped into the sections below, and there are only a few options per section, which lets them be ordered (roughly) from most important to least important. cute, right? 🎀

🪵 LOGGING CONFIGURATION 🪵

these options control CTDB's logging. they're valid inside the logging section of the file, which you write as [logging].

  • log level = LOGLEVEL — LOGLEVEL is a string that sets how chatty ctdbd's logging is. for all the deets, go check the LOG LEVELS section in ctdb(7).

Default: NOTICE

  • location = STRING — STRING says where ctdbd is gonna write its log. the valid values are:
    • file:FILENAME — FILENAME is where ctdbd writes its log. usually this is /var/log/ctdb/log.ctdb.
    • syslog[:METHOD] — CTDB logs to syslog. by default this uses the syslog(3) API.

if METHOD is given, it picks an extension that makes logging happen in a non-blocking way. this is a lifesaver under heavy loads where the syslog daemon dequeues messages too slowly — without it, CTDB would block while logging 😭. METHOD has to be one of:

  • nonblocking — CTDB logs to syslog via /dev/log in non-blocking mode.
  • udp — CTDB logs to syslog via UDP to localhost:514. the syslog daemon must be configured to listen on (at least) localhost:514. most implementations will log those messages against hostname "localhost" — that's a limit of the implementation, done for compatibility with more syslog daemon implementations.
  • udp-rfc5424 — same as "udp" but the messages go out in RFC5424 format. this method logs the correct hostname, but it's not as widely implemented across syslog daemons. 🙈

Default: file:/var/log/ctdb/log.ctdb

👑 CLUSTER CONFIGURATION 👑

these options affect how the CTDB cluster is set up. they're valid inside the cluster section of the file, which you write as [cluster].

  • cluster lock = LOCK — LOCK is the cluster-wide mutex used to detect and prevent a partitioned cluster (aka "split brain"). for the full story on the cluster lock, see the CLUSTER LOCK section in ctdb(7).

Default: NONE. however, using a cluster lock is strongly recommended. like, strongly. please. 🫶

  • leader capability = true|false — says whether a node is allowed to become the leader for the cluster. set it to false and that node can't be the leader, periodt. this feature is mainly used so a cluster can stretch across a WAN link and use CTDB as a WAN-accelerator.

more info is in the REMOTE CLUSTER NODES section in ctdb(7).

Default: true

  • leader timeout = SECONDS — how many SECONDS can pass with no leader broadcast before a node triggers an election. ⏰

Default: 5

  • node address = IPADDR — IPADDR is the private IP address that ctdbd binds to.

you only need this option when automatic address detection can't be used. that happens when you're running multiple ctdbd daemons/nodes on the same physical host (usually for testing 🧪), or using InfiniBand for the private network. another unlikely case: running on a platform with something like Linux's net.ipv4.ip_nonlocal_bind=1 enabled and no usable getifaddrs(3) implementation (or replacement) available.

Default: CTDB picks the first address from the nodes list that it can bind to. see also the PRIVATE ADDRESS section in ctdb(7).

  • nodes list = SOURCE — SOURCE is where the list of private addresses of the nodes in the cluster lives.

typically SOURCE is a path to a file holding the private addresses for the cluster. for what that file should actually contain, see the PRIVATE ADDRESSES section in ctdb(7).

alternatively, instead of a file you can use an arbitrary command to produce the contents of the nodes list. if an exclamation point ('!') is the first character of the SOURCE value, the rest of the value gets executed when the private addresses need to be read. for example, a value of !/usr/bin/mynodes cluster1 runs that given command with those specified arguments. the output the command generates (on standard out) has to be the same as whatever a SOURCE file supports. the command name must be a full path to an executable. arguments are supported, but shell-style quoting is not, and space characters will always produce a new argument for the command.

⚠️ real talk: running this command blocks until the command has completed. the run time depends on how it's implemented and on environmental factors. be aware that if the command takes a non-trivial amount of time, it can introduce undesirable stalls into ctdbd. not the vibe. 😭

Default: /etc/ctdb/nodes

  • transport = tcp|ib — this one says which transport to use for ctdbd internode communications on the private network.

ib means InfiniBand. fyi the InfiniBand support is not regularly tested. if it's known to be broken then it may be disabled, in which case a value of ib is considered invalid.

Default: tcp

🗄️ DATABASE CONFIGURATION 🗄️

these options affect the CTDB database setup. they're valid inside the database section of the file, which you write as [database].

  • volatile database directory = DIRECTORY — DIRECTORY on local storage where CTDB keeps a local copy of volatile TDB databases. this directory is local to each node and should not be stored on the shared cluster filesystem. 🚫

mounting a tmpfs (or similar memory filesystem) on this directory can give you a significant performance improvement when there's I/O contention on the local disk. slay. 💅

Default: /var/lib/ctdb/volatile

  • persistent database directory=DIRECTORY — DIRECTORY on local storage where CTDB keeps a local copy of persistent TDB databases. this directory is local to each node and should not be stored on the shared cluster filesystem.

Default: /var/lib/ctdb/persistent

  • state database directory = DIRECTORY — DIRECTORY on local storage where CTDB keeps a local copy of internal state TDB databases. this directory is local to each node and should not be stored on the shared cluster filesystem.

Default: /var/lib/ctdb/state

  • tdb mutexes = true|false — this parameter enables the TDB_MUTEX_LOCKING feature on volatile databases, if robust mutexes are supported. it optimizes record locking using robust mutexes, and that is much more efficient than using posix locks. efficiency ate, honestly. 🔥

if robust mutexes are unreliable on the platform you're on, you can turn them off by setting this to false.

  • lock debug script = FILENAME — FILENAME is a script that CTDB's database locking code uses to try to provide debugging information when CTDB can't lock an entire database or a record.

this script should be a bare filename relative to the CTDB configuration directory (/etc/ctdb/). any directory prefix is ignored and the path is calculated relative to that directory.

CTDB ships a lock debugging script and installs it as /etc/ctdb/debug_locks.sh.

Default: NONE

🎪 EVENT HANDLING CONFIGURATION 🎪

these options affect CTDB event handling. they're valid inside the event section of the file, which you write as [event].

  • debug script = FILENAME — FILENAME is a script that CTDB's event handling code uses to try to provide debugging information when an event times out.

this script should be a bare filename relative to the CTDB configuration directory (/etc/ctdb/). any directory prefix is ignored and the path is calculated relative to that directory.

CTDB ships a script for debugging timed out event scripts and installs it as /etc/ctdb/debug-hung-script.sh.

Default: NONE

🦋 FAILOVER CONFIGURATION 🦋

these options affect CTDB failover. they're valid inside the failover section of the file, which you write as [failover].

  • disabled = true|false — if this is set to true then public IP failover is disabled. 🛑

Default: false

  • shutdown extra timeout = TIMEOUT — CTDB will wait TIMEOUT seconds after failover completes during shutdown. this can give extra time for SMB durable handles to be reclaimed. if it's set to 0 then no extra timeout happens.

this timeout only occurs if both of these conditions are true:

  • shutdown failover timeout (below) is not 0
  • failover during shutdown completes and does not time out

Default: 0

  • shutdown failover timeout = TIMEOUT — CTDB will wait TIMEOUT seconds for failover to complete during shutdown. this lets NFS servers on other nodes go into grace during a graceful shutdown of a node. failover during shutdown also helps with SMB durable handle reclaim.

set this to 0 to disable explicit failover on shutdown.

Default: 10

👵 LEGACY CONFIGURATION 👵

Okay so this section is the vintage corner of the config file, bestie. Everything in here affects legacy CTDB setup, and these options are only valid inside the legacy section of the file — the one you mark with [legacy]. No cap. So if you drop them in the wrong section, they're just gonna sit there doing nothing and that's on you 💀

  • ctdb start as stopped = true|false — set this to true and CTDB boots up already in the STOPPED state. Which means, bestie, your node is not joining the party yet 😭 To let it actually take part in the cluster you have to manually nudge it along with the ctdb continue command. For the whole scoop on what the STOPPED state even means, go peek at the NODE STATES section in ctdb(7).

Default: false

  • start as disabled = true|false — set this to true and CTDB starts in the DISABLED state instead. If you want the node to host public IP addresses and services, you gotta manually switch it on using the ctdb enable command. Again, the NODE STATES section in ctdb(7) has the full tea on the DISABLED state.

Default: false

  • realtime scheduling = true|false — normally CTDB runs with real-time priority, because obviously ✨ that's how it stays snappy on a busy system, like when there are thousands of Samba clients all up in your business. But if you're running CTDB somewhere that just doesn't support real-time priority, you can flip this to false.

Default: true

  • lmaster capability = true|false — this decides whether a node can be a location master for records in a database. Set it to false and that node will not be part of the vnnmap. The main character use case here is making a cluster stretch across a WAN link and using CTDB as a WAN-accelerator 🦋 The REMOTE CLUSTER NODES section in ctdb(7) has more if you're curious.

Default: true

  • script log level = LOGLEVEL — sets the debug level of event script output to LOGLEVEL. Wanna know what levels exist? The DEBUG LEVELS section in ctdb(7) is right there, go read it bestie 💅

Default: ERROR

📁 FILES 📁

  • /etc/ctdb/ctdb.conf

It's giving "one file to rule them all" fr fr 👑

👀 SEE ALSO 👀

ctdbd(1), onnode(1), ctdb.sysconfig(5), ctdb-script.options(5), ctdb(7), ctdb-tunables(7), http://ctdb.samba.org/

(the whole friend group, together at last 🫶)

✍️ AUTHOR ✍️

This documentation was written by Amitay Isaacs, Martin Schwenke. Legends, honestly 🎀

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. (legal girlies stay winning ⭐)

aaaand that's the whole page bestie, we ate that 🍓 this lil masterpiece is from the ctdb collection, dated 09/13/2026, and it lives at CTDB.CONF(5) — go forth and configure responsibly 💖✨

📦 where this page comes from