doc/ctdbd.1.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry
   3         PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <refentry id="ctdbd.1">
   6
   7 <refmeta>
   8         <refentrytitle>ctdbd</refentrytitle>
   9         <manvolnum>1</manvolnum>
  10         <refmiscinfo class="source">ctdb</refmiscinfo>
  11         <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
  12 </refmeta>
  13
  14
  15 <refnamediv>
  16         <refname>ctdbd</refname>
  17         <refpurpose>The CTDB cluster daemon</refpurpose>
  18 </refnamediv>
  19
  20 <refsynopsisdiv>
  21         <cmdsynopsis>
  22                 <command>ctdbd</command>
  23         </cmdsynopsis>
  24
  25         <cmdsynopsis>
  26                 <command>ctdbd</command>
  27                 <arg choice="opt">-? --help</arg>
  28                 <arg choice="opt">-d --debug=&lt;INTEGER&gt;</arg>
  29                 <arg choice="req">--dbdir=&lt;directory&gt;</arg>
  30                 <arg choice="req">--dbdir-persistent=&lt;directory&gt;</arg>
  31                 <arg choice="opt">--event-script-dir=&lt;directory&gt;</arg>
  32                 <arg choice="opt">-i --interactive</arg>
  33                 <arg choice="opt">--listen=&lt;address&gt;</arg>
  34                 <arg choice="opt">--logfile=&lt;filename&gt;</arg>
  35                 <arg choice="opt">--lvs</arg>
  36                 <arg choice="req">--nlist=&lt;filename&gt;</arg>
  37                 <arg choice="opt">--no-lmaster</arg>
  38                 <arg choice="opt">--no-recmaster</arg>
  39                 <arg choice="opt">--nosetsched</arg>
  40                 <arg choice="req">--notification-script=&lt;filename&gt;</arg>
  41                 <arg choice="opt">--public-addresses=&lt;filename&gt;</arg>
  42                 <arg choice="opt">--public-interface=&lt;interface&gt;</arg>
  43                 <arg choice="req">--reclock=&lt;filename&gt;</arg>
  44                 <arg choice="opt">--single-public-ip=&lt;address&gt;</arg>
  45                 <arg choice="opt">--socket=&lt;filename&gt;</arg>
  46                 <arg choice="opt">--start-as-disabled</arg>
  47                 <arg choice="opt">--start-as-stopped</arg>
  48                 <arg choice="opt">--syslog</arg>
  49                 <arg choice="opt">--log-ringbuf-size=&lt;num-entries&gt;</arg>
  50                 <arg choice="opt">--torture</arg>
  51                 <arg choice="opt">--transport=&lt;STRING&gt;</arg>
  52                 <arg choice="opt">--usage</arg>
  53         </cmdsynopsis>
  54
  55 </refsynopsisdiv>
  56
  57   <refsect1><title>DESCRIPTION</title>
  58     <para>
  59       ctdbd is the main ctdb daemon.
  60     </para>
  61     <para>
  62       ctdbd provides a clustered version of the TDB database with automatic rebuild/recovery of the databases upon nodefailures.
  63     </para>
  64     <para>
  65       Combined with a cluster filesystem ctdbd provides a full HA environment for services such as clustered Samba and NFS as well as other services.
  66     </para>
  67     <para>
  68       ctdbd provides monitoring of all nodes in the cluster and automatically reconfigures the cluster and recovers upon node failures.
  69     </para>
  70     <para>
  71       ctdbd is the main component in clustered Samba that provides a high-availability load-sharing CIFS server cluster.
  72     </para>
  73   </refsect1>
  74
  75
  76   <refsect1>
  77     <title>OPTIONS</title>
  78
  79     <variablelist>
  80       <varlistentry><term>-? --help</term>
  81         <listitem>
  82           <para>
  83             Print some help text to the screen.
  84           </para>
  85         </listitem>
  86       </varlistentry>
  87
  88       <varlistentry><term>-d --debug=&lt;DEBUGLEVEL&gt;</term>
  89         <listitem>
  90           <para>
  91             This option sets the debuglevel on the ctdbd daemon which controls what will be written to the logfile. The default is 0 which will only log important events and errors. A larger number will provide additional logging.
  92           </para>
  93         </listitem>
  94       </varlistentry>
  95
  96       <varlistentry><term>--dbdir=&lt;directory&gt;</term>
  97         <listitem>
  98           <para>
  99             This is the directory on local storage where ctdbd keeps the local
 100             copy of the TDB databases. This directory is local for each node and should not be stored on the shared cluster filesystem.
 101           </para>
 102           <para>
 103             This directory would usually be /var/ctdb .
 104           </para>
 105         </listitem>
 106       </varlistentry>
 107
 108       <varlistentry><term>--dbdir-persistent=&lt;directory&gt;</term>
 109         <listitem>
 110           <para>
 111             This is the directory on local storage where ctdbd keeps the local
 112             copy of the persistent TDB databases. This directory is local for each node and should not be stored on the shared cluster filesystem.
 113           </para>
 114           <para>
 115             This directory would usually be /etc/ctdb/persistent .
 116           </para>
 117         </listitem>
 118       </varlistentry>
 119
 120       <varlistentry><term>--event-script-dir=&lt;directory&gt;</term>
 121         <listitem>
 122           <para>
 123             This option is used to specify the directory where the CTDB event
 124             scripts are stored.
 125           </para>
 126           <para>
 127             This will normally be /etc/ctdb/events.d which is part of the ctdb distribution.
 128           </para>
 129         </listitem>
 130       </varlistentry>
 131
 132       <varlistentry><term>-i --interactive</term>
 133         <listitem>
 134           <para>
 135             By default ctdbd will detach itself from the shell and run in
 136             the background as a daemon. This option makes ctdbd to start in interactive mode.
 137           </para>
 138         </listitem>
 139       </varlistentry>
 140
 141       <varlistentry><term>--listen=&lt;address&gt;</term>
 142         <listitem>
 143           <para>
 144             This specifies which ip address ctdb will bind to. By default ctdbd will bind to the first address it finds in the /etc/ctdb/nodes file and which is also present on the local system in which case you do not need to provide this option.
 145           </para>
 146           <para>
 147             This option is only required when you want to run multiple ctdbd daemons/nodes on the same physical host in which case there would be multiple entries in /etc/ctdb/nodes what would match a local interface.
 148           </para>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry><term>--logfile=&lt;filename&gt;</term>
 153         <listitem>
 154           <para>
 155             This is the file where ctdbd will write its log. This is usually /var/log/log.ctdb .
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry><term>--lvs</term>
 161         <listitem>
 162           <para>
 163           This option is used to activate the LVS capability on a CTDB node.
 164           Please see the LVS section.
 165           </para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry><term>--nlist=&lt;filename&gt;</term>
 170         <listitem>
 171           <para>
 172             This file contains a list of the private ip addresses of every node in the cluster. There is one line/ip address for each node. This file must be the same for all nodes in the cluster.
 173           </para>
 174           <para>
 175             This file is usually /etc/ctdb/nodes .
 176           </para>
 177         </listitem>
 178       </varlistentry>
 179
 180       <varlistentry><term>--no-lmaster</term>
 181         <listitem>
 182           <para>
 183           This argument specifies that this node can NOT become an lmaster
 184           for records in the database. This means that it will never show up
 185           in the vnnmap. This feature is primarily used for making a cluster
 186         span across a WAN link and use CTDB as a WAN-accelerator.
 187           </para>
 188           <para>
 189           Please see the "remote cluster nodes" section for more information.
 190           </para>
 191         </listitem>
 192       </varlistentry>
 193
 194       <varlistentry><term>--no-recmaster</term>
 195         <listitem>
 196           <para>
 197           This argument specifies that this node can NOT become a recmaster
 198           for the database. This feature is primarily used for making a cluster
 199         span across a WAN link and use CTDB as a WAN-accelerator.
 200           </para>
 201           <para>
 202           Please see the "remote cluster nodes" section for more information.
 203           </para>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry><term>--nosetsched</term>
 208         <listitem>
 209           <para>
 210             This is a ctdbd debugging option. this option is only used when
 211             debugging ctdbd.
 212           </para>
 213           <para>
 214             Normally ctdb will change its scheduler to run as a real-time
 215             process. This is the default mode for a normal ctdbd operation
 216             to gurarantee that ctdbd always gets the cpu cycles that it needs.
 217           </para>
 218           <para>
 219             This option is used to tell ctdbd to NOT run as a real-time process
 220             and instead run ctdbd as a normal userspace process.
 221             This is useful for debugging and when you want to run ctdbd under
 222             valgrind or gdb. (You don't want to attach valgrind or gdb to a
 223             real-time process.)
 224           </para>
 225         </listitem>
 226       </varlistentry>
 227
 228       <varlistentry><term>--notification-script=&lt;filename&gt;</term>
 229         <listitem>
 230           <para>
 231             This specifies a script which will be invoked by ctdb when certain
 232             state changes occur in ctdbd and when you may want to trigger this
 233             to run certain scripts.
 234           </para>
 235           <para>
 236             This file is usually /etc/ctdb/notify.sh .
 237           </para>
 238           <para>
 239             See the NOTIFICATION SCRIPT section below for more information.
 240           </para>
 241         </listitem>
 242       </varlistentry>
 243
 244       <varlistentry><term>--public_addresses=&lt;filename&gt;</term>
 245         <listitem>
 246           <para>
 247             When used with IP takeover this specifies a file containing the public ip addresses to use on the cluster. This file contains a list of ip addresses netmasks and interfaces. When ctdb is operational it will distribute these public ip addresses evenly across the available nodes.
 248           </para>
 249           <para>
 250             This is usually the file /etc/ctdb/public_addresses
 251           </para>
 252         </listitem>
 253       </varlistentry>
 254
 255       <varlistentry><term>--public-interface=&lt;interface&gt;</term>
 256         <listitem>
 257           <para>
 258             This option tells ctdb which interface to attach public-addresses
 259             to and also where to attach the single-public-ip when used.
 260             </para>
 261             <para>
 262             This is only required when using public ip addresses and only when
 263             you don't specify the interface explicitly in /etc/ctdb/public_addresses or when you are using --single-public-ip.
 264           </para>
 265           <para>
 266           If you omit this argument when using public addresses or single public ip, ctdb will not be able to send out Gratious ARPs correctly or be able to kill tcp connections correctly which will lead to application failures.
 267           </para>
 268         </listitem>
 269       </varlistentry>
 270
 271       <varlistentry><term>--reclock=&lt;filename&gt;</term>
 272         <listitem>
 273           <para>
 274             This is the name of the lock file stored of the shared cluster filesystem that ctdbd uses to prevent split brains from occuring.
 275             This file must be stored on shared storage.
 276           </para>
 277           <para>
 278             It is possible to run CTDB without a reclock file, but then there
 279             will be no protection against split brain if the network becomes
 280             partitioned. Using CTDB without a reclock file is strongly
 281             discouraged.
 282           </para>
 283         </listitem>
 284       </varlistentry>
 285
 286       <varlistentry><term>--socket=&lt;filename&gt;</term>
 287         <listitem>
 288           <para>
 289             This specifies the name of the domain socket that ctdbd will create. This socket is used for local clients to attach to and communicate with the ctdbd daemon.
 290           </para>
 291           <para>
 292             The default is /tmp/ctdb.socket . You only need to use this option if you plan to run multiple ctdbd daemons on the same physical host.
 293           </para>
 294         </listitem>
 295       </varlistentry>
 296
 297       <varlistentry><term>--start-as-disabled</term>
 298         <listitem>
 299           <para>
 300           This makes the ctdb daemon to be DISABLED when it starts up.
 301           </para>
 302           <para>
 303           As it is DISABLED it will not get any of the public ip addresses
 304           allocated to it, and thus this allow you to start ctdb on a node
 305           without causing any ip address to failover from other nodes onto
 306           the new node.
 307           </para>
 308           <para>
 309           When used, the administrator must keep track of when nodes start and
 310           manually enable them again using the "ctdb enable" command, or else
 311           the node will not host any services.
 312           </para>
 313           <para>
 314           A node that is DISABLED will not host any services and will not be
 315           reachable/used by any clients.
 316           </para>
 317         </listitem>
 318       </varlistentry>
 319
 320       <varlistentry><term>--start-as-stopped</term>
 321         <listitem>
 322           <para>
 323           This makes the ctdb daemon to be STOPPED when it starts up.
 324           </para>
 325           <para>
 326           A node that is STOPPED does not host any public addresses. It is not part of the VNNMAP so it does act as an LMASTER. It also has all databases locked in recovery mode until restarted.
 327           </para>
 328           <para>
 329           To restart and activate a STOPPED node, the command "ctdb continue" is used.
 330           </para>
 331           <para>
 332           A node that is STOPPED will not host any services and will not be
 333           reachable/used by any clients.
 334           </para>
 335         </listitem>
 336       </varlistentry>
 337
 338       <varlistentry><term>--syslog</term>
 339         <listitem>
 340           <para>
 341             Send all log messages to syslog instead of to the ctdb logfile.
 342           </para>
 343         </listitem>
 344       </varlistentry>
 345
 346       <varlistentry><term>--log-ringbuf-size=&lt;num-entries&gt;</term>
 347         <listitem>
 348           <para>
 349             In addition to the normal loggign to a log file,
 350             CTDBD also keeps a in-memory ringbuffer containing the most recent
 351             log entries for all log levels (except DEBUG).
 352           </para>
 353           <para>
 354             This is useful since it allows for keeping continuous logs to a file
 355             at a reasonable non-verbose level, but shortly after an incident has
 356             occured, a much more detailed log can be pulled from memory. This
 357             can allow you to avoid having to reproduce an issue due to the
 358             on-disk logs being of insufficient detail.
 359           </para>
 360           <para>
 361             This in-memory ringbuffer contains a fixed number of the most recent
 362             entries. This is settable at startup either through the
 363             --log-ringbuf-size argument, or preferably by using
 364             CTDB_LOG_RINGBUF_SIZE in the sysconfig file.
 365           </para>
 366           <para>
 367             Use the "ctdb getlog" command to access this log.
 368           </para>
 369         </listitem>
 370       </varlistentry>
 371
 372
 373       <varlistentry><term>--torture</term>
 374         <listitem>
 375           <para>
 376             This option is only used for development and testing of ctdbd. It adds artificial errors and failures to the common codepaths in ctdbd to verify that ctdbd can recover correctly for failures.
 377           </para>
 378           <para>
 379             You do NOT want to use this option unless you are developing and testing new functionality in ctdbd.
 380           </para>
 381         </listitem>
 382       </varlistentry>
 383
 384       <varlistentry><term>--transport=&lt;STRING&gt;</term>
 385         <listitem>
 386           <para>
 387             This option specifies which transport to use for ctdbd internode communications. The default is "tcp".
 388           </para>
 389           <para>
 390             Currently only "tcp" is supported but "infiniband" might be
 391             implemented in the future.
 392           </para>
 393         </listitem>
 394       </varlistentry>
 395
 396       <varlistentry><term>--usage</term>
 397         <listitem>
 398           <para>
 399             Print useage information to the screen.
 400           </para>
 401         </listitem>
 402       </varlistentry>
 403
 404     </variablelist>
 405   </refsect1>
 406
 407
 408   <refsect1><title>Private vs Public addresses</title>
 409     <para>
 410       When used for ip takeover in a HA environment, each node in a ctdb
 411       cluster has multiple ip addresses assigned to it. One private and one or more public.
 412     </para>
 413
 414     <refsect2><title>Private address</title>
 415       <para>
 416         This is the physical ip address of the node which is configured in
 417         linux and attached to a physical interface. This address uniquely
 418         identifies a physical node in the cluster and is the ip addresses
 419         that ctdbd will use to communicate with the ctdbd daemons on the
 420         other nodes in the cluster.
 421       </para>
 422       <para>
 423         The private addresses are configured in /etc/ctdb/nodes
 424         (unless the --nlist option is used) and contain one line for each
 425         node in the cluster. Each line contains the private ip address for one
 426         node in the cluster. This file must be the same on all nodes in the
 427         cluster.
 428       </para>
 429       <para>
 430         Since the private addresses are only available to the network when the
 431         corresponding node is up and running you should not use these addresses
 432         for clients to connect to services provided by the cluster. Instead
 433         client applications should only attach to the public addresses since
 434         these are guaranteed to always be available.
 435       </para>
 436       <para>
 437         When using ip takeover, it is strongly recommended that the private
 438         addresses are configured on a private network physically separated
 439         from the rest of the network and that this private network is dedicated
 440         to CTDB traffic.
 441       </para>
 442       Example /etc/ctdb/nodes for a four node cluster:
 443       <screen format="linespecific">
 444         10.1.1.1
 445         10.1.1.2
 446         10.1.1.3
 447         10.1.1.4
 448       </screen>
 449     </refsect2>
 450     <refsect2><title>Public address</title>
 451       <para>
 452         A public address on the other hand is not attached to an interface.
 453         This address is managed by ctdbd itself and is attached/detached to
 454         a physical node at runtime.
 455       </para>
 456       <para>
 457         The ctdb cluster will assign/reassign these public addresses across the
 458         available healthy nodes in the cluster. When one node fails, its public address
 459         will be migrated to and taken over by a different node in the cluster
 460         to ensure that all public addresses are always available to clients as
 461         long as there are still nodes available capable of hosting this address.
 462       </para>
 463       <para>
 464         These addresses are not physically attached to a specific node.
 465         The 'ctdb ip' command can be used to view the current assignment of
 466         public addresses and which physical node is currently serving it.
 467       </para>
 468       <para>
 469         On each node this file contains a list of the public addresses that
 470         this node is capable of hosting.
 471         The list also contain the netmask and the
 472         interface where this address should be attached for the case where you
 473         may want to serve data out through multiple different interfaces.
 474       </para>
 475       Example /etc/ctdb/public_addresses for a node that can host 4 public addresses:
 476       <screen format="linespecific">
 477         11.1.1.1/24 eth0
 478         11.1.1.2/24 eth0
 479         11.1.2.1/24 eth1
 480         11.1.2.2/24 eth1
 481       </screen>
 482
 483         <para>
 484         In most cases this file would be the same on all nodes in a cluster but
 485         there are exceptions when one may want to use different files
 486         on different nodes.
 487         </para>
 488         Example: 4 nodes partitioned into two subgroups :
 489         <screen format="linespecific">
 490         Node 0:/etc/ctdb/public_addresses
 491                 10.1.1.1/24 eth0
 492                 10.1.1.2/24 eth0
 493
 494         Node 1:/etc/ctdb/public_addresses
 495                 10.1.1.1/24 eth0
 496                 10.1.1.2/24 eth0
 497
 498         Node 2:/etc/ctdb/public_addresses
 499                 10.2.1.1/24 eth0
 500                 10.2.1.2/24 eth0
 501
 502         Node 3:/etc/ctdb/public_addresses
 503                 10.2.1.1/24 eth0
 504                 10.2.1.2/24 eth0
 505         </screen>
 506         <para>
 507         In this example nodes 0 and 1 host two public addresses on the
 508         10.1.1.x network  while nodes 2 and 3 host two public addresses for the
 509         10.2.1.x network.
 510         </para>
 511         <para>
 512         Ip address 10.1.1.1 can be hosted by either of nodes 0 or 1 and will be
 513         available to clients as long as at least one of these two nodes are
 514         available.
 515         If both nodes 0 and node 1 become unavailable 10.1.1.1 also becomes
 516         unavailable. 10.1.1.1 can not be failed over to node 2 or node 3 since
 517         these nodes do not have this ip address listed in their public
 518         addresses file.
 519         </para>
 520     </refsect2>
 521   </refsect1>
 522
 523
 524   <refsect1><title>Node status</title>
 525     <para>
 526       The current status of each node in the cluster can be viewed by the
 527       'ctdb status' command.
 528     </para>
 529     <para>
 530       There are five possible states for a node.
 531     </para>
 532
 533     <para>
 534       OK - This node is fully functional.
 535     </para>
 536
 537     <para>
 538       DISCONNECTED - This node could not be connected through the network
 539       and is currently not particpating in the cluster. If there is a
 540       public IP address associated with this node it should have been taken
 541       over by a different node. No services are running on this node.
 542     </para>
 543
 544     <para>
 545       DISABLED - This node has been administratively disabled. This node is
 546       still functional and participates in the CTDB cluster but its IP
 547       addresses have been taken over by a different node and no services are
 548       currently being hosted.
 549     </para>
 550
 551     <para>
 552       UNHEALTHY - A service provided by this node is malfunctioning and should
 553       be investigated. The CTDB daemon itself is operational and participates
 554       in the cluster. Its public IP address has been taken over by a different
 555       node and no services are currently being hosted. All unhealthy nodes
 556       should be investigated and require an administrative action to rectify.
 557     </para>
 558
 559     <para>
 560       BANNED - This node failed too many recovery attempts and has been banned
 561       from participating in the cluster for a period of RecoveryBanPeriod
 562       seconds. Any public IP address has been taken over by other nodes. This
 563       node does not provide any services. All banned nodes should be
 564       investigated and require an administrative action to rectify. This node
 565       does not perticipate in the CTDB cluster but can still be communicated
 566       with. I.e. ctdb commands can be sent to it.
 567     </para>
 568
 569     <para>
 570       STOPPED - A node that is stopped does not host any public ip addresses,
 571       nor is it part of the VNNMAP. A stopped node can not become LVSMASTER,
 572       RECMASTER or NATGW.
 573       This node does not perticipate in the CTDB cluster but can still be
 574       communicated with. I.e. ctdb commands can be sent to it.
 575     </para>
 576   </refsect1>
 577
 578   <refsect1>
 579     <title>PUBLIC TUNABLES</title>
 580     <para>
 581     These are the public tuneables that can be used to control how ctdb behaves.
 582     </para>
 583
 584     <refsect2><title>MaxRedirectCount</title>
 585     <para>Default: 3</para>
 586     <para>
 587     If we are not the DMASTER and need to fetch a record across the network
 588     we first send the request to the LMASTER after which the record
 589     is passed onto the current DMASTER. If the DMASTER changes before
 590     the request has reached that node, the request will be passed onto the
 591     "next" DMASTER. For very hot records that migrate rapidly across the
 592     cluster this can cause a request to "chase" the record for many hops
 593     before it catches up with the record.
 594
 595     this is how many hops we allow trying to chase the DMASTER before we
 596     switch back to the LMASTER again to ask for new directions.
 597     </para>
 598     <para>
 599     When chasing a record, this is how many hops we will chase the record
 600     for before going back to the LMASTER to ask for new guidance.
 601     </para>
 602     </refsect2>
 603
 604     <refsect2><title>SeqnumInterval</title>
 605     <para>Default: 1000</para>
 606     <para>
 607     Some databases have seqnum tracking enabled, so that samba will be able
 608     to detect asynchronously when there has been updates to the database.
 609     Everytime a database is updated its sequence number is increased.
 610     </para>
 611     <para>
 612     This tunable is used to specify in 'ms' how frequently ctdb will
 613     send out updates to remote nodes to inform them that the sequence
 614     number is increased.
 615     </para>
 616     </refsect2>
 617
 618     <refsect2><title>ControlTimeout</title>
 619     <para>Default: 60</para>
 620     <para>
 621     This is the default
 622     setting for timeout for when sending a control message to either the
 623     local or a remote ctdb daemon.
 624     </para>
 625     </refsect2>
 626
 627     <refsect2><title>TraverseTimeout</title>
 628     <para>Default: 20</para>
 629     <para>
 630     This setting controls how long we allow a traverse process to run.
 631     After this timeout triggers, the main ctdb daemon will abort the
 632     traverse if it has not yet finished.
 633     </para>
 634     </refsect2>
 635
 636     <refsect2><title>KeepaliveInterval</title>
 637     <para>Default: 5</para>
 638     <para>
 639     How often in seconds should the nodes send keepalives to eachother.
 640     </para>
 641     </refsect2>
 642
 643     <refsect2><title>KeepaliveLimit</title>
 644     <para>Default: 5</para>
 645     <para>
 646     After how many keepalive intervals without any traffic should a node
 647     wait until marking the peer as DISCONNECTED.
 648     </para>
 649     <para>
 650     If a node has hung, it can thus take KeepaliveInterval*(KeepaliveLimit+1)
 651     seconds before we determine that the node is DISCONNECTED and that we
 652     require a recovery. This limitshould not be set too high since we want
 653     a hung node to be detectec, and expunged from the cluster well before
 654     common CIFS timeouts (45-90 seconds) kick in.
 655     </para>
 656     </refsect2>
 657
 658     <refsect2><title>RecoverTimeout</title>
 659     <para>Default: 20</para>
 660     <para>
 661     This is the default setting for timeouts for controls when sent from the
 662     recovery daemon. We allow longer control timeouts from the recovery daemon
 663     than from normal use since the recovery dameon often use controls that
 664     can take a lot longer than normal controls.
 665     </para>
 666     </refsect2>
 667
 668     <refsect2><title>RecoverInterval</title>
 669     <para>Default: 1</para>
 670     <para>
 671     How frequently in seconds should the recovery daemon perform the
 672     consistency checks that determine if we need to perform a recovery or not.
 673     </para>
 674     </refsect2>
 675
 676     <refsect2><title>ElectionTimeout</title>
 677     <para>Default: 3</para>
 678     <para>
 679     When electing a new recovery master, this is how many seconds we allow
 680     the election to take before we either deem the election finished
 681     or we fail the election and start a new one.
 682     </para>
 683     </refsect2>
 684
 685     <refsect2><title>TakeoverTimeout</title>
 686     <para>Default: 9</para>
 687     <para>
 688     This is how many seconds we allow controls to take for IP failover events.
 689     </para>
 690     </refsect2>
 691
 692     <refsect2><title>MonitorInterval</title>
 693     <para>Default: 15</para>
 694     <para>
 695     How often should ctdb run the event scripts to check for a nodes health.
 696     </para>
 697     </refsect2>
 698
 699     <refsect2><title>TickleUpdateInterval</title>
 700     <para>Default: 20</para>
 701     <para>
 702     How often will ctdb record and store the "tickle" information used to
 703     kickstart stalled tcp connections after a recovery.
 704     </para>
 705     </refsect2>
 706
 707     <refsect2><title>EventScriptTimeout</title>
 708     <para>Default: 20</para>
 709     <para>
 710     How long should ctdb let an event script run before aborting it and
 711     marking the node unhealthy.
 712     </para>
 713     </refsect2>
 714
 715     <refsect2><title>EventScriptTimeoutCount</title>
 716     <para>Default: 1</para>
 717     <para>
 718     How many events in a row needs to timeout before we flag the node UNHEALTHY.
 719     This setting is useful if your scripts can not be written so that they
 720     do not hang for benign reasons.
 721     </para>
 722     </refsect2>
 723
 724     <refsect2><title>EventScriptUnhealthyOnTimeout</title>
 725     <para>Default: 0</para>
 726     <para>
 727     This setting can be be used to make ctdb never become UNHEALTHY if your
 728     eventscripts keep hanging/timing out.
 729     </para>
 730     </refsect2>
 731
 732     <refsect2><title>RecoveryGracePeriod</title>
 733     <para>Default: 120</para>
 734     <para>
 735     During recoveries, if a node has not caused recovery failures during the
 736     last grace period, any records of transgressions that the node has caused
 737     recovery failures will be forgiven. This resets the ban-counter back to
 738     zero for that node.
 739     </para>
 740     </refsect2>
 741
 742     <refsect2><title>RecoveryBanPeriod</title>
 743     <para>Default: 300</para>
 744     <para>
 745     If a node becomes banned causing repetitive recovery failures. The node will
 746     eventually become banned from the cluster.
 747     This controls how long the culprit node will be banned from the cluster
 748     before it is allowed to try to join the cluster again.
 749     Don't set to small. A node gets banned for a reason and it is usually due
 750     to real problems with the node.
 751     </para>
 752     </refsect2>
 753
 754     <refsect2><title>DatabaseHashSize</title>
 755     <para>Default: 100001</para>
 756     <para>
 757     Size of the hash chains for the local store of the tdbs that ctdb manages.
 758     </para>
 759     </refsect2>
 760
 761     <refsect2><title>DatabaseMaxDead</title>
 762     <para>Default: 5</para>
 763     <para>
 764     How many dead records per hashchain in the TDB database do we allow before
 765     the freelist needs to be processed.
 766     </para>
 767     </refsect2>
 768
 769     <refsect2><title>RerecoveryTimeout</title>
 770     <para>Default: 10</para>
 771     <para>
 772     Once a recovery has completed, no additional recoveries are permitted
 773     until this timeout has expired.
 774     </para>
 775     </refsect2>
 776
 777     <refsect2><title>EnableBans</title>
 778     <para>Default: 1</para>
 779     <para>
 780     When set to 0, this disables BANNING completely in the cluster and thus
 781     nodes can not get banned, even it they break. Don't set to 0 unless you
 782     know what you are doing.  You should set this to the same value on
 783     all nodes to avoid unexpected behaviour.
 784     </para>
 785     </refsect2>
 786
 787     <refsect2><title>DeterministicIPs</title>
 788     <para>Default: 0</para>
 789     <para>
 790     When enabled, this tunable makes ctdb try to keep public IP addresses
 791     locked to specific nodes as far as possible. This makes it easier for
 792     debugging since you can know that as long as all nodes are healthy
 793     public IP X will always be hosted by node Y.
 794     </para>
 795     <para>
 796     The cost of using deterministic IP address assignment is that it
 797     disables part of the logic where ctdb tries to reduce the number of
 798     public IP assignment changes in the cluster. This tunable may increase
 799     the number of IP failover/failbacks that are performed on the cluster
 800     by a small margin.
 801     </para>
 802
 803     </refsect2>
 804     <refsect2><title>LCP2PublicIPs</title>
 805     <para>Default: 1</para>
 806     <para>
 807     When enabled this switches ctdb to use the LCP2 ip allocation
 808     algorithm.
 809     </para>
 810     </refsect2>
 811
 812     <refsect2><title>ReclockPingPeriod</title>
 813     <para>Default: x</para>
 814     <para>
 815     Obsolete
 816     </para>
 817     </refsect2>
 818
 819     <refsect2><title>NoIPFailback</title>
 820     <para>Default: 0</para>
 821     <para>
 822     When set to 1, ctdb will not perform failback of IP addresses when a node
 823     becomes healthy. Ctdb WILL perform failover of public IP addresses when a
 824     node becomes UNHEALTHY, but when the node becomes HEALTHY again, ctdb
 825     will not fail the addresses back.
 826     </para>
 827     <para>
 828     Use with caution! Normally when a node becomes available to the cluster
 829     ctdb will try to reassign public IP addresses onto the new node as a way
 830     to distribute the workload evenly across the clusternode. Ctdb tries to
 831     make sure that all running nodes have approximately the same number of
 832     public addresses it hosts.
 833     </para>
 834     <para>
 835     When you enable this tunable, CTDB will no longer attempt to rebalance
 836     the cluster by failing IP addresses back to the new nodes. An unbalanced
 837     cluster will therefore remain unbalanced until there is manual
 838     intervention from the administrator. When this parameter is set, you can
 839     manually fail public IP addresses over to the new node(s) using the
 840     'ctdb moveip' command.
 841     </para>
 842     </refsect2>
 843
 844     <refsect2><title>DisableIPFailover</title>
 845     <para>Default: 0</para>
 846     <para>
 847     When enabled, ctdb will not perform failover or failback. Even if a
 848     node fails while holding public IPs, ctdb will not recover the IPs or
 849     assign them to another node.
 850     </para>
 851     <para>
 852     When you enable this tunable, CTDB will no longer attempt to recover
 853     the cluster by failing IP addresses over to other nodes. This leads to
 854     a service outage until the administrator has manually performed failover
 855     to replacement nodes using the 'ctdb moveip' command.
 856     </para>
 857     </refsect2>
 858
 859     <refsect2><title>NoIPTakeover</title>
 860     <para>Default: 0</para>
 861     <para>
 862     When set to 1, ctdb will not allow IP addresses to be failed over
 863     onto this node. Any IP addresses that the node currently hosts
 864     will remain on the node but no new IP addresses can be failed over
 865     to the node.
 866     </para>
 867     </refsect2>
 868
 869     <refsect2><title>NoIPHostOnAllDisabled</title>
 870     <para>Default: 0</para>
 871     <para>
 872     If no nodes are healthy then by default ctdb will happily host
 873     public IPs on disabled (unhealthy or administratively disabled)
 874     nodes.  This can cause problems, for example if the underlying
 875     cluster filesystem is not mounted.  When set to 1 on a node and
 876     that node is disabled it, any IPs hosted by this node will be
 877     released and the node will not takeover any IPs until it is no
 878     longer disabled.
 879     </para>
 880     </refsect2>
 881
 882     <refsect2><title>DBRecordCountWarn</title>
 883     <para>Default: 100000</para>
 884     <para>
 885     When set to non-zero, ctdb will log a warning when we try to recover a
 886     database with more than this many records. This will produce a warning
 887     if a database grows uncontrollably with orphaned records.
 888     </para>
 889     </refsect2>
 890
 891     <refsect2><title>DBRecordSizeWarn</title>
 892     <para>Default: 10000000</para>
 893     <para>
 894     When set to non-zero, ctdb will log a warning when we try to recover a
 895     database where a single record is bigger than this. This will produce
 896     a warning if a database record grows uncontrollably with orphaned
 897     sub-records.
 898     </para>
 899     </refsect2>
 900
 901     <refsect2><title>DBSizeWarn</title>
 902     <para>Default: 1000000000</para>
 903     <para>
 904     When set to non-zero, ctdb will log a warning when we try to recover a
 905     database bigger than this. This will produce
 906     a warning if a database grows uncontrollably.
 907     </para>
 908     </refsect2>
 909
 910     <refsect2><title>VerboseMemoryNames</title>
 911     <para>Default: 0</para>
 912     <para>
 913     This feature consumes additional memory. when used the talloc library
 914     will create more verbose names for all talloc allocated objects.
 915     </para>
 916     </refsect2>
 917
 918     <refsect2><title>RecdPingTimeout</title>
 919     <para>Default: 60</para>
 920     <para>
 921     If the main dameon has not heard a "ping" from the recovery dameon for
 922     this many seconds, the main dameon will log a message that the recovery
 923     daemon is potentially hung.
 924     </para>
 925     </refsect2>
 926
 927     <refsect2><title>RecdFailCount</title>
 928     <para>Default: 10</para>
 929     <para>
 930     If the recovery daemon has failed to ping the main dameon for this many
 931     consecutive intervals, the main daemon will consider the recovery daemon
 932     as hung and will try to restart it to recover.
 933     </para>
 934     </refsect2>
 935
 936     <refsect2><title>LogLatencyMs</title>
 937     <para>Default: 0</para>
 938     <para>
 939     When set to non-zero, this will make the main daemon log any operation that
 940     took longer than this value, in 'ms', to complete.
 941     These include "how long time a lockwait child process needed",
 942     "how long time to write to a persistent database" but also
 943     "how long did it take to get a response to a CALL from a remote node".
 944     </para>
 945     </refsect2>
 946
 947     <refsect2><title>RecLockLatencyMs</title>
 948     <para>Default: 1000</para>
 949     <para>
 950     When using a reclock file for split brain prevention, if set to non-zero
 951     this tunable will make the recovery dameon log a message if the fcntl()
 952     call to lock/testlock the recovery file takes longer than this number of
 953     ms.
 954     </para>
 955     </refsect2>
 956
 957     <refsect2><title>RecoveryDropAllIPs</title>
 958     <para>Default: 120</para>
 959     <para>
 960     If we have been stuck in recovery, or stopped, or banned, mode for
 961     this many seconds we will force drop all held public addresses.
 962     </para>
 963     </refsect2>
 964
 965     <refsect2><title>verifyRecoveryLock</title>
 966     <para>Default: 1</para>
 967     <para>
 968     Should we take a fcntl() lock on the reclock file to verify that we are the
 969     sole recovery master node on the cluster or not.
 970     </para>
 971     </refsect2>
 972
 973     <refsect2><title>DeferredAttachTO</title>
 974     <para>Default: 120</para>
 975     <para>
 976     When databases are frozen we do not allow clients to attach to the
 977     databases. Instead of returning an error immediately to the application
 978     the attach request from the client is deferred until the database
 979     becomes available again at which stage we respond to the client.
 980     </para>
 981     <para>
 982     This timeout controls how long we will defer the request from the client
 983     before timing it out and returning an error to the client.
 984     </para>
 985     </refsect2>
 986
 987     <refsect2><title>HopcountMakeSticky</title>
 988     <para>Default: 50</para>
 989     <para>
 990     If the database is set to 'STICKY' mode, using the 'ctdb setdbsticky'
 991     command, any record that is seen as very hot and migrating so fast that
 992     hopcount surpasses 50 is set to become a STICKY record for StickyDuration
 993     seconds. This means that after each migration the record will be kept on
 994     the node and prevented from being migrated off the node.
 995     </para>
 996     <para>
 997     This setting allows one to try to identify such records and stop them from
 998     migrating across the cluster so fast. This will improve performance for
 999     certain workloads, such as locking.tdb if many clients are opening/closing
1000     the same file concurrently.
1001     </para>
1002     </refsect2>
1003
1004     <refsect2><title>StickyDuration</title>
1005     <para>Default: 600</para>
1006     <para>
1007     Once a record has been found to be fetch-lock hot and has been flagged to
1008     become STICKY, this is for how long, in seconds, the record will be
1009     flagged as a STICKY record.
1010     </para>
1011     </refsect2>
1012
1013     <refsect2><title>StickyPindown</title>
1014     <para>Default: 200</para>
1015     <para>
1016     Once a STICKY record has been migrated onto a node, it will be pinned down
1017     on that node for this number of ms. Any request from other nodes to migrate
1018     the record off the node will be deferred until the pindown timer expires.
1019     </para>
1020     </refsect2>
1021
1022     <refsect2><title>MaxLACount</title>
1023     <para>Default: 20</para>
1024     <para>
1025     When record content is fetched from a remote node, if it is only for
1026     reading the record, pass back the content of the record but do not yet
1027     migrate the record. Once MaxLACount identical requests from the
1028     same remote node have been seen will the record be forcefully migrated
1029     onto the requesting node. This reduces the amount of migration for a
1030     database read-mostly workload at the expense of more frequent network
1031     roundtrips.
1032     </para>
1033     </refsect2>
1034
1035     <refsect2><title>StatHistoryInterval</title>
1036     <para>Default: 1</para>
1037     <para>
1038     Granularity of the statistics collected in the statistics history.
1039     </para>
1040     </refsect2>
1041
1042     <refsect2><title>AllowClientDBAttach</title>
1043     <para>Default: 1</para>
1044     <para>
1045     When set to 0, clients are not allowed to attach to any databases.
1046     This can be used to temporarily block any new processes from attaching
1047     to and accessing the databases.
1048     </para>
1049     </refsect2>
1050
1051     <refsect2><title>RecoverPDBBySeqNum</title>
1052     <para>Default: 0</para>
1053     <para>
1054     When set to non-zero, this will change how the recovery process for
1055     persistent databases ar performed. By default, when performing a database
1056     recovery, for normal as for persistent databases, recovery is
1057     record-by-record and recovery process simply collects the most recent
1058     version of every individual record.
1059     </para>
1060     <para>
1061     When set to non-zero, persistent databases will instead be recovered as
1062     a whole db and not by individual records. The node that contains the
1063     highest value stored in the record "__db_sequence_number__" is selected
1064     and the copy of that nodes database is used as the recovered database.
1065     </para>
1066     </refsect2>
1067
1068     <refsect2><title>FetchCollapse</title>
1069     <para>Default: 1</para>
1070     <para>
1071     When many clients across many nodes try to access the same record at the
1072     same time this can lead to a fetch storm where the record becomes very
1073     active and bounces between nodes very fast. This leads to high CPU
1074     utilization of the ctdbd daemon, trying to bounce that record around
1075     very fast, and poor performance.
1076     </para>
1077     <para>
1078     This parameter is used to activate a fetch-collapse. A fetch-collapse
1079     is when we track which records we have requests in flight so that we only
1080     keep one request in flight from a certain node, even if multiple smbd
1081     processes are attemtping to fetch the record at the same time. This
1082     can improve performance and reduce CPU utilization for certain
1083     workloads.
1084     </para>
1085     <para>
1086     This timeout controls if we should collapse multiple fetch operations
1087     of the same record into a single request and defer all duplicates or not.
1088     </para>
1089     </refsect2>
1090
1091     <refsect2><title>Samba3AvoidDeadlocks</title>
1092     <para>Default: 0</para>
1093     <para>
1094     Enable code that prevents deadlocks with Samba (only for Samba 3.x).
1095     </para>
1096     <para>
1097     This should be set to 1 when using Samba version 3.x to enable special
1098     code in CTDB to avoid deadlock with Samba version 3.x.  This code
1099     is not required for Samba version 4.x and must not be enabled for
1100     Samba 4.x.
1101     </para>
1102     </refsect2>
1103   </refsect1>
1104
1105   <refsect1><title>LVS</title>
1106     <para>
1107     LVS is a mode where CTDB presents one single IP address for the entire
1108     cluster. This is an alternative to using public IP addresses and round-robin
1109     DNS to loadbalance clients across the cluster.
1110     </para>
1111
1112     <para>
1113     This is similar to using a layer-4 loadbalancing switch but with some restrictions.
1114     </para>
1115
1116     <para>
1117     In this mode the cluster select a set of nodes in the cluster and loadbalance
1118     all client access to the LVS address across this set of nodes. This set of nodes are all LVS capable nodes that are HEALTHY, or if no HEALTHY nodes exists
1119     all LVS capable nodes regardless of health status.
1120     LVS will however never loadbalance traffic to nodes that are BANNED,
1121     STOPPED, DISABLED or DISCONNECTED. The "ctdb lvs" command is used to show
1122     which nodes are currently load-balanced across.
1123     </para>
1124
1125     <para>
1126     One of the these nodes are elected as the LVSMASTER. This node receives all
1127     traffic from clients coming in to the LVS address and multiplexes it
1128     across the internal network to one of the nodes that LVS is using.
1129     When responding to the client, that node will send the data back
1130     directly to the client, bypassing the LVSMASTER node.
1131     The command "ctdb lvsmaster" will show which node is the current
1132     LVSMASTER.
1133     </para>
1134
1135     <para>
1136     The path used for a client i/o is thus :
1137     <screen format="linespecific">
1138         (1) Client sends request packet to LVSMASTER
1139         (2) LVSMASTER passes the request on to one node across the internal network.
1140         (3) Selected node processes the request.
1141         (4) Node responds back to client.
1142     </screen>
1143     </para>
1144
1145     <para>
1146     This means that all incoming traffic to the cluster will pass through
1147     one physical node, which limits scalability. You can send more data to the
1148     LVS address that one physical node can multiplex. This means that you
1149     should not use LVS if your I/O pattern is write-intensive since you will be
1150     limited in the available network bandwidth that node can handle.
1151     LVS does work wery well for read-intensive workloads where only smallish
1152     READ requests are going through the LVSMASTER bottleneck and the majority
1153     of the traffic volume (the data in the read replies) goes straight from
1154     the processing node back to the clients. For read-intensive i/o patterns you can acheive very high throughput rates in this mode.
1155     </para>
1156
1157     <para>
1158     Note: you can use LVS and public addresses at the same time.
1159     </para>
1160
1161     <refsect2><title>Configuration</title>
1162         <para>
1163     To activate LVS on a CTDB node you must specify CTDB_PUBLIC_INTERFACE and
1164     CTDB_LVS_PUBLIC_ADDRESS in /etc/sysconfig/ctdb.
1165         </para>
1166
1167         <para>
1168 You must also specify the "--lvs" command line argument to ctdbd to activate LVS as a capability of the node. This should be done automatically for you by the /etc/init.d/ctdb script.
1169         </para>
1170
1171         <para>
1172         Example:
1173     <screen format="linespecific">
1174         CTDB_PUBLIC_INTERFACE=eth0
1175         CTDB_LVS_PUBLIC_IP=10.0.0.237
1176         </screen>
1177         </para>
1178
1179     </refsect2>
1180
1181     <para>
1182     If you use LVS, you must still have a real/permanent address configured
1183     for the public interface on each node. This address must be routable
1184     and the cluster nodes must be configured so that all traffic back to client
1185     hosts are routed through this interface. This is also required in order
1186     to allow samba/winbind on the node to talk to the domain controller.
1187     (we can not use the lvs IP address to initiate outgoing traffic)
1188     </para>
1189     <para>
1190     I.e. make sure that you can "ping" both the domain controller and also
1191     all of the clients from the node BEFORE you enable LVS. Also make sure
1192     that when you ping these hosts that the traffic is routed out through the
1193     eth0 interface.
1194     </para>
1195   </refsect1>
1196
1197
1198   <refsect1><title>REMOTE CLUSTER NODES</title>
1199     <para>
1200 It is possible to have a CTDB cluster that spans across a WAN link.
1201 For example where you have a CTDB cluster in your datacentre but you also
1202 want to have one additional CTDB node located at a remote branch site.
1203 This is similar to how a WAN accelerator works but with the difference
1204 that while a WAN-accelerator often acts as a Proxy or a MitM, in
1205 the ctdb remote cluster node configuration the Samba instance at the remote site
1206 IS the genuine server, not a proxy and not a MitM, and thus provides 100%
1207 correct CIFS semantics to clients.
1208     </para>
1209
1210     <para>
1211         See the cluster as one single multihomed samba server where one of
1212         the NICs (the remote node) is very far away.
1213     </para>
1214
1215     <para>
1216         NOTE: This does require that the cluster filesystem you use can cope
1217         with WAN-link latencies. Not all cluster filesystems can handle
1218         WAN-link latencies! Whether this will provide very good WAN-accelerator
1219         performance or it will perform very poorly depends entirely
1220         on how optimized your cluster filesystem is in handling high latency
1221         for data and metadata operations.
1222     </para>
1223
1224     <para>
1225         To activate a node as being a remote cluster node you need to set
1226         the following two parameters in /etc/sysconfig/ctdb  for the remote node:
1227         <screen format="linespecific">
1228 CTDB_CAPABILITY_LMASTER=no
1229 CTDB_CAPABILITY_RECMASTER=no
1230         </screen>
1231     </para>
1232
1233     <para>
1234         Verify with the command "ctdb getcapabilities" that that node no longer
1235         has the recmaster or the lmaster capabilities.
1236     </para>
1237
1238   </refsect1>
1239
1240
1241   <refsect1><title>NAT-GW</title>
1242     <para>
1243       Sometimes it is desireable to run services on the CTDB node which will
1244       need to originate outgoing traffic to external servers. This might
1245       be contacting NIS servers, LDAP servers etc. etc.
1246     </para>
1247     <para>
1248       This can sometimes be problematic since there are situations when a
1249       node does not have any public ip addresses assigned. This could
1250       be due to the nobe just being started up and no addresses have been
1251       assigned yet or it could be that the node is UNHEALTHY in which
1252       case all public addresses have been migrated off.
1253     </para>
1254     <para>
1255       If then the service status of CTDB depends on such services being
1256       able to always being able to originate traffic to external resources
1257       this becomes extra troublesome. The node might be UNHEALTHY because
1258       the service can not be reached, and the service can not be reached
1259       because the node is UNHEALTHY.
1260     </para>
1261     <para>
1262       There are two ways to solve this problem. The first is by assigning a
1263       static ip address for one public interface on every node which will allow
1264       every node to be able to route traffic to the public network even
1265       if there are no public addresses assigned to the node.
1266       This is the simplest way but it uses up a lot of ip addresses since you
1267       have to assign both static and also public addresses to each node.
1268     </para>
1269     <refsect2><title>NAT-GW</title>
1270     <para>
1271       A second way is to use the built in NAT-GW feature in CTDB.
1272       With NAT-GW you assign one public NATGW address for each natgw group.
1273       Each NATGW group is a set of nodes in the cluster that shares the same
1274       NATGW address to talk to the outside world. Normally there would only be
1275       one NATGW group spanning the entire cluster, but in situations where one
1276       ctdb cluster spans multiple physical sites it is useful to have one
1277       NATGW group for each of the two sites.
1278     </para>
1279     <para>
1280       There can be multiple NATGW groups in one cluster but each node can only
1281       be member of one NATGW group.
1282     </para>
1283     <para>
1284       In each NATGW group, one of the nodes is designated the NAT Gateway
1285       through which all traffic that is originated by nodes in this group
1286       will be routed through if a public addresses are not available.
1287     </para>
1288     </refsect2>
1289
1290     <refsect2><title>Configuration</title>
1291     <para>
1292       NAT-GW is configured in /etc/sysconfig/ctdb by setting the following
1293       variables:
1294     </para>
1295     <screen format="linespecific">
1296 # NAT-GW configuration
1297 # Some services running on nthe CTDB node may need to originate traffic to
1298 # remote servers before the node is assigned any IP addresses,
1299 # This is problematic since before the node has public addresses the node might
1300 # not be able to route traffic to the public networks.
1301 # One solution is to have static public addresses assigned with routing
1302 # in addition to the public address interfaces, thus guaranteeing that
1303 # a node always can route traffic to the external network.
1304 # This is the most simple solution but it uses up a large number of
1305 # additional ip addresses.
1306 #
1307 # A more complex solution is NAT-GW.
1308 # In this mode we only need one additional ip address for the cluster from
1309 # the exsternal public network.
1310 # One of the nodes in the cluster is elected to be hosting this ip address
1311 # so it can reach the external services. This node is also configured
1312 # to use NAT MASQUERADING for all traffic from the internal private network
1313 # to the external network. This node is the NAT-GW node.
1314 #
1315 # All other nodes are set up with a default rote with a metric of 10 to point
1316 # to the nat-gw node.
1317 #
1318 # The effect of this is that only when a node does not have a public address
1319 # and thus no proper routes to the external world it will instead
1320 # route all packets through the nat-gw node.
1321 #
1322 # CTDB_NATGW_NODES is the list of nodes that belong to this natgw group.
1323 # You can have multiple natgw groups in one cluster but each node
1324 # can only belong to one single natgw group.
1325 #
1326 # CTDB_NATGW_PUBLIC_IP=10.0.0.227/24
1327 # CTDB_NATGW_PUBLIC_IFACE=eth0
1328 # CTDB_NATGW_DEFAULT_GATEWAY=10.0.0.1
1329 # CTDB_NATGW_PRIVATE_NETWORK=10.1.1.0/24
1330 # CTDB_NATGW_NODES=/etc/ctdb/natgw_nodes
1331 #
1332 # Normally any node in the natgw group can act as the natgw master.
1333 # In some configurations you may have special nodes that is a part of the
1334 # cluster/natgw group, but where the node lacks connectivity to the
1335 # public network.
1336 # For these cases, set this variable to make these nodes not able to
1337 # become natgw master.
1338 #
1339 # CTDB_NATGW_SLAVE_ONLY=yes
1340     </screen>
1341     </refsect2>
1342
1343     <refsect2><title>CTDB_NATGW_PUBLIC_IP</title>
1344     <para>
1345       This is an ip address in the public network that is used for all outgoing
1346       traffic when the public addresses are not assigned.
1347       This address will be assigned to one of the nodes in the cluster which
1348       will masquerade all traffic for the other nodes.
1349     </para>
1350     <para>
1351       Format of this parameter is IPADDRESS/NETMASK
1352     </para>
1353     </refsect2>
1354
1355     <refsect2><title>CTDB_NATGW_PUBLIC_IFACE</title>
1356     <para>
1357       This is the physical interface where the CTDB_NATGW_PUBLIC_IP will be
1358       assigned to. This should be an interface connected to the public network.
1359     </para>
1360     <para>
1361       Format of this parameter is INTERFACE
1362     </para>
1363     </refsect2>
1364
1365     <refsect2><title>CTDB_NATGW_DEFAULT_GATEWAY</title>
1366     <para>
1367       This is the default gateway to use on the node that is elected to host
1368       the CTDB_NATGW_PUBLIC_IP. This is the default gateway on the public network.
1369     </para>
1370     <para>
1371       Format of this parameter is IPADDRESS
1372     </para>
1373     </refsect2>
1374
1375     <refsect2><title>CTDB_NATGW_PRIVATE_NETWORK</title>
1376     <para>
1377       This is the network/netmask used for the interal private network.
1378     </para>
1379     <para>
1380       Format of this parameter is IPADDRESS/NETMASK
1381     </para>
1382     </refsect2>
1383
1384     <refsect2><title>CTDB_NATGW_NODES</title>
1385     <para>
1386       This is the list of all nodes that belong to the same NATGW group
1387       as this node. The default is /etc/ctdb/natgw_nodes.
1388     </para>
1389     </refsect2>
1390
1391     <refsect2><title>Operation</title>
1392     <para>
1393       When the NAT-GW functionality is used, one of the nodes is elected
1394       to act as a NAT router for all the other nodes in the group when
1395       they need to originate traffic to the external public network.
1396     </para>
1397     <para>
1398       The NAT-GW node is assigned the CTDB_NATGW_PUBLIC_IP to the
1399       specified interface and the provided default route.  Given that
1400       the NAT-GW mechanism acts as a last resort, its default route is
1401       added with a metric of 10 so that it can coexist with other
1402       configured static routes.  The NAT-GW is configured to act as a
1403       router and to masquerade all traffic it receives from the
1404       internal private network and which is destined to the external
1405       network(s).
1406     </para>
1407     <para>
1408       All other nodes in the group are configured with a default route of
1409       metric 10 pointing to the designated NAT GW node.
1410     </para>
1411     <para>
1412       This is implemented in the 11.natgw eventscript. Please see the
1413       eventscript for further information.
1414     </para>
1415
1416     </refsect2>
1417
1418     <refsect2><title>Removing/Changing NATGW at runtime</title>
1419     <para>
1420       The following are the procedures to change/remove a NATGW configuration
1421       at runtime, without having to restart ctdbd.
1422     </para>
1423
1424     <para>
1425       If you want to remove NATGW completely from a node, use these steps:
1426     </para>
1427     <screen format="linespecific">
1428 1, Run 'CTDB_BASE=/etc/ctdb /etc/ctdb/events.d/11.natgw removenatgw'
1429 2, Then remove the configuration from /etc/sysconfig/ctdb
1430     </screen>
1431
1432     <para>
1433       If you want to change the NATGW configuration on a node :
1434     </para>
1435     <screen format="linespecific">
1436 1, Run 'CTDB_BASE=/etc/ctdb /etc/ctdb/events.d/11.natgw removenatgw'
1437 2, Then change the configuration in /etc/sysconfig/ctdb
1438 3, Run 'CTDB_BASE=/etc/ctdb /etc/ctdb/events.d/11.natgw updatenatgw'
1439     </screen>
1440
1441     </refsect2>
1442
1443   </refsect1>
1444
1445   <refsect1>
1446     <title>POLICY ROUTING</title>
1447
1448     <para>
1449       A node running CTDB may be a component of a complex network
1450       topology.  In particular, public addresses may be spread across
1451       several different networks (or VLANs) and it may not be possible
1452       to route packets from these public addresses via the system's
1453       default route.  Therefore, CTDB has support for policy routing
1454       via the 13.per_ip_routing eventscript.  This allows routing to
1455       be specified for packets sourced from each public address.  The
1456       routes are added and removed as CTDB moves public addresses
1457       between nodes.
1458     </para>
1459
1460     <refsect2>
1461       <title>Configuration variables</title>
1462
1463       <para>
1464         There are 4 configuration variables related to policy routing:
1465       </para>
1466
1467       <variablelist>
1468         <varlistentry><term><varname>CTDB_PER_IP_ROUTING_CONF</varname></term>
1469         <listitem>
1470           <para>
1471             The name of a configuration file that specifies the
1472             desired routes for each source address.  The configuration
1473             file format is discussed below.  A recommended value is
1474             <filename>/etc/ctdb/policy_routing</filename>.
1475           </para>
1476
1477           <para>
1478             The special value <constant>__auto_link_local__</constant>
1479             indicates that no configuration file is provided and that
1480             CTDB should generate reasonable link-local routes for each
1481             public address.
1482           </para>
1483         </listitem>
1484         </varlistentry>
1485
1486         <varlistentry><term><varname>CTDB_PER_IP_ROUTING_RULE_PREF</varname></term>
1487         <listitem>
1488           <para>
1489             This sets the priority (or preference) for the routing
1490             rules that are added by CTDB.
1491           </para>
1492
1493           <para>
1494             This should be (strictly) greater than 0 and (strictly)
1495             less than 32766.  A priority of 100 is recommended, unless
1496             this conflicts with a priority already in use on the
1497             system.  See ip(8) for more details.
1498           </para>
1499         </listitem>
1500         </varlistentry>
1501
1502         <varlistentry>
1503           <term>
1504             <varname>CTDB_PER_IP_ROUTING_TABLE_ID_LOW</varname>,
1505             <varname>CTDB_PER_IP_ROUTING_TABLE_ID_HIGH</varname>
1506           </term>
1507           <listitem>
1508             <para>
1509               CTDB determines a unique routing table number to use for
1510               the routing related to each public address.  These
1511               variables indicate the minimum and maximum routing table
1512               numbers that are used.
1513             </para>
1514
1515             <para>
1516               The ip command uses some reserved routing table numbers
1517               below 255.  Therefore, CTDB_PER_IP_ROUTING_TABLE_ID_LOW
1518               should be (strictly) greater than 255.  1000 and 9000
1519               are recommended values, unless this range conflicts with
1520               routing tables numbers already in use on the system.
1521             </para>
1522
1523             <para>
1524               CTDB uses the standard file
1525               <filename>/etc/iproute2/rt_tables</filename> to maintain
1526               a mapping between the routing table numbers and labels.
1527               The label for a public address &lt;addr;gt; will look
1528               like ctdb.&lt;addr&gt;.  This means that the associated
1529               rules and routes are easy to read (and manipulate).
1530             </para>
1531           </listitem>
1532         </varlistentry>
1533       </variablelist>
1534     </refsect2>
1535
1536     <refsect2>
1537       <title>Configuration file</title>
1538
1539       <para>
1540         The format of each line is:
1541       </para>
1542
1543       <screen>
1544     &lt;public_address&gt; &lt;network&gt; [ &lt;gateway&gt; ]
1545       </screen>
1546
1547       <para>
1548         Leading whitespace is ignored and arbitrary whitespace may be
1549         used as a separator.  Lines that have a "public address" item
1550         that doesn't match an actual public address are ignored.  This
1551         means that comment lines can be added using a leading
1552         character such as '#', since this will never match an IP
1553         address.
1554       </para>
1555
1556       <para>
1557         A line without a gateway indicates a link local route.
1558       </para>
1559
1560       <para>
1561         For example, consider the configuration line:
1562       </para>
1563
1564       <screen>
1565   192.168.1.99  192.168.1.1/24
1566       </screen>
1567
1568       <para>
1569         If the corresponding public_addresses line is:
1570       </para>
1571
1572       <screen>
1573   192.168.1.99/24     eth2,eth3
1574       </screen>
1575
1576       <para>
1577         <varname>CTDB_PER_IP_ROUTING_RULE_PREF</varname> is 100, and
1578         CTDB adds the address to eth2 then the following routing
1579         information is added:
1580       </para>
1581
1582       <screen>
1583   ip rule add from 192.168.1.99 pref 100 table ctdb.192.168.1.99
1584   ip route add 192.168.1.0/24 dev eth2 table ctdb.192.168.1.99
1585       </screen>
1586
1587       <para>
1588         This causes traffic from 192.168.1.1 to 192.168.1.0/24 go via
1589         eth2.
1590       </para>
1591
1592       <para>
1593         The <command>ip rule</command> command will show (something
1594         like - depending on other public addresses and other routes on
1595         the system):
1596       </para>
1597
1598       <screen>
1599   0:            from all lookup local
1600   100:          from 192.168.1.99 lookup ctdb.192.168.1.99
1601   32766:        from all lookup main
1602   32767:        from all lookup default
1603       </screen>
1604
1605       <para>
1606         <command>ip route show table ctdb.192.168.1.99</command> will show:
1607       </para>
1608
1609       <screen>
1610   192.168.1.0/24 dev eth2 scope link
1611       </screen>
1612
1613       <para>
1614         The usual use for a line containing a gateway is to add a
1615         default route corresponding to a particular source address.
1616         Consider this line of configuration:
1617       </para>
1618
1619       <screen>
1620   192.168.1.99  0.0.0.0/0       192.168.1.1
1621       </screen>
1622
1623       <para>
1624         In the situation described above this will cause an extra
1625         routing command to be executed:
1626       </para>
1627
1628       <screen>
1629   ip route add 0.0.0.0/0 via 192.168.1.1 dev eth2 table ctdb.192.168.1.99
1630       </screen>
1631
1632       <para>
1633         With both configuration lines, <command>ip route show table
1634         ctdb.192.168.1.99</command> will show:
1635       </para>
1636
1637       <screen>
1638   192.168.1.0/24 dev eth2 scope link
1639   default via 192.168.1.1 dev eth2
1640       </screen>
1641     </refsect2>
1642
1643     <refsect2>
1644       <title>Example configuration</title>
1645
1646       <para>
1647         Here is a more complete example configuration.
1648       </para>
1649
1650       <screen>
1651 /etc/ctdb/public_addresses:
1652
1653   192.168.1.98  eth2,eth3
1654   192.168.1.99  eth2,eth3
1655
1656 /etc/ctdb/policy_routing:
1657
1658   192.168.1.98 192.168.1.0/24
1659   192.168.1.98 192.168.200.0/24 192.168.1.254
1660   192.168.1.98 0.0.0.0/0        192.168.1.1
1661   192.168.1.99 192.168.1.0/24
1662   192.168.1.99 192.168.200.0/24 192.168.1.254
1663   192.168.1.99 0.0.0.0/0        192.168.1.1
1664       </screen>
1665
1666       <para>
1667         The routes local packets as expected, the default route is as
1668         previously discussed, but packets to 192.168.200.0/24 are
1669         routed via the alternate gateway 192.168.1.254.
1670       </para>
1671
1672     </refsect2>
1673   </refsect1>
1674
1675   <refsect1><title>NOTIFICATION SCRIPT</title>
1676     <para>
1677       Notification scripts are used with ctdb to have a call-out from ctdb
1678       to a user-specified script when certain state changes occur in ctdb.
1679       This is commonly to set up either sending SNMP traps or emails
1680       when a node becomes unhealthy and similar.
1681     </para>
1682     <para>
1683       This is activated by setting CTDB_NOTIFY_SCRIPT=&lt;your script&gt; in the
1684         sysconfig file, or by adding --notification-script=&lt;your script&gt;.
1685     </para>
1686     <para>
1687       See /etc/ctdb/notify.sh for an example script.  This script
1688       executes files in <filename>/etc/ctdb/notify.d/</filename>, so
1689       it is recommended that you handle notifications using the
1690       example script and by place executable scripts in
1691       <filename>/etc/ctdb/notify.d/</filename> to handle the desired
1692       notifications.
1693     </para>
1694     <para>
1695       CTDB currently generates notifications on these state changes:
1696     </para>
1697
1698     <refsect2><title>unhealthy</title>
1699     <para>
1700       This call-out is triggered when the node changes to UNHEALTHY state.
1701     </para>
1702     </refsect2>
1703
1704     <refsect2><title>healthy</title>
1705     <para>
1706       This call-out is triggered when the node changes to HEALTHY state.
1707     </para>
1708     </refsect2>
1709
1710     <refsect2><title>startup</title>
1711     <para>
1712       This call-out is triggered when ctdb has started up and all managed services are up and running.
1713     </para>
1714     </refsect2>
1715
1716   </refsect1>
1717
1718
1719 <refsect1><title>ClamAV Daemon</title>
1720 <para>
1721 CTDB has support to manage the popular anti-virus daemon ClamAV.
1722 This support is implemented through the
1723 eventscript : /etc/ctdb/events.d/31.clamd.
1724 </para>
1725
1726 <refsect2><title>Configuration</title>
1727 <para>
1728 Start by configuring CLAMAV normally and test that it works. Once this is
1729 done, copy the configuration files over to all the nodes so that all nodes
1730 share identical CLAMAV configurations.
1731 Once this is done you can proceed with the intructions below to activate
1732 CTDB support for CLAMAV.
1733 </para>
1734
1735 <para>
1736 First, to activate CLAMAV support in CTDB, edit /etc/sysconfig/ctdb and add the two lines :
1737 </para>
1738 <screen format="linespecific">
1739 CTDB_MANAGES_CLAMD=yes
1740 CTDB_CLAMD_SOCKET="/path/to/clamd.socket"
1741 </screen>
1742
1743 <para>
1744 Second, activate the eventscript
1745 </para>
1746 <screen format="linespecific">
1747 ctdb enablescript 31.clamd
1748 </screen>
1749
1750 <para>
1751 Third, CTDB will now be starting and stopping this service accordingly,
1752 so make sure that the system is not configured to start/stop this service
1753 automatically.
1754 On RedHat systems you can disable the system starting/stopping CLAMAV automatically by running :
1755 <screen format="linespecific">
1756 chkconfig clamd off
1757 </screen>
1758 </para>
1759
1760
1761 <para>
1762 Once you have restarted CTDBD, use
1763 <screen format="linespecific">
1764 ctdb scriptstatus
1765 </screen>
1766 and verify that the 31.clamd eventscript is listed and that it was executed successfully.
1767 </para>
1768
1769 </refsect2>
1770 </refsect1>
1771
1772
1773
1774
1775   <refsect1><title>SEE ALSO</title>
1776     <para>
1777       ctdb(1), onnode(1)
1778       <ulink url="http://ctdb.samba.org/"/>
1779     </para>
1780   </refsect1>
1781
1782   <refsect1><title>COPYRIGHT/LICENSE</title>
1783 <literallayout>
1784 Copyright (C) Andrew Tridgell 2007
1785 Copyright (C) Ronnie sahlberg 2007
1786
1787 This program is free software; you can redistribute it and/or modify
1788 it under the terms of the GNU General Public License as published by
1789 the Free Software Foundation; either version 3 of the License, or (at
1790 your option) any later version.
1791
1792 This program is distributed in the hope that it will be useful, but
1793 WITHOUT ANY WARRANTY; without even the implied warranty of
1794 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1795 General Public License for more details.
1796
1797 You should have received a copy of the GNU General Public License
1798 along with this program; if not, see http://www.gnu.org/licenses/.
1799 </literallayout>
1800   </refsect1>
1801 </refentry>