ctdb/doc/ctdbd.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="ctdbd.conf.5">
   7
   8   <refmeta>
   9     <refentrytitle>ctdbd.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>ctdbd.conf</refname>
  17     <refpurpose>CTDB daemon configuration file</refpurpose>
  18   </refnamediv>
  19
  20   <refsect1>
  21     <title>DESCRIPTION</title>
  22
  23     <para>
  24       This file contains CTDB configuration variables that are affect
  25       the operation of CTDB.  The default location of this file is
  26       <filename>/usr/local/etc/ctdb/ctdbd.conf</filename>.
  27     </para>
  28
  29     <para>
  30       This file is a shell script (see
  31       <citerefentry><refentrytitle>sh</refentrytitle>
  32       <manvolnum>1</manvolnum></citerefentry>) but is usually limited
  33       to simple variable assignments and shell-style comments.
  34     </para>
  35
  36     <para>
  37       CTDB configuration variables are grouped into several categories below.
  38     </para>
  39
  40     <para>
  41       Variables defined in this document can also be set in a
  42       distribution-specific configuration file such as
  43       <filename>/etc/sysconfig/ctdb</filename> (Red Hat) or
  44       <filename>/etc/default/ctdb</filename> (Debian).  However, these
  45       files should be reserved for variables used by the initscript.
  46       A historical alternative is
  47       <filename>/usr/local/etc/ctdb/sysconfig/ctdb</filename> - this is
  48       deprecated.
  49     </para>
  50
  51   </refsect1>
  52
  53   <refsect1>
  54     <title>
  55       INITSCRIPT CONFIGURATION
  56     </title>
  57
  58     <para>
  59       Some options must be available to the initscript so they need to
  60       be set in the distribution-specific initscript configuration,
  61       such as <filename>/etc/sysconfig/ctdb</filename> or
  62       <filename>/etc/default/ctdb</filename>.
  63     </para>
  64
  65     <variablelist>
  66
  67       <varlistentry>
  68         <term>CTDB_PIDFILE=<parameter>FILENAME</parameter></term>
  69         <listitem>
  70           <para>
  71             FILENAME is the name of the file used to contain the
  72             process ID (PID) of the main CTDB daemon when it is
  73             running.  This is passed from the initscript to
  74             <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
  75             <manvolnum>1</manvolnum></citerefentry>.
  76           </para>
  77
  78           <para>
  79             Default is <filename>/usr/local/var/run/ctdb/ctdbd.pid</filename>.
  80             Corresponds to <option>--pidfile</option>.
  81           </para>
  82         </listitem>
  83       </varlistentry>
  84
  85     </variablelist>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>
  90       GLOBAL CONFIGURATION
  91     </title>
  92
  93     <para>
  94       These options may be used in the initscripts, daemon and
  95       scripts.
  96     </para>
  97
  98     <variablelist>
  99
 100       <varlistentry>
 101         <term>CTDB_BASE=<parameter>DIRECTORY</parameter></term>
 102         <listitem>
 103           <para>
 104             DIRECTORY containing CTDB scripts and configuration files.
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108
 109     </variablelist>
 110   </refsect1>
 111
 112   <refsect1>
 113     <title>
 114       DAEMON CONFIGURATION
 115     </title>
 116
 117     <para>
 118       Variables in this section are processed by
 119       <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
 120       <manvolnum>1</manvolnum></citerefentry> and are converted into
 121       command-line arguments to
 122       <citerefentry><refentrytitle>ctdbd</refentrytitle>
 123       <manvolnum>1</manvolnum></citerefentry>.  Correspondence with
 124       <citerefentry><refentrytitle>ctdbd</refentrytitle>
 125       <manvolnum>1</manvolnum></citerefentry> options is shown for
 126       each variable.  The the documentation for the relevant options
 127       for more details.
 128     </para>
 129
 130     <para>
 131       Many of these variables are also used by event scripts.
 132     </para>
 133
 134     <variablelist>
 135
 136       <varlistentry>
 137         <term>CTDB_CAPABILITY_LMASTER=yes|no</term>
 138         <listitem>
 139           <para>
 140             Defaults to yes.  Corresponds to <option>--no-lmaster</option>.
 141           </para>
 142         </listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term>CTDB_CAPABILITY_RECMASTER=yes|no</term>
 147         <listitem>
 148           <para>
 149             Defaults to yes.  Corresponds to
 150             <option>--no-recmaster</option>.
 151           </para>
 152         </listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term>CTDB_DBDIR=<parameter>DIRECTORY</parameter></term>
 157         <listitem>
 158           <para>
 159             Defaults to <filename>/usr/local/var/lib/ctdb</filename>.
 160           </para>
 161           <para>
 162             Apart from a DIRECTORY, this can take a special value of
 163             the form
 164             <option>tmpfs</option><optional>:<parameter>OPTIONS</parameter></optional>.
 165             OPTIONS is a comma-separated list of any permissible
 166             options to the tmpfs filesystem.  The only pre-specified
 167             default is <option>mode=700</option>, which can
 168             overriden by specifying <option>mode</option> in
 169             OPTIONS.  It probably makes sense to specify a maximum
 170             <option>size</option>.
 171           </para>
 172           <para>
 173             Corresponds to <option>--dbdir</option>.
 174           </para>
 175         </listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term>CTDB_DBDIR_PERSISTENT=<parameter>DIRECTORY</parameter></term>
 180         <listitem>
 181           <para>
 182             Defaults to <filename>/usr/local/var/lib/ctdb/persistent</filename>.
 183           </para>
 184           <para>
 185             Corresponds to <option>--dbdir-persistent</option>.
 186           </para>
 187         </listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term>CTDB_DBDIR_STATE=<parameter>DIRECTORY</parameter></term>
 192         <listitem>
 193           <para>
 194             Defaults to <filename>/usr/local/var/lib/ctdb/state</filename>.
 195           </para>
 196           <para>
 197             Corresponds to <option>--dbdir-state</option>.
 198           </para>
 199         </listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term>CTDB_DEBUGLEVEL=<parameter>DEBUGLEVEL</parameter></term>
 204         <listitem>
 205           <para>
 206             Default is NOTICE (2).  Corresponds to <option>-d</option> or
 207             <option>--debug</option>.
 208           </para>
 209         </listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term>CTDB_EVENT_SCRIPT_DIR=<parameter>DIRECTORY</parameter></term>
 214         <listitem>
 215           <para>
 216             Default is <varname>CTDB_BASE</varname>/events.d, so usually
 217             <filename>/usr/local/etc/ctdb/events.d</filename>.  Corresponds to
 218             <option>--event-script-dir</option>.
 219           </para>
 220         </listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term>CTDB_LOGGING=<parameter>STRING</parameter></term>
 225         <listitem>
 226           <para>
 227             STRING specifies where ctdbd will write its log. The
 228             default is
 229             file:<filename>/usr/local/var/log/log.ctdb</filename>.
 230             Corresponds to <option>--logging</option>.
 231           </para>
 232           <para>
 233             Valid values are:
 234           </para>
 235           <variablelist>
 236             <varlistentry>
 237               <term>file:<parameter>FILENAME</parameter></term>
 238               <listitem>
 239                 <para>
 240                   FILENAME where ctdbd will write its log. This is usually
 241                   <filename>/usr/local/var/log/log.ctdb</filename>.
 242                 </para>
 243               </listitem>
 244             </varlistentry>
 245             <varlistentry>
 246               <term>syslog<optional>:<parameter>METHOD</parameter></optional></term>
 247               <listitem>
 248                 <para>
 249                   CTDB will log to syslog.  By default this will use
 250                   the syslog(3) API.
 251                 </para>
 252                 <para>
 253                   If METHOD is specified then it specifies an
 254                   extension that causes logging to be done in a
 255                   non-blocking fashion.  This can be useful under
 256                   heavy loads that might cause the syslog daemon to
 257                   dequeue messages too slowly, which would otherwise
 258                   cause CTDB to block when logging.  METHOD must be
 259                   one of:
 260                 </para>
 261                 <variablelist>
 262                   <varlistentry>
 263                     <term>nonblocking</term>
 264                     <listitem>
 265                       <para>
 266                         CTDB will log to syslog via
 267                         <filename>/dev/log</filename> in non-blocking
 268                         mode.
 269                       </para>
 270                     </listitem>
 271                   </varlistentry>
 272                   <varlistentry>
 273                     <term>udp</term>
 274                     <listitem>
 275                       <para>
 276                         CTDB will log to syslog via UDP to
 277                         localhost:514.  The syslog daemon must be
 278                         configured to listen on (at least)
 279                         localhost:514.  Most implementations will log
 280                         the messages against hostname "localhost" -
 281                         this is a limit of the implementation for
 282                         compatibility with more syslog daemon
 283                         implementations.
 284                       </para>
 285                     </listitem>
 286                   </varlistentry>
 287                   <varlistentry>
 288                     <term>udp-rfc5424</term>
 289                     <listitem>
 290                       <para>
 291                         As with "udp" but messages are sent in RFC5424
 292                         format.  This method will log the correct
 293                         hostname but is not as widely implemented in
 294                         syslog daemons.
 295                       </para>
 296                     </listitem>
 297                   </varlistentry>
 298                 </variablelist>
 299               </listitem>
 300             </varlistentry>
 301           </variablelist>
 302         </listitem>
 303       </varlistentry>
 304
 305       <varlistentry>
 306         <term>CTDB_NODES=<parameter>FILENAME</parameter></term>
 307         <listitem>
 308           <para>
 309             Default is <varname>CTDB_BASE</varname>/nodes, so usually
 310             <filename>/usr/local/etc/ctdb/nodes</filename>.  Corresponds to
 311             <option>--nlist</option>.
 312           </para>
 313         </listitem>
 314       </varlistentry>
 315
 316       <varlistentry>
 317         <term>CTDB_NOTIFY_SCRIPT=<parameter>FILENAME</parameter></term>
 318         <listitem>
 319           <para>
 320             No default, usually
 321             <filename>/usr/local/etc/ctdb/notify.sh</filename>.  Corresponds to
 322             <option>--notification-script</option>.
 323           </para>
 324         </listitem>
 325       </varlistentry>
 326
 327       <varlistentry>
 328         <term>CTDB_MAX_PERSISTENT_CHECK_ERRORS=<parameter>NUM</parameter></term>
 329         <listitem>
 330           <para>
 331             Default 0.  Corresponds to
 332             <option>--max-persistent-check-errors</option>.
 333           </para>
 334         </listitem>
 335       </varlistentry>
 336
 337       <varlistentry>
 338         <term>CTDB_NODE_ADDRESS=<parameter>IPADDR</parameter></term>
 339         <listitem>
 340           <para>
 341             IPADDR is the private IP address that ctdbd will bind to.
 342             Corresponds to <option>--listen</option>.
 343           </para>
 344           <para>
 345             By default ctdbd will select the first address from the
 346             nodes list that in can bind to.  See also
 347             <citetitle>CTDB_NODES</citetitle>.
 348           </para>
 349           <para>
 350             This option is only required when automatic address
 351             detection can not be used.  This can be the case when
 352             running multiple ctdbd daemons/nodes on the same physical
 353             host (usually for testing), using InfiniBand for the
 354             private network or on Linux when sysctl
 355             net.ipv4.ip_nonlocal_bind=1.
 356           </para>
 357         </listitem>
 358       </varlistentry>
 359
 360       <varlistentry>
 361         <term>CTDB_PUBLIC_ADDRESSES=<parameter>FILENAME</parameter></term>
 362         <listitem>
 363           <para>
 364             No default, usually
 365             <filename>/usr/local/etc/ctdb/public_addresses</filename>.
 366             Corresponds to <option>--public-addresses</option>.
 367           </para>
 368         </listitem>
 369       </varlistentry>
 370
 371       <varlistentry>
 372         <term>CTDB_PUBLIC_INTERFACE=<parameter>INTERFACE</parameter></term>
 373         <listitem>
 374           <para>
 375             No default.  Corresponds to
 376             <option>--public-interface</option>.
 377           </para>
 378         </listitem>
 379       </varlistentry>
 380
 381       <varlistentry>
 382         <term>CTDB_RECOVERY_LOCK=<parameter>FILENAME</parameter></term>
 383         <listitem>
 384           <para>
 385             Defaults to
 386             <filename>/some/place/on/shared/storage</filename>, which
 387             should be change to a useful value.  Corresponds to
 388             <option>--reclock</option>.
 389           </para>
 390           <para>
 391             For information about the recovery lock please see the
 392             <citetitle>RECOVERY LOCK</citetitle> section in
 393             <citerefentry><refentrytitle>ctdb</refentrytitle>
 394             <manvolnum>7</manvolnum></citerefentry>.
 395           </para>
 396         </listitem>
 397       </varlistentry>
 398
 399       <varlistentry>
 400         <term>CTDB_SCRIPT_LOG_LEVEL=<parameter>DEBUGLEVEL</parameter></term>
 401         <listitem>
 402           <para>
 403             Defaults to ERR (0).  Corresponds to
 404             <option>--script-log-level</option>.
 405           </para>
 406         </listitem>
 407       </varlistentry>
 408
 409       <varlistentry>
 410         <term>CTDB_SOCKET=<parameter>FILENAME</parameter></term>
 411         <listitem>
 412           <para>
 413             Defaults to <filename>/usr/local/var/run/ctdb/ctdbd.socket</filename>.
 414             Corresponds to <option>--socket</option>.
 415           </para>
 416           <para>
 417             If you change this then you probably want to set this in
 418             root's environment (perhaps in a file in
 419             <filename>/etc/profile.d</filename>) so that you can use
 420             the <citerefentry><refentrytitle>ctdb</refentrytitle>
 421             <manvolnum>1</manvolnum></citerefentry> command in a
 422             straightforward manner.
 423           </para>
 424         </listitem>
 425       </varlistentry>
 426
 427       <varlistentry>
 428         <term>CTDB_START_AS_DISABLED=yes|no</term>
 429         <listitem>
 430           <para>
 431             Default is no.  Corresponds to
 432             <option>--start-as-disabled</option>.
 433           </para>
 434         </listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term>CTDB_START_AS_STOPPED=yes|no</term>
 439         <listitem>
 440           <para>
 441             Default is no.  Corresponds to
 442             <option>--start-as-stopped</option>.
 443           </para>
 444         </listitem>
 445       </varlistentry>
 446
 447       <varlistentry>
 448         <term>CTDB_TRANSPORT=tcp|infiniband</term>
 449         <listitem>
 450           <para>
 451             Defaults to tcp.  Corresponds to
 452             <option>--transport</option>.
 453           </para>
 454         </listitem>
 455       </varlistentry>
 456
 457     </variablelist>
 458
 459     <para>
 460       While the following variables do not translate into daemon
 461       options they are used by
 462       <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
 463       <manvolnum>1</manvolnum></citerefentry> when starting and
 464       stopping <citerefentry><refentrytitle>ctdbd</refentrytitle>
 465       <manvolnum>1</manvolnum></citerefentry>.
 466     </para>
 467
 468     <variablelist>
 469
 470       <varlistentry>
 471         <term>CTDB_SHUTDOWN_TIMEOUT=<parameter>NUM</parameter></term>
 472         <listitem>
 473           <para>
 474             NUM is the number of seconds to wait for
 475             <citerefentry><refentrytitle>ctdbd</refentrytitle>
 476             <manvolnum>1</manvolnum></citerefentry> to shut down
 477             gracefully before giving up and killing it.
 478           </para>
 479
 480           <para>
 481             Defaults is 30.
 482           </para>
 483         </listitem>
 484       </varlistentry>
 485
 486       <varlistentry>
 487         <term>CTDB_STARTUP_TIMEOUT=<parameter>NUM</parameter></term>
 488         <listitem>
 489           <para>
 490             NUM is the number of seconds to wait for
 491             <citerefentry><refentrytitle>ctdbd</refentrytitle>
 492             <manvolnum>1</manvolnum></citerefentry> complete early
 493             initialisation up to a point where it is unlikely to
 494             abort.  If <command>ctdbd</command> doesn't complete the
 495             "setup" event before this timeout then it is killed.
 496           </para>
 497
 498           <para>
 499             Defaults is 10.
 500           </para>
 501         </listitem>
 502       </varlistentry>
 503
 504     </variablelist>
 505   </refsect1>
 506
 507   <refsect1>
 508     <title>NETWORK CONFIGURATION</title>
 509
 510     <refsect2>
 511       <title>NAT GATEWAY</title>
 512
 513       <para>
 514         NAT gateway is used to configure fallback routing for nodes
 515         when they do not host any public IP addresses.  For example,
 516         it allows unhealthy nodes to reliably communicate with
 517         external infrastructure.  One node in a NAT gateway group will
 518         be designated as the NAT gateway master node and other (slave)
 519         nodes will be configured with fallback routes via the NAT
 520         gateway master node.  For more information, see the
 521         <citetitle>NAT GATEWAY</citetitle> section in
 522         <citerefentry><refentrytitle>ctdb</refentrytitle>
 523         <manvolnum>7</manvolnum></citerefentry>.
 524       </para>
 525
 526       <variablelist>
 527
 528         <varlistentry>
 529           <term>CTDB_NATGW_DEFAULT_GATEWAY=<parameter>IPADDR</parameter></term>
 530           <listitem>
 531             <para>
 532               IPADDR is an alternate network gateway to use on the NAT
 533               gateway master node.  If set, a fallback default route
 534               is added via this network gateway.
 535             </para>
 536             <para>
 537               No default.  Setting this variable is optional - if not
 538               set that no route is created on the NAT gateway master
 539               node.
 540             </para>
 541           </listitem>
 542         </varlistentry>
 543
 544         <varlistentry>
 545           <term>CTDB_NATGW_NODES=<parameter>FILENAME</parameter></term>
 546           <listitem>
 547             <para>
 548               FILENAME contains the list of nodes that belong to the
 549               same NAT gateway group.
 550             </para>
 551             <para>
 552               File format:
 553               <screen>
 554 <parameter>IPADDR</parameter> <optional>slave-only</optional>
 555               </screen>
 556             </para>
 557             <para>
 558               IPADDR is the private IP address of each node in the NAT
 559               gateway group.
 560             </para>
 561             <para>
 562               If "slave-only" is specified then the corresponding node
 563               can not be the NAT gateway master node.  In this case
 564               <varname>CTDB_NATGW_PUBLIC_IFACE</varname> and
 565               <varname>CTDB_NATGW_PUBLIC_IP</varname> are optional and
 566               unused.
 567             </para>
 568             <para>
 569               No default, usually
 570               <filename>/usr/local/etc/ctdb/natgw_nodes</filename> when enabled.
 571             </para>
 572           </listitem>
 573         </varlistentry>
 574
 575         <varlistentry>
 576           <term>CTDB_NATGW_PRIVATE_NETWORK=<parameter>IPADDR/MASK</parameter></term>
 577           <listitem>
 578             <para>
 579               IPADDR/MASK is the private sub-network that is
 580               internally routed via the NAT gateway master node.  This
 581               is usually the private network that is used for node
 582               addresses.
 583             </para>
 584             <para>
 585               No default.
 586             </para>
 587           </listitem>
 588         </varlistentry>
 589
 590         <varlistentry>
 591           <term>CTDB_NATGW_PUBLIC_IFACE=<parameter>IFACE</parameter></term>
 592           <listitem>
 593             <para>
 594               IFACE is the network interface on which the
 595               CTDB_NATGW_PUBLIC_IP will be configured.
 596             </para>
 597             <para>
 598               No default.
 599             </para>
 600           </listitem>
 601         </varlistentry>
 602
 603         <varlistentry>
 604           <term>CTDB_NATGW_PUBLIC_IP=<parameter>IPADDR/MASK</parameter></term>
 605           <listitem>
 606             <para>
 607               IPADDR/MASK indicates the IP address that is used for
 608               outgoing traffic (originating from
 609               CTDB_NATGW_PRIVATE_NETWORK) on the NAT gateway master
 610               node.  This <emphasis>must not</emphasis> be a
 611               configured public IP address.
 612             </para>
 613             <para>
 614               No default.
 615             </para>
 616           </listitem>
 617         </varlistentry>
 618
 619         <varlistentry>
 620           <term>CTDB_NATGW_STATIC_ROUTES=<parameter>IPADDR/MASK[@GATEWAY]</parameter> ...</term>
 621           <listitem>
 622             <para>
 623               Each IPADDR/MASK identifies a network or host to which
 624               NATGW should create a fallback route, instead of
 625               creating a single default route.  This can be used when
 626               there is already a default route, via an interface that
 627               can not reach required infrastructure, that overrides
 628               the NAT gateway default route.
 629             </para>
 630             <para>
 631               If GATEWAY is specified then the corresponding route on
 632               the NATGW master node will be via GATEWAY.  Such routes
 633               are created even if
 634               <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is not
 635               specified.  If GATEWAY is not specified for some
 636               networks then routes are only created on the NATGW
 637               master node for those networks if
 638               <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is
 639               specified.
 640             </para>
 641             <para>
 642               This should be used with care to avoid causing traffic
 643               to unnecessarily double-hop through the NAT gateway
 644               master, even when a node is hosting public IP addresses.
 645               Each specified network or host should probably have a
 646               corresponding automatically created link route or static
 647               route to avoid this.
 648             </para>
 649             <para>
 650               No default.
 651             </para>
 652           </listitem>
 653         </varlistentry>
 654
 655       </variablelist>
 656
 657       <refsect3>
 658         <title>Example</title>
 659         <screen>
 660 CTDB_NATGW_NODES=/usr/local/etc/ctdb/natgw_nodes
 661 CTDB_NATGW_PRIVATE_NETWORK=192.168.1.0/24
 662 CTDB_NATGW_DEFAULT_GATEWAY=10.0.0.1
 663 CTDB_NATGW_PUBLIC_IP=10.0.0.227/24
 664 CTDB_NATGW_PUBLIC_IFACE=eth0
 665         </screen>
 666
 667         <para>
 668           A variation that ensures that infrastructure (ADS, DNS, ...)
 669           directly attached to the public network (10.0.0.0/24) is
 670           always reachable would look like this:
 671         </para>
 672         <screen>
 673 CTDB_NATGW_NODES=/usr/local/etc/ctdb/natgw_nodes
 674 CTDB_NATGW_PRIVATE_NETWORK=192.168.1.0/24
 675 CTDB_NATGW_PUBLIC_IP=10.0.0.227/24
 676 CTDB_NATGW_PUBLIC_IFACE=eth0
 677 CTDB_NATGW_STATIC_ROUTES=10.0.0.0/24
 678         </screen>
 679         <para>
 680           Note that <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is
 681           not specified.
 682         </para>
 683       </refsect3>
 684
 685     </refsect2>
 686
 687     <refsect2>
 688       <title>POLICY ROUTING</title>
 689
 690       <para>
 691         A node running CTDB may be a component of a complex network
 692         topology.  In particular, public addresses may be spread
 693         across several different networks (or VLANs) and it may not be
 694         possible to route packets from these public addresses via the
 695         system's default route.  Therefore, CTDB has support for
 696         policy routing via the <filename>13.per_ip_routing</filename>
 697         eventscript.  This allows routing to be specified for packets
 698         sourced from each public address.  The routes are added and
 699         removed as CTDB moves public addresses between nodes.
 700       </para>
 701
 702       <para>
 703         For more information, see the <citetitle>POLICY
 704         ROUTING</citetitle> section in
 705         <citerefentry><refentrytitle>ctdb</refentrytitle>
 706         <manvolnum>7</manvolnum></citerefentry>.
 707       </para>
 708
 709       <variablelist>
 710         <varlistentry>
 711           <term>CTDB_PER_IP_ROUTING_CONF=<parameter>FILENAME</parameter></term>
 712           <listitem>
 713             <para>
 714               FILENAME contains elements for constructing the desired
 715               routes for each source address.
 716             </para>
 717
 718             <para>
 719               The special FILENAME value
 720               <constant>__auto_link_local__</constant> indicates that no
 721               configuration file is provided and that CTDB should
 722               generate reasonable link-local routes for each public IP
 723               address.
 724             </para>
 725
 726             <para>
 727               File format:
 728               <screen>
 729 <parameter>IPADDR</parameter> <parameter>DEST-IPADDR/MASK</parameter> <optional><parameter>GATEWAY-IPADDR</parameter></optional>
 730               </screen>
 731             </para>
 732
 733             <para>
 734               No default, usually
 735               <filename>/usr/local/etc/ctdb/policy_routing</filename> when enabled.
 736             </para>
 737           </listitem>
 738         </varlistentry>
 739
 740         <varlistentry>
 741           <term>CTDB_PER_IP_ROUTING_RULE_PREF=<parameter>NUM</parameter></term>
 742         <listitem>
 743           <para>
 744             NUM sets the priority (or preference) for the routing
 745             rules that are added by CTDB.
 746           </para>
 747
 748           <para>
 749             This should be (strictly) greater than 0 and (strictly)
 750             less than 32766.  A priority of 100 is recommended, unless
 751             this conflicts with a priority already in use on the
 752             system.  See
 753             <citerefentry><refentrytitle>ip</refentrytitle>
 754             <manvolnum>8</manvolnum></citerefentry>, for more details.
 755           </para>
 756         </listitem>
 757         </varlistentry>
 758
 759         <varlistentry>
 760           <term>
 761             CTDB_PER_IP_ROUTING_TABLE_ID_LOW=<parameter>LOW-NUM</parameter>,
 762             CTDB_PER_IP_ROUTING_TABLE_ID_HIGH=<parameter>HIGH-NUM</parameter>
 763           </term>
 764           <listitem>
 765             <para>
 766               CTDB determines a unique routing table number to use for
 767               the routing related to each public address.  LOW-NUM and
 768               HIGH-NUM indicate the minimum and maximum routing table
 769               numbers that are used.
 770             </para>
 771
 772             <para>
 773               <citerefentry><refentrytitle>ip</refentrytitle>
 774               <manvolnum>8</manvolnum></citerefentry> uses some
 775               reserved routing table numbers below 255.  Therefore,
 776               CTDB_PER_IP_ROUTING_TABLE_ID_LOW should be (strictly)
 777               greater than 255.
 778             </para>
 779
 780             <para>
 781               CTDB uses the standard file
 782               <filename>/etc/iproute2/rt_tables</filename> to maintain
 783               a mapping between the routing table numbers and labels.
 784               The label for a public address
 785               <replaceable>ADDR</replaceable> will look like
 786               ctdb.<replaceable>addr</replaceable>.  This means that
 787               the associated rules and routes are easy to read (and
 788               manipulate).
 789             </para>
 790
 791             <para>
 792               No default, usually 1000 and 9000.
 793             </para>
 794           </listitem>
 795         </varlistentry>
 796       </variablelist>
 797
 798       <refsect3>
 799         <title>Example</title>
 800         <screen>
 801 CTDB_PER_IP_ROUTING_CONF=/usr/local/etc/ctdb/policy_routing
 802 CTDB_PER_IP_ROUTING_RULE_PREF=100
 803 CTDB_PER_IP_ROUTING_TABLE_ID_LOW=1000
 804 CTDB_PER_IP_ROUTING_TABLE_ID_HIGH=9000
 805         </screen>
 806       </refsect3>
 807
 808     </refsect2>
 809
 810     <refsect2>
 811       <title>LVS</title>
 812
 813       <para>
 814         For a general description see the <citetitle>LVS</citetitle>
 815         section in <citerefentry><refentrytitle>ctdb</refentrytitle>
 816         <manvolnum>7</manvolnum></citerefentry>.
 817       </para>
 818
 819       <refsect3>
 820         <title>Eventscript</title>
 821
 822         <simplelist>
 823           <member><filename>91.lvs</filename></member>
 824         </simplelist>
 825       </refsect3>
 826
 827       <variablelist>
 828
 829         <varlistentry>
 830           <term>CTDB_LVS_NODES=<parameter>FILENAME</parameter></term>
 831           <listitem>
 832             <para>
 833               FILENAME contains the list of nodes that belong to the
 834               same LVS group.
 835             </para>
 836             <para>
 837               File format:
 838               <screen>
 839 <parameter>IPADDR</parameter> <optional>slave-only</optional>
 840               </screen>
 841             </para>
 842             <para>
 843               IPADDR is the private IP address of each node in the LVS
 844               group.
 845             </para>
 846             <para>
 847               If "slave-only" is specified then the corresponding node
 848               can not be the LVS master node.  In this case
 849               <varname>CTDB_LVS_PUBLIC_IFACE</varname> and
 850               <varname>CTDB_LVS_PUBLIC_IP</varname> are optional and
 851               unused.
 852             </para>
 853             <para>
 854               No default, usually
 855               <filename>/usr/local/etc/ctdb/lvs_nodes</filename> when enabled.
 856             </para>
 857           </listitem>
 858         </varlistentry>
 859
 860         <varlistentry>
 861           <term>CTDB_LVS_PUBLIC_IFACE=<parameter>INTERFACE</parameter></term>
 862           <listitem>
 863             <para>
 864               INTERFACE is the network interface that clients will use
 865               to connection to <varname>CTDB_LVS_PUBLIC_IP</varname>.
 866               This is optional for slave-only nodes.
 867               No default.
 868             </para>
 869           </listitem>
 870         </varlistentry>
 871
 872         <varlistentry>
 873           <term>CTDB_LVS_PUBLIC_IP=<parameter>IPADDR</parameter></term>
 874           <listitem>
 875             <para>
 876               CTDB_LVS_PUBLIC_IP is the LVS public address.  No
 877               default.
 878           </para>
 879           </listitem>
 880         </varlistentry>
 881
 882       </variablelist>
 883     </refsect2>
 884
 885     <refsect2>
 886       <title>MISCELLANEOUS NETWORK CONFIGURATION</title>
 887
 888       <variablelist>
 889
 890         <varlistentry>
 891           <term>CTDB_PARTIALLY_ONLINE_INTERFACES=yes|no</term>
 892           <listitem>
 893             <para>
 894               Whether one or more offline interfaces should cause a
 895               monitor event to fail if there are other interfaces that
 896               are up.  If this is "yes" and a node has some interfaces
 897               that are down then <command>ctdb status</command> will
 898               display the node as "PARTIALLYONLINE".
 899             </para>
 900
 901             <para>
 902               Note that CTDB_PARTIALLY_ONLINE_INTERFACES=yes is
 903               incompatible with NAT gateway, since NAT gateway relies
 904               on the interface configured by CTDB_NATGW_PUBLIC_IFACE
 905               to be up.
 906             </para>
 907
 908             <para>
 909               Default is "no".
 910             </para>
 911           </listitem>
 912         </varlistentry>
 913
 914       </variablelist>
 915     </refsect2>
 916
 917   </refsect1>
 918
 919   <refsect1>
 920     <title>SERVICE CONFIGURATION</title>
 921
 922     <para>
 923       CTDB can be configured to manage and/or monitor various NAS (and
 924       other) services via its eventscripts.
 925     </para>
 926
 927     <para>
 928       In the simplest case CTDB will manage a service.  This means the
 929       service will be started and stopped along with CTDB, CTDB will
 930       monitor the service and CTDB will do any required
 931       reconfiguration of the service when public IP addresses are
 932       failed over.
 933     </para>
 934
 935     <refsect2>
 936       <title>SAMBA</title>
 937
 938       <refsect3>
 939         <title>Eventscripts</title>
 940
 941         <simplelist>
 942           <member><filename>49.winbind</filename></member>
 943           <member><filename>50.samba</filename></member>
 944         </simplelist>
 945       </refsect3>
 946
 947       <variablelist>
 948
 949         <varlistentry>
 950           <term>CTDB_MANAGES_SAMBA=yes|no</term>
 951           <listitem>
 952             <para>
 953               Should CTDB manage Samba?
 954             </para>
 955             <para>
 956               Default is no.
 957             </para>
 958           </listitem>
 959         </varlistentry>
 960
 961         <varlistentry>
 962           <term>CTDB_MANAGES_WINBIND=yes|no</term>
 963           <listitem>
 964             <para>
 965               Should CTDB manage Winbind?
 966             </para>
 967             <para>
 968               Default is no.
 969             </para>
 970           </listitem>
 971         </varlistentry>
 972
 973         <varlistentry>
 974           <term>CTDB_SAMBA_CHECK_PORTS=<parameter>PORT-LIST</parameter></term>
 975           <listitem>
 976             <para>
 977               When monitoring Samba, check TCP ports in
 978               space-separated PORT-LIST.
 979             </para>
 980             <para>
 981               Default is to monitor ports that Samba is configured to listen on.
 982             </para>
 983           </listitem>
 984         </varlistentry>
 985
 986         <varlistentry>
 987           <term>CTDB_SAMBA_SKIP_SHARE_CHECK=yes|no</term>
 988           <listitem>
 989             <para>
 990               As part of monitoring, should CTDB skip the check for
 991               the existence of each directory configured as share in
 992               Samba.  This may be desirable if there is a large number
 993               of shares.
 994             </para>
 995             <para>
 996               Default is no.
 997             </para>
 998           </listitem>
 999         </varlistentry>
1000
1001         <varlistentry>
1002           <term>CTDB_SERVICE_NMB=<parameter>SERVICE</parameter></term>
1003           <listitem>
1004             <para>
1005               Distribution specific SERVICE for managing nmbd.
1006             </para>
1007             <para>
1008               Default is distribution-dependant.
1009             </para>
1010           </listitem>
1011         </varlistentry>
1012         <varlistentry>
1013           <term>CTDB_SERVICE_SMB=<parameter>SERVICE</parameter></term>
1014           <listitem>
1015             <para>
1016               Distribution specific SERVICE for managing smbd.
1017             </para>
1018             <para>
1019               Default is distribution-dependant.
1020             </para>
1021           </listitem>
1022         </varlistentry>
1023
1024         <varlistentry>
1025           <term>CTDB_SERVICE_WINBIND=<parameter>SERVICE</parameter></term>
1026           <listitem>
1027             <para>
1028               Distribution specific SERVICE for managing winbindd.
1029             </para>
1030             <para>
1031               Default is "winbind".
1032             </para>
1033           </listitem>
1034         </varlistentry>
1035
1036       </variablelist>
1037
1038     </refsect2>
1039
1040     <refsect2>
1041       <title>NFS</title>
1042
1043       <para>
1044         This includes parameters for the kernel NFS server.
1045         Alternative NFS subsystems (such as <ulink
1046         url="https://github.com/nfs-ganesha/nfs-ganesha/wiki">NFS-Ganesha</ulink>)
1047         can be integrated using <varname>CTDB_NFS_CALLOUT</varname>.
1048       </para>
1049
1050       <refsect3>
1051         <title>Eventscript</title>
1052
1053         <simplelist>
1054           <member><filename>60.nfs</filename></member>
1055         </simplelist>
1056       </refsect3>
1057
1058       <variablelist>
1059
1060         <varlistentry>
1061           <term>CTDB_CLUSTER_FILESYSTEM_TYPE=gpfs</term>
1062           <listitem>
1063             <para>
1064               The type of cluster filesystem to use with NFS-ganesha.
1065               Currently only "gpfs" is supported.
1066             </para>
1067             <para>
1068               Default is "gpfs".
1069             </para>
1070           </listitem>
1071         </varlistentry>
1072
1073         <varlistentry>
1074           <term>CTDB_MANAGES_NFS=yes|no</term>
1075           <listitem>
1076             <para>
1077               Should CTDB manage NFS?
1078             </para>
1079             <para>
1080               Default is no.
1081             </para>
1082           </listitem>
1083         </varlistentry>
1084
1085         <varlistentry>
1086           <term>CTDB_NFS_CALLOUT=<parameter>COMMAND</parameter></term>
1087           <listitem>
1088             <para>
1089               COMMAND specifies the path to a callout to handle
1090               interactions with the configured NFS system, including
1091               startup, shutdown, monitoring.
1092             </para>
1093             <para>
1094               Default is the included
1095               <command>nfs-linux-kernel-callout</command>.
1096             </para>
1097           </listitem>
1098         </varlistentry>
1099
1100         <varlistentry>
1101           <term>CTDB_NFS_SKIP_SHARE_CHECK=yes|no</term>
1102           <listitem>
1103             <para>
1104               As part of monitoring, should CTDB skip the check for
1105               the existence of each directory exported via NFS.  This
1106               may be desirable if there is a large number of exports.
1107             </para>
1108             <para>
1109               Default is no.
1110             </para>
1111           </listitem>
1112         </varlistentry>
1113
1114         <varlistentry>
1115           <term>CTDB_RPCINFO_LOCALHOST=<parameter>IPADDR</parameter>|<parameter>HOSTNAME</parameter></term>
1116           <listitem>
1117             <para>
1118               IPADDR or HOSTNAME indicates the address that
1119               <command>rpcinfo</command> should connect to when doing
1120               <command>rpcinfo</command> check on IPv4 RPC service during
1121               monitoring.  Optimally this would be "localhost".
1122               However, this can add some performance overheads.
1123             </para>
1124             <para>
1125               Default is "127.0.0.1".
1126             </para>
1127           </listitem>
1128         </varlistentry>
1129
1130         <varlistentry>
1131           <term>CTDB_RPCINFO_LOCALHOST6=<parameter>IPADDR</parameter>|<parameter>HOSTNAME</parameter></term>
1132           <listitem>
1133             <para>
1134               IPADDR or HOSTNAME indicates the address that
1135               <command>rpcinfo</command> should connect to when doing
1136               <command>rpcinfo</command> check on IPv6 RPC service
1137               during monitoring.  Optimally this would be "localhost6"
1138               (or similar).  However, this can add some performance
1139               overheads.
1140             </para>
1141             <para>
1142               Default is "::1".
1143             </para>
1144           </listitem>
1145         </varlistentry>
1146
1147       </variablelist>
1148
1149     </refsect2>
1150
1151     <refsect2>
1152       <title>APACHE HTTPD</title>
1153
1154       <para>
1155         CTDB can manage the Apache web server.
1156       </para>
1157
1158       <refsect3>
1159         <title>Eventscript</title>
1160
1161         <simplelist>
1162           <member><filename>41.httpd</filename></member>
1163         </simplelist>
1164       </refsect3>
1165
1166       <variablelist>
1167         <varlistentry>
1168           <term>CTDB_MANAGES_HTTPD=yes|no</term>
1169           <listitem>
1170             <para>
1171               Should CTDB manage the Apache web server?
1172             </para>
1173             <para>
1174               Default is no.
1175             </para>
1176           </listitem>
1177         </varlistentry>
1178       </variablelist>
1179     </refsect2>
1180
1181     <refsect2>
1182       <title>CLAMAV</title>
1183
1184       <para>
1185         CTDB has support to manage the popular anti-virus daemon
1186         ClamAV.
1187       </para>
1188
1189       <refsect3>
1190         <title>Eventscript</title>
1191
1192         <simplelist>
1193           <member><filename>31.clamd</filename></member>
1194         </simplelist>
1195
1196         <para>
1197           This eventscript is not enabled by default.  Use
1198           <command>ctdb enablescript</command> to enable it.
1199         </para>
1200
1201       </refsect3>
1202
1203       <variablelist>
1204
1205         <varlistentry>
1206           <term>CTDB_MANAGES_CLAMD=yes|no</term>
1207           <listitem>
1208             <para>
1209               Should CTDB manage ClamAV?
1210             </para>
1211             <para>
1212               Default is no.
1213             </para>
1214           </listitem>
1215         </varlistentry>
1216
1217         <varlistentry>
1218           <term>CTDB_CLAMD_SOCKET=<parameter>FILENAME</parameter></term>
1219           <listitem>
1220             <para>
1221               FILENAME is the socket to monitor ClamAV.
1222             </para>
1223             <para>
1224               No default.
1225             </para>
1226           </listitem>
1227         </varlistentry>
1228
1229       </variablelist>
1230
1231     </refsect2>
1232
1233     <refsect2>
1234       <title>ISCSI</title>
1235
1236       <para>
1237         CTDB has support for managing the Linux iSCSI tgtd service.
1238       </para>
1239
1240       <refsect3>
1241         <title>Eventscript</title>
1242
1243         <simplelist>
1244           <member><filename>70.iscsi</filename></member>
1245         </simplelist>
1246       </refsect3>
1247
1248       <variablelist>
1249
1250         <varlistentry>
1251           <term>CTDB_MANAGES_ISCSI=yes|no</term>
1252           <listitem>
1253             <para>
1254               Should CTDB manage iSCSI tgtd?
1255             </para>
1256             <para>
1257               Default is no.
1258             </para>
1259           </listitem>
1260         </varlistentry>
1261
1262         <varlistentry>
1263           <term>CTDB_START_ISCSI_SCRIPTS=<parameter>DIRECTORY</parameter></term>
1264           <listitem>
1265             <para>
1266               DIRECTORY on shared storage containing scripts to start
1267               tgtd for each public IP address.
1268             </para>
1269             <para>
1270               No default.
1271             </para>
1272           </listitem>
1273         </varlistentry>
1274       </variablelist>
1275     </refsect2>
1276
1277     <refsect2>
1278       <title>MULTIPATHD</title>
1279
1280       <para>
1281         CTDB can monitor multipath devices to ensure that active paths
1282         are available.
1283       </para>
1284
1285       <refsect3>
1286         <title>Eventscript</title>
1287
1288         <simplelist>
1289           <member><filename>20.multipathd</filename></member>
1290         </simplelist>
1291
1292         <para>
1293           This eventscript is not enabled by default.  Use
1294           <command>ctdb enablescript</command> to enable it.
1295         </para>
1296       </refsect3>
1297
1298       <variablelist>
1299         <varlistentry>
1300           <term>CTDB_MONITOR_MPDEVICES=<parameter>MP-DEVICE-LIST</parameter></term>
1301           <listitem>
1302             <para>
1303               MP-DEVICE-LIST is a list of multipath devices for CTDB to monitor?
1304             </para>
1305             <para>
1306               No default.
1307             </para>
1308           </listitem>
1309         </varlistentry>
1310       </variablelist>
1311     </refsect2>
1312
1313     <refsect2>
1314       <title>VSFTPD</title>
1315
1316       <para>
1317         CTDB can manage the vsftpd FTP server.
1318       </para>
1319
1320       <refsect3>
1321         <title>Eventscript</title>
1322
1323         <simplelist>
1324           <member><filename>40.vsftpd</filename></member>
1325         </simplelist>
1326       </refsect3>
1327
1328       <variablelist>
1329         <varlistentry>
1330           <term>CTDB_MANAGES_VSFTPD=yes|no</term>
1331           <listitem>
1332             <para>
1333               Should CTDB manage the vsftpd FTP server?
1334             </para>
1335             <para>
1336               Default is no.
1337             </para>
1338           </listitem>
1339         </varlistentry>
1340       </variablelist>
1341     </refsect2>
1342
1343     <refsect2>
1344       <title>
1345         SYSTEM RESOURCE MONITORING CONFIGURATION
1346       </title>
1347
1348       <para>
1349         CTDB can experience seemingly random (performance and other)
1350         issues if system resources become too constrained.  Options in
1351         this section can be enabled to allow certain system resources
1352         to be checked.  They allows warnings to be logged and nodes to
1353         be marked unhealthy when system resource usage reaches the
1354         configured thresholds.
1355       </para>
1356
1357       <para>
1358         Some checks are enabled by default.  It is recommended that
1359         these checks remain enabled or are augmented by extra checks.
1360         There is no supported way of completely disabling the checks.
1361       </para>
1362
1363       <refsect3>
1364         <title>Eventscripts</title>
1365
1366         <simplelist>
1367           <member><filename>05.system</filename></member>
1368         </simplelist>
1369
1370         <para>
1371           Filesystem and memory usage monitoring is in
1372           <filename>05.system</filename>.
1373         </para>
1374       </refsect3>
1375
1376       <variablelist>
1377
1378         <varlistentry>
1379           <term>CTDB_MONITOR_FILESYSTEM_USAGE=<parameter>FS-LIMIT-LIST</parameter></term>
1380           <listitem>
1381             <para>
1382               FS-LIMIT-LIST is a space-separated list of
1383               <parameter>FILESYSTEM</parameter>:<parameter>WARN_LIMIT</parameter><optional>:<parameter>UNHEALTHY_LIMIT</parameter></optional>
1384               triples indicating that warnings should be logged if the
1385               space used on FILESYSTEM reaches WARN_LIMIT%.  If usage
1386               reaches UNHEALTHY_LIMIT then the node should be flagged
1387               unhealthy.  Either WARN_LIMIT or UNHEALTHY_LIMIT may be
1388               left blank, meaning that check will be omitted.
1389             </para>
1390
1391             <para>
1392               Default is to warn for each filesystem containing a
1393               database directory (<envar>CTDB_DBDIR</envar>,
1394               <envar>CTDB_DBDIR_PERSISTENT</envar>,
1395               <envar>CTDB_DBDIR_STATE</envar>) with a threshold of
1396               90%.
1397             </para>
1398           </listitem>
1399         </varlistentry>
1400
1401         <varlistentry>
1402           <term>CTDB_MONITOR_MEMORY_USAGE=<parameter>MEM-LIMITS</parameter></term>
1403           <listitem>
1404             <para>
1405               MEM-LIMITS takes the form
1406               <parameter>WARN_LIMIT</parameter><optional>:<parameter>UNHEALTHY_LIMIT</parameter></optional>
1407               indicating that warnings should be logged if memory
1408               usage reaches WARN_LIMIT%.  If usage reaches
1409               UNHEALTHY_LIMIT then the node should be flagged
1410               unhealthy.  Either WARN_LIMIT or UNHEALTHY_LIMIT may be
1411               left blank, meaning that check will be omitted.
1412             </para>
1413             <para>
1414               Default is 80, so warnings will be logged when memory
1415               usage reaches 80%.
1416             </para>
1417           </listitem>
1418         </varlistentry>
1419
1420         <varlistentry>
1421           <term>CTDB_MONITOR_SWAP_USAGE=<parameter>SWAP-LIMITS</parameter></term>
1422           <listitem>
1423             <para>
1424               SWAP-LIMITS takes the form
1425               <parameter>WARN_LIMIT</parameter><optional>:<parameter>UNHEALTHY_LIMIT</parameter></optional>
1426                indicating that warnings should be logged if
1427               swap usage reaches WARN_LIMIT%.  If usage reaches
1428               UNHEALTHY_LIMIT then the node should be flagged
1429               unhealthy.  Either WARN_LIMIT or UNHEALTHY_LIMIT may be
1430               left blank, meaning that check will be omitted.
1431             </para>
1432             <para>
1433               Default is 25, so warnings will be logged when swap
1434               usage reaches 25%.
1435             </para>
1436           </listitem>
1437         </varlistentry>
1438
1439       </variablelist>
1440     </refsect2>
1441
1442     <refsect2>
1443       <title>MISCELLANEOUS SERVICE-RELATED CONFIGURATION</title>
1444
1445       <variablelist>
1446
1447         <varlistentry>
1448           <term>CTDB_MANAGED_SERVICES=<parameter>SERVICE-LIST</parameter></term>
1449           <listitem>
1450             <para>
1451               SERVICE-LIST is a space-separated list of SERVICEs that
1452               CTDB should manage.  This can be used as an alternative
1453               to the
1454               <varname>CTDB_MANAGES_<replaceable>SERVICE</replaceable></varname>
1455               variables.
1456             </para>
1457             <para>
1458               No default.
1459             </para>
1460           </listitem>
1461         </varlistentry>
1462
1463         <varlistentry>
1464           <term>CTDB_SERVICE_AUTOSTARTSTOP=yes|no</term>
1465           <listitem>
1466             <para>
1467               When CTDB should start and stop services if they become
1468               managed or unmanaged.
1469             </para>
1470             <para>
1471               Default is no.
1472             </para>
1473           </listitem>
1474         </varlistentry>
1475
1476       </variablelist>
1477
1478     </refsect2>
1479
1480   </refsect1>
1481
1482   <refsect1>
1483     <title>
1484       TUNABLES CONFIGURATION
1485     </title>
1486
1487     <para>
1488       CTDB tunables (see
1489       <citerefentry><refentrytitle>ctdbd-tunables</refentrytitle>
1490       <manvolnum>7</manvolnum></citerefentry>) can be set from the
1491       configuration file.  They are set as follows:
1492
1493       <literallayout>
1494 CTDB_SET_<replaceable>TUNABLE</replaceable>=<replaceable>VALUE</replaceable>
1495       </literallayout>
1496     </para>
1497
1498     <para>
1499       For example:
1500
1501       <screen format="linespecific">
1502 CTDB_SET_MonitorInterval=20
1503       </screen>
1504     </para>
1505   </refsect1>
1506
1507   <refsect1>
1508     <title>
1509       DEBUG AND TEST
1510     </title>
1511
1512     <para>
1513       Variable in this section are for debugging and testing CTDB.
1514       They should not generally be needed.
1515     </para>
1516
1517     <variablelist>
1518
1519       <varlistentry>
1520         <term>CTDB_DEBUG_HUNG_SCRIPT=<parameter>FILENAME</parameter></term>
1521         <listitem>
1522           <para>
1523             FILENAME is a script to run to log debug information when
1524             an event script times out.
1525           </para>
1526           <para>
1527             Default is <filename><varname>CTDB_BASE</varname>/debug-hung-script.sh</filename>.
1528           </para>
1529         </listitem>
1530       </varlistentry>
1531
1532       <varlistentry>
1533         <term>CTDB_DEBUG_HUNG_SCRIPT_LOGFILE=<parameter>FILENAME</parameter></term>
1534         <listitem>
1535           <para>
1536             FILENAME specifies where log messages should go when
1537             debugging hung eventscripts.  This is a testing option.
1538             See also <citetitle>CTDB_DEBUG_HUNG_SCRIPT</citetitle>.
1539           </para>
1540           <para>
1541             No default.  Messages go to stdout/stderr and are logged
1542             to the same place as other CTDB log messages.
1543           </para>
1544         </listitem>
1545       </varlistentry>
1546
1547       <varlistentry>
1548         <term>CTDB_DEBUG_HUNG_SCRIPT_STACKPAT=<parameter>REGEXP</parameter></term>
1549         <listitem>
1550           <para>
1551             REGEXP specifies interesting processes for which stack
1552             traces should be logged when debugging hung eventscripts
1553             and those processes are matched in pstree output.  REGEXP
1554             is an extended regexp so choices are separated by pipes
1555             ('|').  However, REGEXP should not contain parentheses.
1556             See also <citetitle>CTDB_DEBUG_HUNG_SCRIPT</citetitle>.
1557           </para>
1558           <para>
1559             Default is "exportfs|rpcinfo".
1560           </para>
1561         </listitem>
1562       </varlistentry>
1563
1564       <varlistentry>
1565         <term>CTDB_DEBUG_LOCKS=<parameter>FILENAME</parameter></term>
1566         <listitem>
1567           <para>
1568             FILENAME is a script to run to log debug information when
1569             an CTDB fails to freeze databases during recovery.
1570           </para>
1571           <para>
1572             No default, usually
1573             <filename><varname>CTDB_BASE</varname>/debug_locks.sh</filename>.
1574           </para>
1575         </listitem>
1576       </varlistentry>
1577
1578       <varlistentry>
1579         <term>CTDB_SYS_ETCDIR=<parameter>DIRECTORY</parameter></term>
1580         <listitem>
1581           <para>
1582             DIRECTORY containing system configuration files.  This is
1583             used to provide alternate configuration when testing and
1584             should not need to be changed from the default.
1585           </para>
1586           <para>
1587             Default is <filename>/etc</filename>.
1588           </para>
1589         </listitem>
1590       </varlistentry>
1591
1592       <varlistentry>
1593         <term>CTDB_INIT_STYLE=debian|redhat|suse</term>
1594         <listitem>
1595           <para>
1596             This is the init style used by the Linux distribution (or
1597             other operating system) being used.  This is usually
1598             determined dynamically by checking the system.  This
1599             variable is used by the initscript to determine which init
1600             system primitives to use.  It is also used by some
1601             eventscripts to choose the name of initscripts for certain
1602             services, since these can vary between distributions.
1603           </para>
1604           <para>
1605             No fixed default.
1606           </para>
1607           <para>
1608             If this option needs to be changed from the calculated
1609             default for the initscript to function properly, then it
1610             must be set in the distribution-specific initscript
1611             configuration, such as
1612             <filename>/etc/sysconfig/ctdb</filename>
1613           </para>
1614         </listitem>
1615       </varlistentry>
1616
1617       <varlistentry>
1618         <term>CTDB_MAX_CORRUPT_DB_BACKUPS=<parameter>NUM</parameter></term>
1619         <listitem>
1620           <para>
1621             NUM is the maximum number of volatile TDB database backups
1622             to be kept (for each database) when a corrupt database is
1623             found during startup.  Volatile TDBs are zeroed during
1624             startup so backups are needed to debug any corruption that
1625             occurs before a restart.
1626           </para>
1627           <para>
1628             Default is 10.
1629           </para>
1630         </listitem>
1631       </varlistentry>
1632
1633       <varlistentry>
1634         <term>CTDB_MAX_OPEN_FILES=<parameter>NUM</parameter></term>
1635         <listitem>
1636           <para>
1637             NUM is the maximum number of open files.
1638           </para>
1639           <para>
1640             There is no default.
1641           </para>
1642         </listitem>
1643       </varlistentry>
1644
1645       <varlistentry>
1646         <term>CTDB_RC_LOCAL=<parameter>FILENAME</parameter></term>
1647         <listitem>
1648           <para>
1649             FILENAME is a script fragment to be sourced by the
1650             <filename>functions</filename> that is sourced by scripts.
1651             On example use would be to override function definitions
1652             in unit tests.  As a sanity check, this file must be
1653             executable for it to be used.
1654           </para>
1655           <para>
1656             No default.
1657           </para>
1658         </listitem>
1659       </varlistentry>
1660
1661       <varlistentry>
1662         <term>CTDB_RUN_TIMEOUT_MONITOR=yes|no</term>
1663         <listitem>
1664           <para>
1665             Whether CTDB should simulate timing out monitor events.
1666             This uses the <filename>99.timeout</filename> eventscript.
1667           </para>
1668           <para>
1669             Default is no.
1670           </para>
1671         </listitem>
1672       </varlistentry>
1673
1674       <varlistentry>
1675         <term>CTDB_SCRIPT_DEBUGLEVEL=<parameter>NUM</parameter></term>
1676         <listitem>
1677           <para>
1678             NUM is the level debugging messages printed by CTDB
1679             scripts.  Setting this to a higher number (e.g. 4) will
1680             cause some scripts to log more messages.
1681           </para>
1682           <para>
1683             Default is 2.
1684           </para>
1685         </listitem>
1686       </varlistentry>
1687
1688       <varlistentry>
1689         <term>CTDB_SUPPRESS_COREFILE=yes|no</term>
1690         <listitem>
1691           <para>
1692             Whether CTDB core files should be suppressed.
1693           </para>
1694           <para>
1695             Default is no.
1696           </para>
1697         </listitem>
1698       </varlistentry>
1699
1700       <varlistentry>
1701         <term>CTDB_VALGRIND=yes|no|<parameter>COMMAND</parameter></term>
1702         <listitem>
1703           <para>
1704             If "yes", this causes
1705             <citerefentry><refentrytitle>ctdbd</refentrytitle>
1706             <manvolnum>1</manvolnum></citerefentry> to be run under
1707             <citerefentry><refentrytitle>valgrind</refentrytitle>
1708             <manvolnum>1</manvolnum></citerefentry> with logs going to
1709             <filename>/usr/local/var/log/ctdb_valgrind</filename>.  If neither
1710             "yes" nor "no" then the value is assumed to be a COMMAND
1711             (e.g. a <command>valgrind</command> variation, a
1712             <citerefentry><refentrytitle>gdb</refentrytitle>
1713             <manvolnum>1</manvolnum></citerefentry> command) that is
1714             used in place of the default <command>valgrind</command>
1715             command.  In either case, the <option>--valgrind</option>
1716             option is passed to <command>ctdbd</command>.
1717           </para>
1718           <para>
1719             Default is no.
1720           </para>
1721         </listitem>
1722       </varlistentry>
1723
1724       <varlistentry>
1725         <term>CTDB_VARDIR=<parameter>DIRECTORY</parameter></term>
1726         <listitem>
1727           <para>
1728             DIRECTORY containing CTDB files that are modified at
1729             runtime.
1730           </para>
1731           <para>
1732             Defaults to <filename>/usr/local/var/lib/ctdb</filename>.
1733           </para>
1734         </listitem>
1735       </varlistentry>
1736
1737     </variablelist>
1738
1739   </refsect1>
1740
1741
1742   <refsect1>
1743     <title>FILES</title>
1744
1745     <simplelist>
1746       <member><filename>/usr/local/etc/ctdb/ctdbd.conf</filename></member>
1747       <member><filename>/etc/sysconfig/ctdb</filename></member>
1748       <member><filename>/etc/default/ctdb</filename></member>
1749       <member><filename>/usr/local/etc/ctdb/sysconfig/ctdb</filename></member>
1750     </simplelist>
1751   </refsect1>
1752
1753   <refsect1>
1754     <title>SEE ALSO</title>
1755     <para>
1756       <citerefentry><refentrytitle>ctdbd</refentrytitle>
1757       <manvolnum>1</manvolnum></citerefentry>,
1758
1759       <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
1760       <manvolnum>1</manvolnum></citerefentry>,
1761
1762       <citerefentry><refentrytitle>onnode</refentrytitle>
1763       <manvolnum>1</manvolnum></citerefentry>,
1764
1765       <citerefentry><refentrytitle>ctdb</refentrytitle>
1766       <manvolnum>7</manvolnum></citerefentry>,
1767
1768       <citerefentry><refentrytitle>ctdb-tunables</refentrytitle>
1769       <manvolnum>7</manvolnum></citerefentry>,
1770
1771       <ulink url="http://ctdb.samba.org/"/>
1772     </para>
1773   </refsect1>
1774
1775   <refentryinfo>
1776     <author>
1777       <contrib>
1778         This documentation was written by
1779         Amitay Isaacs,
1780         Martin Schwenke
1781       </contrib>
1782     </author>
1783
1784     <copyright>
1785       <year>2007</year>
1786       <holder>Andrew Tridgell</holder>
1787       <holder>Ronnie Sahlberg</holder>
1788     </copyright>
1789     <legalnotice>
1790       <para>
1791         This program is free software; you can redistribute it and/or
1792         modify it under the terms of the GNU General Public License as
1793         published by the Free Software Foundation; either version 3 of
1794         the License, or (at your option) any later version.
1795       </para>
1796       <para>
1797         This program is distributed in the hope that it will be
1798         useful, but WITHOUT ANY WARRANTY; without even the implied
1799         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1800         PURPOSE.  See the GNU General Public License for more details.
1801       </para>
1802       <para>
1803         You should have received a copy of the GNU General Public
1804         License along with this program; if not, see
1805         <ulink url="http://www.gnu.org/licenses"/>.
1806       </para>
1807     </legalnotice>
1808   </refentryinfo>
1809
1810 </refentry>