ctdb/doc/ctdb.conf.5.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry
   3         PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   5
   6 <refentry id="ctdb.conf.5">
   7
   8   <refmeta>
   9     <refentrytitle>ctdb.conf</refentrytitle>
  10     <manvolnum>5</manvolnum>
  11     <refmiscinfo class="source">ctdb</refmiscinfo>
  12     <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
  13   </refmeta>
  14
  15   <refnamediv>
  16     <refname>ctdb.conf</refname>
  17     <refpurpose>CTDB configuration file</refpurpose>
  18   </refnamediv>
  19
  20   <refsect1>
  21     <title>DESCRIPTION</title>
  22
  23     <para>
  24       This file contains CTDB configuration options that affect the
  25       operation of CTDB daemons and command-line tools.  The default
  26       location of this file is
  27       <filename>/usr/local/etc/ctdb/ctdb.conf</filename>.
  28     </para>
  29
  30     <para>
  31       Note that this is a Samba-style configuration file, so it has a
  32       very different syntax to previous CTDB configuration files.
  33     </para>
  34
  35     <para>
  36       For event script options please see
  37       <citerefentry><refentrytitle>ctdb-script.options</refentrytitle>
  38       <manvolnum>5</manvolnum></citerefentry>.
  39     </para>
  40
  41     <para>
  42       Configuration options are grouped into several sections below.
  43       There are only a few options in each section, allowing them to
  44       be ordered (approximately) in decreasing order of importance.
  45     </para>
  46
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>
  51       LOGGING CONFIGURATION
  52     </title>
  53
  54     <para>
  55       Options in this section control CTDB's logging.  They are valid
  56       within the <emphasis>logging</emphasis> section of file,
  57       indicated by <literal>[logging]</literal>.
  58     </para>
  59
  60     <variablelist>
  61
  62       <varlistentry>
  63         <term>log level = <parameter>LOGLEVEL</parameter></term>
  64         <listitem>
  65           <para>
  66             LOGLEVEL is a string that controls the verbosity of
  67             ctdbd's logging.  See the <citetitle>LOG
  68             LEVELS</citetitle> section in
  69             <citerefentry><refentrytitle>ctdb</refentrytitle>
  70             <manvolnum>7</manvolnum></citerefentry> for more details.
  71           </para>
  72           <para>
  73             Default: <literal>NOTICE</literal>
  74           </para>
  75         </listitem>
  76       </varlistentry>
  77
  78       <varlistentry>
  79         <term>location = <parameter>STRING</parameter></term>
  80         <listitem>
  81           <para>
  82             STRING specifies where ctdbd will write its log.
  83           </para>
  84           <para>
  85             Valid values are:
  86           </para>
  87           <variablelist>
  88             <varlistentry>
  89               <term>file:<parameter>FILENAME</parameter></term>
  90               <listitem>
  91                 <para>
  92                   FILENAME where ctdbd will write its log. This is usually
  93                   <filename>/usr/local/var/log/log.ctdb</filename>.
  94                 </para>
  95               </listitem>
  96             </varlistentry>
  97             <varlistentry>
  98               <term>syslog<optional>:<parameter>METHOD</parameter></optional></term>
  99               <listitem>
 100                 <para>
 101                   CTDB will log to syslog.  By default this will use
 102                   the syslog(3) API.
 103                 </para>
 104                 <para>
 105                   If METHOD is specified then it specifies an
 106                   extension that causes logging to be done in a
 107                   non-blocking fashion.  This can be useful under
 108                   heavy loads that might cause the syslog daemon to
 109                   dequeue messages too slowly, which would otherwise
 110                   cause CTDB to block when logging.  METHOD must be
 111                   one of:
 112                 </para>
 113                 <variablelist>
 114                   <varlistentry>
 115                     <term>nonblocking</term>
 116                     <listitem>
 117                       <para>
 118                         CTDB will log to syslog via
 119                         <filename>/dev/log</filename> in non-blocking
 120                         mode.
 121                       </para>
 122                     </listitem>
 123                   </varlistentry>
 124                   <varlistentry>
 125                     <term>udp</term>
 126                     <listitem>
 127                       <para>
 128                         CTDB will log to syslog via UDP to
 129                         localhost:514.  The syslog daemon must be
 130                         configured to listen on (at least)
 131                         localhost:514.  Most implementations will log
 132                         the messages against hostname "localhost" -
 133                         this is a limit of the implementation for
 134                         compatibility with more syslog daemon
 135                         implementations.
 136                       </para>
 137                     </listitem>
 138                   </varlistentry>
 139                   <varlistentry>
 140                     <term>udp-rfc5424</term>
 141                     <listitem>
 142                       <para>
 143                         As with "udp" but messages are sent in RFC5424
 144                         format.  This method will log the correct
 145                         hostname but is not as widely implemented in
 146                         syslog daemons.
 147                       </para>
 148                     </listitem>
 149                   </varlistentry>
 150                 </variablelist>
 151               </listitem>
 152             </varlistentry>
 153           </variablelist>
 154           <para>
 155             Default:
 156             file:<filename>/usr/local/var/log/log.ctdb</filename>
 157           </para>
 158         </listitem>
 159       </varlistentry>
 160
 161     </variablelist>
 162   </refsect1>
 163
 164   <refsect1>
 165     <title>
 166       CLUSTER CONFIGURATION
 167     </title>
 168
 169     <para>
 170       Options in this section affect the CTDB cluster setup. They
 171       are valid within the <emphasis>cluster</emphasis> section of
 172       file, indicated by <literal>[cluster]</literal>.
 173     </para>
 174
 175     <variablelist>
 176
 177       <varlistentry>
 178         <term>cluster lock = <parameter>LOCK</parameter></term>
 179         <listitem>
 180           <para>
 181             LOCK specifies the cluster-wide mutex used to detect and
 182             prevent a partitioned cluster (or "split brain").
 183           </para>
 184           <para>
 185             For information about the cluster lock please see the
 186             <citetitle>CLUSTER LOCK</citetitle> section in
 187             <citerefentry><refentrytitle>ctdb</refentrytitle>
 188             <manvolnum>7</manvolnum></citerefentry>.
 189           </para>
 190           <para>
 191             Default: NONE.  However, uses of a cluster lock is
 192             <emphasis>strongly recommended</emphasis>.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term>leader capability = true|false</term>
 199         <listitem>
 200           <para>
 201             Indicates whether a node can become the leader
 202             for the cluster. If this is set to
 203             <literal>false</literal> then the node will not be able to
 204             become the leader for the cluster. This feature
 205             is primarily used for making a cluster span across a WAN
 206             link and use CTDB as a WAN-accelerator.
 207           </para>
 208           <para>
 209             Please see the <citetitle>REMOTE CLUSTER NODES</citetitle>
 210             section in
 211             <citerefentry><refentrytitle>ctdb</refentrytitle>
 212             <manvolnum>7</manvolnum></citerefentry> for more
 213             information.
 214           </para>
 215           <para>
 216             Default: <literal>true</literal>
 217           </para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term>leader timeout = <parameter>SECONDS</parameter></term>
 223         <listitem>
 224           <para>
 225             Number of SECONDS without a leader broadcast before a node
 226             triggers an election.
 227           </para>
 228           <para>
 229             Default: <literal>5</literal>
 230           </para>
 231         </listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term>node address = <parameter>IPADDR</parameter></term>
 236         <listitem>
 237           <para>
 238             IPADDR is the private IP address that ctdbd will bind to.
 239           </para>
 240           <para>
 241             This option is only required when automatic address
 242             detection can not be used.  This can be the case when
 243             running multiple ctdbd daemons/nodes on the same physical
 244             host (usually for testing), using InfiniBand for the
 245             private network or on Linux when sysctl
 246             net.ipv4.ip_nonlocal_bind=1.
 247           </para>
 248           <para>
 249             Default: CTDB selects the first address from the nodes
 250             list that it can bind to.  See also the <citetitle>PRIVATE
 251             ADDRESS</citetitle> section in
 252             <citerefentry><refentrytitle>ctdb</refentrytitle>
 253             <manvolnum>7</manvolnum></citerefentry>.
 254           </para>
 255         </listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term>transport = tcp|ib</term>
 260         <listitem>
 261           <para>
 262             This option specifies which transport to use for ctdbd
 263             internode communications on the private network.
 264           </para>
 265           <para>
 266             <literal>ib</literal> means InfiniBand.  The InfiniBand
 267             support is not regularly tested.  If it is known to be
 268             broken then it may be disabled so that a value of
 269             <literal>ib</literal> is considered invalid.
 270           </para>
 271           <para>
 272             Default: <literal>tcp</literal>
 273           </para>
 274         </listitem>
 275       </varlistentry>
 276
 277     </variablelist>
 278   </refsect1>
 279
 280   <refsect1>
 281     <title>
 282       DATABASE CONFIGURATION
 283     </title>
 284
 285     <para>
 286       Options in this section affect the CTDB database setup. They
 287       are valid within the <emphasis>database</emphasis> section of
 288       file, indicated by <literal>[database]</literal>.
 289     </para>
 290
 291     <variablelist>
 292
 293       <varlistentry>
 294         <term>volatile database directory = <parameter>DIRECTORY</parameter></term>
 295         <listitem>
 296           <para>
 297             DIRECTORY on local storage where CTDB keeps a local copy
 298             of volatile TDB databases.  This directory is local for
 299             each node and should not be stored on the shared cluster
 300             filesystem.
 301           </para>
 302           <para>
 303             Mounting a tmpfs (or similar memory filesystem) on this
 304             directory can provide a significant performance
 305             improvement when there is I/O contention on the local
 306             disk.
 307           </para>
 308           <para>
 309             Default: <filename>/usr/local/var/lib/ctdb/volatile</filename>
 310           </para>
 311         </listitem>
 312       </varlistentry>
 313
 314       <varlistentry>
 315         <term>persistent database directory=<parameter>DIRECTORY</parameter></term>
 316         <listitem>
 317           <para>
 318             DIRECTORY on local storage where CTDB keeps a local copy
 319             of persistent TDB databases.  This directory is local for
 320             each node and should not be stored on the shared cluster
 321             filesystem.
 322           </para>
 323           <para>
 324             Default: <filename>/usr/local/var/lib/ctdb/persistent</filename>
 325           </para>
 326         </listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term>state database directory = <parameter>DIRECTORY</parameter></term>
 331         <listitem>
 332           <para>
 333             DIRECTORY on local storage where CTDB keeps a local copy
 334             of internal state TDB databases.  This directory is local
 335             for each node and should not be stored on the shared
 336             cluster filesystem.
 337           </para>
 338           <para>
 339             Default: <filename>/usr/local/var/lib/ctdb/state</filename>
 340           </para>
 341         </listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term>tdb mutexes = true|false</term>
 346         <listitem>
 347           <para>
 348             This parameter enables TDB_MUTEX_LOCKING feature on
 349             volatile databases if the robust mutexes are
 350             supported. This optimizes the record locking using robust
 351             mutexes and is much more efficient that using posix locks.
 352           </para>
 353           <para>
 354             If robust mutexes are unreliable on the platform being
 355             used then they can be disabled by setting this to
 356             <literal>false</literal>.
 357           </para>
 358         </listitem>
 359       </varlistentry>
 360
 361       <varlistentry>
 362         <term>lock debug script = <parameter>FILENAME</parameter></term>
 363         <listitem>
 364           <para>
 365             FILENAME is a script used by CTDB's database locking code
 366             to attempt to provide debugging information when CTDB is
 367             unable to lock an entire database or a record.
 368           </para>
 369           <para>
 370             This script should be a bare filename relative to the CTDB
 371             configuration directory
 372             (<filename>/usr/local/etc/ctdb/</filename>).  Any
 373             directory prefix is ignored and the path is calculated
 374             relative to this directory.
 375           </para>
 376           <para>
 377             CTDB provides a lock debugging script and installs it as
 378             <filename>/usr/local/etc/ctdb/debug_locks.sh</filename>.
 379           </para>
 380           <para>
 381             Default: NONE
 382           </para>
 383         </listitem>
 384       </varlistentry>
 385
 386     </variablelist>
 387   </refsect1>
 388
 389   <refsect1>
 390     <title>
 391       EVENT HANDLING CONFIGURATION
 392     </title>
 393
 394     <para>
 395       Options in this section affect CTDB event handling. They are
 396       valid within the <emphasis>event</emphasis> section of file,
 397       indicated by <literal>[event]</literal>.
 398     </para>
 399
 400     <variablelist>
 401
 402       <varlistentry>
 403         <term>debug script = <parameter>FILENAME</parameter></term>
 404         <listitem>
 405           <para>
 406             FILENAME is a script used by CTDB's event handling code to
 407             attempt to provide debugging information when an event
 408             times out.
 409           </para>
 410           <para>
 411             This script should be a bare filename relative to the CTDB
 412             configuration directory
 413             (<filename>/usr/local/etc/ctdb/</filename>).  Any
 414             directory prefix is ignored and the path is calculated
 415             relative to this directory.
 416           </para>
 417           <para>
 418             CTDB provides a script for debugging timed out event
 419             scripts and installs it as
 420             <filename>/usr/local/etc/ctdb/debug-hung-script.sh</filename>.
 421           </para>
 422           <para>
 423             Default: NONE
 424           </para>
 425         </listitem>
 426       </varlistentry>
 427
 428     </variablelist>
 429   </refsect1>
 430
 431   <refsect1>
 432     <title>
 433       FAILOVER CONFIGURATION
 434     </title>
 435
 436     <para>
 437       Options in this section affect CTDB failover. They are
 438       valid within the <emphasis>failover</emphasis> section of file,
 439       indicated by <literal>[failover]</literal>.
 440     </para>
 441
 442     <variablelist>
 443
 444       <varlistentry>
 445         <term>disabled = true|false</term>
 446         <listitem>
 447           <para>
 448             If set to <literal>true</literal> then public IP failover
 449             is disabled.
 450           </para>
 451           <para>
 452             Default: <literal>false</literal>
 453           </para>
 454         </listitem>
 455       </varlistentry>
 456
 457     </variablelist>
 458   </refsect1>
 459
 460   <refsect1>
 461     <title>
 462       LEGACY CONFIGURATION
 463     </title>
 464
 465     <para>
 466       Options in this section affect legacy CTDB setup. They are valid
 467       within the <emphasis>legacy</emphasis> section of file,
 468       indicated by <literal>[legacy]</literal>.
 469     </para>
 470
 471     <variablelist>
 472
 473       <varlistentry>
 474         <term>ctdb start as stopped = true|false</term>
 475         <listitem>
 476           <para>
 477             If set to <literal>true</literal> CTDB starts in the
 478             STOPPED state.
 479           </para>
 480           <para>
 481             To allow the node to take part in the cluster it must be
 482             manually continued with the <command>ctdb
 483             continue</command> command.
 484           </para>
 485           <para>
 486             Please see the <citetitle>NODE STATES</citetitle> section
 487             in <citerefentry><refentrytitle>ctdb</refentrytitle>
 488             <manvolnum>7</manvolnum></citerefentry> for more
 489             information about the STOPPED state.
 490           </para>
 491           <para>
 492             Default: <literal>false</literal>
 493           </para>
 494         </listitem>
 495       </varlistentry>
 496
 497       <varlistentry>
 498         <term>start as disabled = true|false</term>
 499         <listitem>
 500           <para>
 501             If set to <literal>true</literal> CTDB starts in the
 502             DISABLED state.
 503           </para>
 504           <para>
 505             To allow the node to host public IP addresses and
 506             services, it must be manually enabled using the
 507             <command>ctdb enable</command> command.
 508           </para>
 509           <para>
 510             Please see the <citetitle>NODE STATES</citetitle> section
 511             in <citerefentry><refentrytitle>ctdb</refentrytitle>
 512             <manvolnum>7</manvolnum></citerefentry> for more
 513             information about the DISABLED state.
 514           </para>
 515           <para>
 516             Default: <literal>false</literal>
 517           </para>
 518         </listitem>
 519       </varlistentry>
 520
 521       <varlistentry>
 522         <term>realtime scheduling = true|false</term>
 523         <listitem>
 524           <para>
 525             Usually CTDB runs with real-time priority. This helps it
 526             to perform effectively on a busy system, such as when
 527             there are thousands of Samba clients. If you are running
 528             CTDB on a platform that does not support real-time
 529             priority, you can set this to <literal>false</literal>.
 530           </para>
 531           <para>
 532             Default: <literal>true</literal>
 533           </para>
 534         </listitem>
 535       </varlistentry>
 536
 537       <varlistentry>
 538         <term>lmaster capability = true|false</term>
 539         <listitem>
 540           <para>
 541             Indicates whether a node can become a location master for
 542             records in a database. If this is set to
 543             <literal>false</literal> then the node will not be part of
 544             the vnnmap. This feature is primarily used for making a
 545             cluster span across a WAN link and use CTDB as a
 546             WAN-accelerator.
 547           </para>
 548           <para>
 549             Please see the <citetitle>REMOTE CLUSTER NODES</citetitle>
 550             section in
 551             <citerefentry><refentrytitle>ctdb</refentrytitle>
 552             <manvolnum>7</manvolnum></citerefentry> for more
 553             information.
 554           </para>
 555           <para>
 556             Default: <literal>true</literal>
 557           </para>
 558         </listitem>
 559       </varlistentry>
 560
 561       <varlistentry>
 562         <term>script log level = <parameter>LOGLEVEL</parameter></term>
 563         <listitem>
 564           <para>
 565             This option sets the debug level of event script output to
 566             LOGLEVEL.
 567           </para>
 568           <para>
 569             See the <citetitle>DEBUG LEVELS</citetitle> section in
 570             <citerefentry><refentrytitle>ctdb</refentrytitle>
 571             <manvolnum>7</manvolnum></citerefentry> for more
 572             information.
 573           </para>
 574           <para>
 575             Default: <literal>ERROR</literal>
 576           </para>
 577         </listitem>
 578       </varlistentry>
 579
 580     </variablelist>
 581
 582   </refsect1>
 583
 584   <refsect1>
 585     <title>FILES</title>
 586
 587     <simplelist>
 588       <member><filename>/usr/local/etc/ctdb/ctdb.conf</filename></member>
 589     </simplelist>
 590   </refsect1>
 591
 592   <refsect1>
 593     <title>SEE ALSO</title>
 594     <para>
 595       <citerefentry><refentrytitle>ctdbd</refentrytitle>
 596       <manvolnum>1</manvolnum></citerefentry>,
 597
 598       <citerefentry><refentrytitle>onnode</refentrytitle>
 599       <manvolnum>1</manvolnum></citerefentry>,
 600
 601       <citerefentry><refentrytitle>ctdb.sysconfig</refentrytitle>
 602       <manvolnum>5</manvolnum></citerefentry>,
 603
 604       <citerefentry><refentrytitle>ctdb-script.options</refentrytitle>
 605       <manvolnum>5</manvolnum></citerefentry>,
 606
 607       <citerefentry><refentrytitle>ctdb</refentrytitle>
 608       <manvolnum>7</manvolnum></citerefentry>,
 609
 610       <citerefentry><refentrytitle>ctdb-tunables</refentrytitle>
 611       <manvolnum>7</manvolnum></citerefentry>,
 612
 613       <ulink url="http://ctdb.samba.org/"/>
 614     </para>
 615   </refsect1>
 616
 617   <info>
 618     <author>
 619       <contrib>
 620         This documentation was written by
 621         Amitay Isaacs,
 622         Martin Schwenke
 623       </contrib>
 624     </author>
 625
 626     <copyright>
 627       <year>2007</year>
 628       <holder>Andrew Tridgell</holder>
 629       <holder>Ronnie Sahlberg</holder>
 630     </copyright>
 631     <legalnotice>
 632       <para>
 633         This program is free software; you can redistribute it and/or
 634         modify it under the terms of the GNU General Public License as
 635         published by the Free Software Foundation; either version 3 of
 636         the License, or (at your option) any later version.
 637       </para>
 638       <para>
 639         This program is distributed in the hope that it will be
 640         useful, but WITHOUT ANY WARRANTY; without even the implied
 641         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 642         PURPOSE.  See the GNU General Public License for more details.
 643       </para>
 644       <para>
 645         You should have received a copy of the GNU General Public
 646         License along with this program; if not, see
 647         <ulink url="http://www.gnu.org/licenses"/>.
 648       </para>
 649     </legalnotice>
 650   </info>
 651
 652 </refentry>