ctdb/doc/ctdb.conf.5.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   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>recovery 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 recovery lock please see the
 186             <citetitle>RECOVERY 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 recovery lock is
 192             <emphasis>strongly recommended</emphasis>.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term>node address = <parameter>IPADDR</parameter></term>
 199         <listitem>
 200           <para>
 201             IPADDR is the private IP address that ctdbd will bind to.
 202           </para>
 203           <para>
 204             This option is only required when automatic address
 205             detection can not be used.  This can be the case when
 206             running multiple ctdbd daemons/nodes on the same physical
 207             host (usually for testing), using InfiniBand for the
 208             private network or on Linux when sysctl
 209             net.ipv4.ip_nonlocal_bind=1.
 210           </para>
 211           <para>
 212             Default: CTDB selects the first address from the nodes
 213             list that it can bind to.  See also the <citetitle>PRIVATE
 214             ADDRESS</citetitle> section in
 215             <citerefentry><refentrytitle>ctdb</refentrytitle>
 216             <manvolnum>7</manvolnum></citerefentry>.
 217           </para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term>transport = tcp|ib</term>
 223         <listitem>
 224           <para>
 225             This option specifies which transport to use for ctdbd
 226             internode communications on the private network.
 227           </para>
 228           <para>
 229             <literal>ib</literal> means InfiniBand.  The InfiniBand
 230             support is not regularly tested.  If it is known to be
 231             broken then it may be disabled so that a value of
 232             <literal>ib</literal> is considered invalid.
 233           </para>
 234           <para>
 235             Default: <literal>tcp</literal>
 236           </para>
 237         </listitem>
 238       </varlistentry>
 239
 240     </variablelist>
 241   </refsect1>
 242
 243   <refsect1>
 244     <title>
 245       DATABASE CONFIGURATION
 246     </title>
 247
 248     <para>
 249       Options in this section affect the CTDB database setup. They
 250       are valid within the <emphasis>database</emphasis> section of
 251       file, indicated by <literal>[database]</literal>.
 252     </para>
 253
 254     <variablelist>
 255
 256       <varlistentry>
 257         <term>volatile database directory = <parameter>DIRECTORY</parameter></term>
 258         <listitem>
 259           <para>
 260             DIRECTORY on local storage where CTDB keeps a local copy
 261             of volatile TDB databases.  This directory is local for
 262             each node and should not be stored on the shared cluster
 263             filesystem.
 264           </para>
 265           <para>
 266             Mounting a tmpfs (or similar memory filesystem) on this
 267             directory can provide a significant performance
 268             improvement when there is I/O contention on the local
 269             disk.
 270           </para>
 271           <para>
 272             Default: <filename>/usr/local/var/lib/ctdb/volatile</filename>
 273           </para>
 274         </listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term>persistent database directory=<parameter>DIRECTORY</parameter></term>
 279         <listitem>
 280           <para>
 281             DIRECTORY on local storage where CTDB keeps a local copy
 282             of persistent TDB databases.  This directory is local for
 283             each node and should not be stored on the shared cluster
 284             filesystem.
 285           </para>
 286           <para>
 287             Default: <filename>/usr/local/var/lib/ctdb/persistent</filename>
 288           </para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term>state database directory = <parameter>DIRECTORY</parameter></term>
 294         <listitem>
 295           <para>
 296             DIRECTORY on local storage where CTDB keeps a local copy
 297             of internal state TDB databases.  This directory is local
 298             for each node and should not be stored on the shared
 299             cluster filesystem.
 300           </para>
 301           <para>
 302             Default: <filename>/usr/local/var/lib/ctdb/state</filename>
 303           </para>
 304         </listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term>tdb mutexes = true|false</term>
 309         <listitem>
 310           <para>
 311             This parameter enables TDB_MUTEX_LOCKING feature on
 312             volatile databases if the robust mutexes are
 313             supported. This optimizes the record locking using robust
 314             mutexes and is much more efficient that using posix locks.
 315           </para>
 316           <para>
 317             If robust mutexes are unreliable on the platform being
 318             used then they can be disabled by setting this to
 319             <literal>false</literal>.
 320           </para>
 321         </listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term>lock debug script = <parameter>FILENAME</parameter></term>
 326         <listitem>
 327           <para>
 328             FILENAME is a script used by CTDB's database locking code
 329             to attempt to provide debugging information when CTDB is
 330             unable to lock an entire database or a record.
 331           </para>
 332           <para>
 333             This script should be a bare filename relative to the CTDB
 334             configuration directory
 335             (<filename>/usr/local/etc/ctdb/</filename>).  Any
 336             directory prefix is ignored and the path is calculated
 337             relative to this directory.
 338           </para>
 339           <para>
 340             CTDB provides a lock debugging script and installs it as
 341             <filename>/usr/local/etc/ctdb/debug_locks.sh</filename>.
 342           </para>
 343           <para>
 344             Default: NONE
 345           </para>
 346         </listitem>
 347       </varlistentry>
 348
 349     </variablelist>
 350   </refsect1>
 351
 352   <refsect1>
 353     <title>
 354       EVENT HANDLING CONFIGURATION
 355     </title>
 356
 357     <para>
 358       Options in this section affect CTDB event handling. They are
 359       valid within the <emphasis>event</emphasis> section of file,
 360       indicated by <literal>[event]</literal>.
 361     </para>
 362
 363     <variablelist>
 364
 365       <varlistentry>
 366         <term>debug script = <parameter>FILENAME</parameter></term>
 367         <listitem>
 368           <para>
 369             FILENAME is a script used by CTDB's event handling code to
 370             attempt to provide debugging information when an event
 371             times out.
 372           </para>
 373           <para>
 374             This script should be a bare filename relative to the CTDB
 375             configuration directory
 376             (<filename>/usr/local/etc/ctdb/</filename>).  Any
 377             directory prefix is ignored and the path is calculated
 378             relative to this directory.
 379           </para>
 380           <para>
 381             CTDB provides a script for debugging timed out event
 382             scripts and installs it as
 383             <filename>/usr/local/etc/ctdb/debug-hung-script.sh</filename>.
 384           </para>
 385           <para>
 386             Default: NONE
 387           </para>
 388         </listitem>
 389       </varlistentry>
 390
 391     </variablelist>
 392   </refsect1>
 393
 394   <refsect1>
 395     <title>
 396       FAILOVER CONFIGURATION
 397     </title>
 398
 399     <para>
 400       Options in this section affect CTDB failover. They are
 401       valid within the <emphasis>failover</emphasis> section of file,
 402       indicated by <literal>[failover]</literal>.
 403     </para>
 404
 405     <variablelist>
 406
 407       <varlistentry>
 408         <term>disabled = true|false</term>
 409         <listitem>
 410           <para>
 411             If set to <literal>true</literal> then public IP failover
 412             is disabled.
 413           </para>
 414           <para>
 415             Default: <literal>false</literal>
 416           </para>
 417         </listitem>
 418       </varlistentry>
 419
 420     </variablelist>
 421   </refsect1>
 422
 423   <refsect1>
 424     <title>
 425       LEGACY CONFIGURATION
 426     </title>
 427
 428     <para>
 429       Options in this section affect legacy CTDB setup. They are valid
 430       within the <emphasis>legacy</emphasis> section of file,
 431       indicated by <literal>[legacy]</literal>.
 432     </para>
 433
 434     <variablelist>
 435
 436       <varlistentry>
 437         <term>ctdb start as stopped = true|false</term>
 438         <listitem>
 439           <para>
 440             If set to <literal>true</literal> CTDB starts in the
 441             STOPPED state.
 442           </para>
 443           <para>
 444             To allow the node to take part in the cluster it must be
 445             manually continued with the <command>ctdb
 446             continue</command> command.
 447           </para>
 448           <para>
 449             Please see the <citetitle>NODE STATES</citetitle> section
 450             in <citerefentry><refentrytitle>ctdb</refentrytitle>
 451             <manvolnum>7</manvolnum></citerefentry> for more
 452             information about the STOPPED state.
 453           </para>
 454           <para>
 455             Default: <literal>false</literal>
 456           </para>
 457         </listitem>
 458       </varlistentry>
 459
 460       <varlistentry>
 461         <term>start as disabled = true|false</term>
 462         <listitem>
 463           <para>
 464             If set to <literal>true</literal> CTDB starts in the
 465             DISABLED state.
 466           </para>
 467           <para>
 468             To allow the node to host public IP addresses and
 469             services, it must be manually enabled using the
 470             <command>ctdb enable</command> command.
 471           </para>
 472           <para>
 473             Please see the <citetitle>NODE STATES</citetitle> section
 474             in <citerefentry><refentrytitle>ctdb</refentrytitle>
 475             <manvolnum>7</manvolnum></citerefentry> for more
 476             information about the DISABLED state.
 477           </para>
 478           <para>
 479             Default: <literal>false</literal>
 480           </para>
 481         </listitem>
 482       </varlistentry>
 483
 484       <varlistentry>
 485         <term>realtime scheduling = true|false</term>
 486         <listitem>
 487           <para>
 488             Usually CTDB runs with real-time priority. This helps it
 489             to perform effectively on a busy system, such as when
 490             there are thousands of Samba clients. If you are running
 491             CTDB on a platform that does not support real-time
 492             priority, you can set this to <literal>false</literal>.
 493           </para>
 494           <para>
 495             Default: <literal>true</literal>
 496           </para>
 497         </listitem>
 498       </varlistentry>
 499
 500       <varlistentry>
 501         <term>recmaster capability = true|false</term>
 502         <listitem>
 503           <para>
 504             Indicates whether a node can become the recovery master
 505             for the cluster. If this is set to
 506             <literal>false</literal> then the node will not be able to
 507             become the recovery master for the cluster. This feature
 508             is primarily used for making a cluster span across a WAN
 509             link and use CTDB as a WAN-accelerator.
 510           </para>
 511           <para>
 512             Please see the <citetitle>REMOTE CLUSTER NODES</citetitle>
 513             section in
 514             <citerefentry><refentrytitle>ctdb</refentrytitle>
 515             <manvolnum>7</manvolnum></citerefentry> for more
 516             information.
 517           </para>
 518           <para>
 519             Default: <literal>true</literal>
 520           </para>
 521         </listitem>
 522       </varlistentry>
 523
 524       <varlistentry>
 525         <term>lmaster capability = true|false</term>
 526         <listitem>
 527           <para>
 528             Indicates whether a node can become a location master for
 529             records in a database. If this is set to
 530             <literal>false</literal> then the node will not be part of
 531             the vnnmap. This feature is primarily used for making a
 532             cluster span across a WAN link and use CTDB as a
 533             WAN-accelerator.
 534           </para>
 535           <para>
 536             Please see the <citetitle>REMOTE CLUSTER NODES</citetitle>
 537             section in
 538             <citerefentry><refentrytitle>ctdb</refentrytitle>
 539             <manvolnum>7</manvolnum></citerefentry> for more
 540             information.
 541           </para>
 542           <para>
 543             Default: <literal>true</literal>
 544           </para>
 545         </listitem>
 546       </varlistentry>
 547
 548       <varlistentry>
 549         <term>script log level = <parameter>LOGLEVEL</parameter></term>
 550         <listitem>
 551           <para>
 552             This option sets the debug level of event script output to
 553             LOGLEVEL.
 554           </para>
 555           <para>
 556             See the <citetitle>DEBUG LEVELS</citetitle> section in
 557             <citerefentry><refentrytitle>ctdb</refentrytitle>
 558             <manvolnum>7</manvolnum></citerefentry> for more
 559             information.
 560           </para>
 561           <para>
 562             Default: <literal>ERROR</literal>
 563           </para>
 564         </listitem>
 565       </varlistentry>
 566
 567     </variablelist>
 568
 569   </refsect1>
 570
 571   <refsect1>
 572     <title>FILES</title>
 573
 574     <simplelist>
 575       <member><filename>/usr/local/etc/ctdb/ctdb.conf</filename></member>
 576     </simplelist>
 577   </refsect1>
 578
 579   <refsect1>
 580     <title>SEE ALSO</title>
 581     <para>
 582       <citerefentry><refentrytitle>ctdbd</refentrytitle>
 583       <manvolnum>1</manvolnum></citerefentry>,
 584
 585       <citerefentry><refentrytitle>onnode</refentrytitle>
 586       <manvolnum>1</manvolnum></citerefentry>,
 587
 588       <citerefentry><refentrytitle>ctdb.sysconfig</refentrytitle>
 589       <manvolnum>5</manvolnum></citerefentry>,
 590
 591       <citerefentry><refentrytitle>ctdb-script.options</refentrytitle>
 592       <manvolnum>5</manvolnum></citerefentry>,
 593
 594       <citerefentry><refentrytitle>ctdb</refentrytitle>
 595       <manvolnum>7</manvolnum></citerefentry>,
 596
 597       <citerefentry><refentrytitle>ctdb-tunables</refentrytitle>
 598       <manvolnum>7</manvolnum></citerefentry>,
 599
 600       <ulink url="http://ctdb.samba.org/"/>
 601     </para>
 602   </refsect1>
 603
 604   <info>
 605     <author>
 606       <contrib>
 607         This documentation was written by
 608         Amitay Isaacs,
 609         Martin Schwenke
 610       </contrib>
 611     </author>
 612
 613     <copyright>
 614       <year>2007</year>
 615       <holder>Andrew Tridgell</holder>
 616       <holder>Ronnie Sahlberg</holder>
 617     </copyright>
 618     <legalnotice>
 619       <para>
 620         This program is free software; you can redistribute it and/or
 621         modify it under the terms of the GNU General Public License as
 622         published by the Free Software Foundation; either version 3 of
 623         the License, or (at your option) any later version.
 624       </para>
 625       <para>
 626         This program is distributed in the hope that it will be
 627         useful, but WITHOUT ANY WARRANTY; without even the implied
 628         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 629         PURPOSE.  See the GNU General Public License for more details.
 630       </para>
 631       <para>
 632         You should have received a copy of the GNU General Public
 633         License along with this program; if not, see
 634         <ulink url="http://www.gnu.org/licenses"/>.
 635       </para>
 636     </legalnotice>
 637   </info>
 638
 639 </refentry>