ctdb/doc/ctdb.7.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 <refentry id="ctdb.7">
   6
   7 <refmeta>
   8         <refentrytitle>ctdb</refentrytitle>
   9         <manvolnum>7</manvolnum>
  10         <refmiscinfo class="source">ctdb</refmiscinfo>
  11         <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
  12 </refmeta>
  13
  14
  15 <refnamediv>
  16         <refname>ctdb</refname>
  17         <refpurpose>Clustered TDB</refpurpose>
  18 </refnamediv>
  19
  20 <refsect1>
  21   <title>DESCRIPTION</title>
  22
  23   <para>
  24     CTDB is a clustered database component in clustered Samba that
  25     provides a high-availability load-sharing CIFS server cluster.
  26   </para>
  27
  28   <para>
  29     The main functions of CTDB are:
  30   </para>
  31
  32   <itemizedlist>
  33     <listitem>
  34       <para>
  35         Provide a clustered version of the TDB database with automatic
  36         rebuild/recovery of the databases upon node failures.
  37       </para>
  38     </listitem>
  39
  40     <listitem>
  41       <para>
  42       Monitor nodes in the cluster and services running on each node.
  43       </para>
  44     </listitem>
  45
  46     <listitem>
  47       <para>
  48         Manage a pool of public IP addresses that are used to provide
  49         services to clients.  Alternatively, CTDB can be used with
  50         LVS.
  51       </para>
  52     </listitem>
  53   </itemizedlist>
  54
  55   <para>
  56     Combined with a cluster filesystem CTDB provides a full
  57     high-availablity (HA) environment for services such as clustered
  58     Samba, NFS and other services.
  59   </para>
  60 </refsect1>
  61
  62 <refsect1>
  63   <title>ANATOMY OF A CTDB CLUSTER</title>
  64
  65   <para>
  66     A CTDB cluster is a collection of nodes with 2 or more network
  67     interfaces.  All nodes provide network (usually file/NAS) services
  68     to clients.  Data served by file services is stored on shared
  69     storage (usually a cluster filesystem) that is accessible by all
  70     nodes.
  71   </para>
  72   <para>
  73     CTDB provides an "all active" cluster, where services are load
  74     balanced across all nodes.
  75   </para>
  76 </refsect1>
  77
  78   <refsect1>
  79     <title>Recovery Lock</title>
  80
  81     <para>
  82       CTDB uses a <emphasis>recovery lock</emphasis> to avoid a
  83       <emphasis>split brain</emphasis>, where a cluster becomes
  84       partitioned and each partition attempts to operate
  85       independently.  Issues that can result from a split brain
  86       include file data corruption, because file locking metadata may
  87       not be tracked correctly.
  88     </para>
  89
  90     <para>
  91       CTDB uses a <emphasis>cluster leader and follower</emphasis>
  92       model of cluster management.  All nodes in a cluster elect one
  93       node to be the leader.  The leader node coordinates privileged
  94       operations such as database recovery and IP address failover.
  95       CTDB refers to the leader node as the <emphasis>recovery
  96       master</emphasis>.  This node takes and holds the recovery lock
  97       to assert its privileged role in the cluster.
  98     </para>
  99
 100     <para>
 101       By default, the recovery lock is implemented using a file
 102       (specified by <parameter>CTDB_RECOVERY_LOCK</parameter>)
 103       residing in shared storage (usually) on a cluster filesystem.
 104       To support a recovery lock the cluster filesystem must support
 105       lock coherence.  See
 106       <citerefentry><refentrytitle>ping_pong</refentrytitle>
 107       <manvolnum>1</manvolnum></citerefentry> for more details.
 108     </para>
 109
 110     <para>
 111       The recovery lock can also be implemented using an arbitrary
 112       cluster mutex call-out by using an exclamation point ('!') as
 113       the first character of
 114       <parameter>CTDB_RECOVERY_LOCK</parameter>.  For example, a value
 115       of <command>!/usr/local/bin/myhelper recovery</command> would
 116       run the given helper with the specified arguments.  See the
 117       source code relating to cluster mutexes for clues about writing
 118       call-outs.
 119     </para>
 120
 121     <para>
 122       If a cluster becomes partitioned (for example, due to a
 123       communication failure) and a different recovery master is
 124       elected by the nodes in each partition, then only one of these
 125       recovery masters will be able to take the recovery lock.  The
 126       recovery master in the "losing" partition will not be able to
 127       take the recovery lock and will be excluded from the cluster.
 128       The nodes in the "losing" partition will elect each node in turn
 129       as their recovery master so eventually all the nodes in that
 130       partition will be excluded.
 131     </para>
 132
 133     <para>
 134       CTDB does sanity checks to ensure that the recovery lock is held
 135       as expected.
 136     </para>
 137
 138     <para>
 139       CTDB can run without a recovery lock but this is not recommended
 140       as there will be no protection from split brains.
 141     </para>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Private vs Public addresses</title>
 146
 147     <para>
 148       Each node in a CTDB cluster has multiple IP addresses assigned
 149       to it:
 150
 151       <itemizedlist>
 152         <listitem>
 153           <para>
 154             A single private IP address that is used for communication
 155             between nodes.
 156           </para>
 157         </listitem>
 158         <listitem>
 159           <para>
 160             One or more public IP addresses that are used to provide
 161             NAS or other services.
 162           </para>
 163         </listitem>
 164       </itemizedlist>
 165     </para>
 166
 167     <refsect2>
 168       <title>Private address</title>
 169
 170       <para>
 171         Each node is configured with a unique, permanently assigned
 172         private address.  This address is configured by the operating
 173         system.  This address uniquely identifies a physical node in
 174         the cluster and is the address that CTDB daemons will use to
 175         communicate with the CTDB daemons on other nodes.
 176       </para>
 177       <para>
 178         Private addresses are listed in the file specified by the
 179         <varname>CTDB_NODES</varname> configuration variable (see
 180         <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
 181         <manvolnum>5</manvolnum></citerefentry>, default
 182         <filename>/usr/local/etc/ctdb/nodes</filename>).  This file contains the
 183         list of private addresses for all nodes in the cluster, one
 184         per line. This file must be the same on all nodes in the
 185         cluster.
 186       </para>
 187       <para>
 188         Private addresses should not be used by clients to connect to
 189         services provided by the cluster.
 190       </para>
 191       <para>
 192         It is strongly recommended that the private addresses are
 193         configured on a private network that is separate from client
 194         networks.  This is because the CTDB protocol is both
 195         unauthenticated and unencrypted.  If clients share the private
 196         network then steps need to be taken to stop injection of
 197         packets to relevant ports on the private addresses.  It is
 198         also likely that CTDB protocol traffic between nodes could
 199         leak sensitive information if it can be intercepted.
 200       </para>
 201
 202       <para>
 203         Example <filename>/usr/local/etc/ctdb/nodes</filename> for a four node
 204         cluster:
 205       </para>
 206       <screen format="linespecific">
 207 192.168.1.1
 208 192.168.1.2
 209 192.168.1.3
 210 192.168.1.4
 211       </screen>
 212     </refsect2>
 213
 214     <refsect2>
 215       <title>Public addresses</title>
 216
 217       <para>
 218         Public addresses are used to provide services to clients.
 219         Public addresses are not configured at the operating system
 220         level and are not permanently associated with a particular
 221         node.  Instead, they are managed by CTDB and are assigned to
 222         interfaces on physical nodes at runtime.
 223       </para>
 224       <para>
 225         The CTDB cluster will assign/reassign these public addresses
 226         across the available healthy nodes in the cluster. When one
 227         node fails, its public addresses will be taken over by one or
 228         more other nodes in the cluster.  This ensures that services
 229         provided by all public addresses are always available to
 230         clients, as long as there are nodes available capable of
 231         hosting this address.
 232       </para>
 233       <para>
 234         The public address configuration is stored in a file on each
 235         node specified by the <varname>CTDB_PUBLIC_ADDRESSES</varname>
 236         configuration variable (see
 237         <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
 238         <manvolnum>5</manvolnum></citerefentry>, recommended
 239         <filename>/usr/local/etc/ctdb/public_addresses</filename>).  This file
 240         contains a list of the public addresses that the node is
 241         capable of hosting, one per line.  Each entry also contains
 242         the netmask and the interface to which the address should be
 243         assigned.
 244       </para>
 245
 246       <para>
 247         Example <filename>/usr/local/etc/ctdb/public_addresses</filename> for a
 248         node that can host 4 public addresses, on 2 different
 249         interfaces:
 250       </para>
 251       <screen format="linespecific">
 252 10.1.1.1/24 eth1
 253 10.1.1.2/24 eth1
 254 10.1.2.1/24 eth2
 255 10.1.2.2/24 eth2
 256       </screen>
 257
 258       <para>
 259         In many cases the public addresses file will be the same on
 260         all nodes.  However, it is possible to use different public
 261         address configurations on different nodes.
 262       </para>
 263
 264       <para>
 265         Example: 4 nodes partitioned into two subgroups:
 266       </para>
 267       <screen format="linespecific">
 268 Node 0:/usr/local/etc/ctdb/public_addresses
 269         10.1.1.1/24 eth1
 270         10.1.1.2/24 eth1
 271
 272 Node 1:/usr/local/etc/ctdb/public_addresses
 273         10.1.1.1/24 eth1
 274         10.1.1.2/24 eth1
 275
 276 Node 2:/usr/local/etc/ctdb/public_addresses
 277         10.1.2.1/24 eth2
 278         10.1.2.2/24 eth2
 279
 280 Node 3:/usr/local/etc/ctdb/public_addresses
 281         10.1.2.1/24 eth2
 282         10.1.2.2/24 eth2
 283       </screen>
 284       <para>
 285         In this example nodes 0 and 1 host two public addresses on the
 286         10.1.1.x network while nodes 2 and 3 host two public addresses
 287         for the 10.1.2.x network.
 288       </para>
 289       <para>
 290         Public address 10.1.1.1 can be hosted by either of nodes 0 or
 291         1 and will be available to clients as long as at least one of
 292         these two nodes are available.
 293       </para>
 294       <para>
 295         If both nodes 0 and 1 become unavailable then public address
 296         10.1.1.1 also becomes unavailable. 10.1.1.1 can not be failed
 297         over to nodes 2 or 3 since these nodes do not have this public
 298         address configured.
 299       </para>
 300       <para>
 301         The <command>ctdb ip</command> command can be used to view the
 302         current assignment of public addresses to physical nodes.
 303       </para>
 304     </refsect2>
 305   </refsect1>
 306
 307
 308   <refsect1>
 309     <title>Node status</title>
 310
 311     <para>
 312       The current status of each node in the cluster can be viewed by the
 313       <command>ctdb status</command> command.
 314     </para>
 315
 316     <para>
 317       A node can be in one of the following states:
 318     </para>
 319
 320     <variablelist>
 321       <varlistentry>
 322         <term>OK</term>
 323         <listitem>
 324           <para>
 325             This node is healthy and fully functional.  It hosts public
 326             addresses to provide services.
 327           </para>
 328         </listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term>DISCONNECTED</term>
 333         <listitem>
 334           <para>
 335             This node is not reachable by other nodes via the private
 336             network.  It is not currently participating in the cluster.
 337             It <emphasis>does not</emphasis> host public addresses to
 338             provide services.  It might be shut down.
 339           </para>
 340         </listitem>
 341       </varlistentry>
 342
 343       <varlistentry>
 344         <term>DISABLED</term>
 345         <listitem>
 346           <para>
 347             This node has been administratively disabled. This node is
 348             partially functional and participates in the cluster.
 349             However, it <emphasis>does not</emphasis> host public
 350             addresses to provide services.
 351           </para>
 352         </listitem>
 353       </varlistentry>
 354
 355       <varlistentry>
 356         <term>UNHEALTHY</term>
 357         <listitem>
 358           <para>
 359             A service provided by this node has failed a health check
 360             and should be investigated.  This node is partially
 361             functional and participates in the cluster.  However, it
 362             <emphasis>does not</emphasis> host public addresses to
 363             provide services.  Unhealthy nodes should be investigated
 364             and may require an administrative action to rectify.
 365           </para>
 366         </listitem>
 367       </varlistentry>
 368
 369       <varlistentry>
 370         <term>BANNED</term>
 371         <listitem>
 372           <para>
 373             CTDB is not behaving as designed on this node.  For example,
 374             it may have failed too many recovery attempts.  Such nodes
 375             are banned from participating in the cluster for a
 376             configurable time period before they attempt to rejoin the
 377             cluster.  A banned node <emphasis>does not</emphasis> host
 378             public addresses to provide services.  All banned nodes
 379             should be investigated and may require an administrative
 380             action to rectify.
 381           </para>
 382         </listitem>
 383       </varlistentry>
 384
 385       <varlistentry>
 386         <term>STOPPED</term>
 387         <listitem>
 388           <para>
 389             This node has been administratively exclude from the
 390             cluster.  A stopped node does no participate in the cluster
 391             and <emphasis>does not</emphasis> host public addresses to
 392             provide services.  This state can be used while performing
 393             maintenance on a node.
 394           </para>
 395         </listitem>
 396       </varlistentry>
 397
 398       <varlistentry>
 399         <term>PARTIALLYONLINE</term>
 400         <listitem>
 401           <para>
 402             A node that is partially online participates in a cluster
 403             like a healthy (OK) node.  Some interfaces to serve public
 404             addresses are down, but at least one interface is up.  See
 405             also <command>ctdb ifaces</command>.
 406           </para>
 407         </listitem>
 408       </varlistentry>
 409
 410     </variablelist>
 411   </refsect1>
 412
 413   <refsect1>
 414     <title>CAPABILITIES</title>
 415
 416     <para>
 417       Cluster nodes can have several different capabilities enabled.
 418       These are listed below.
 419     </para>
 420
 421     <variablelist>
 422
 423       <varlistentry>
 424         <term>RECMASTER</term>
 425         <listitem>
 426           <para>
 427             Indicates that a node can become the CTDB cluster recovery
 428             master.  The current recovery master is decided via an
 429             election held by all active nodes with this capability.
 430           </para>
 431           <para>
 432             Default is YES.
 433           </para>
 434         </listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term>LMASTER</term>
 439         <listitem>
 440           <para>
 441             Indicates that a node can be the location master (LMASTER)
 442             for database records.  The LMASTER always knows which node
 443             has the latest copy of a record in a volatile database.
 444           </para>
 445           <para>
 446             Default is YES.
 447           </para>
 448         </listitem>
 449       </varlistentry>
 450
 451     </variablelist>
 452
 453     <para>
 454       The RECMASTER and LMASTER capabilities can be disabled when CTDB
 455       is used to create a cluster spanning across WAN links. In this
 456       case CTDB acts as a WAN accelerator.
 457     </para>
 458
 459   </refsect1>
 460
 461   <refsect1>
 462     <title>LVS</title>
 463
 464     <para>
 465       LVS is a mode where CTDB presents one single IP address for the
 466       entire cluster. This is an alternative to using public IP
 467       addresses and round-robin DNS to loadbalance clients across the
 468       cluster.
 469     </para>
 470
 471     <para>
 472       This is similar to using a layer-4 loadbalancing switch but with
 473       some restrictions.
 474     </para>
 475
 476     <para>
 477       One extra LVS public address is assigned on the public network
 478       to each LVS group.  Each LVS group is a set of nodes in the
 479       cluster that presents the same LVS address public address to the
 480       outside world.  Normally there would only be one LVS group
 481       spanning an entire cluster, but in situations where one CTDB
 482       cluster spans multiple physical sites it might be useful to have
 483       one LVS group for each site.  There can be multiple LVS groups
 484       in a cluster but each node can only be member of one LVS group.
 485     </para>
 486
 487     <para>
 488       Client access to the cluster is load-balanced across the HEALTHY
 489       nodes in an LVS group.  If no HEALTHY nodes exists then all
 490       nodes in the group are used, regardless of health status.  CTDB
 491       will, however never load-balance LVS traffic to nodes that are
 492       BANNED, STOPPED, DISABLED or DISCONNECTED.  The <command>ctdb
 493       lvs</command> command is used to show which nodes are currently
 494       load-balanced across.
 495     </para>
 496
 497     <para>
 498       In each LVS group, one of the nodes is selected by CTDB to be
 499       the LVS master.  This node receives all traffic from clients
 500       coming in to the LVS public address and multiplexes it across
 501       the internal network to one of the nodes that LVS is using.
 502       When responding to the client, that node will send the data back
 503       directly to the client, bypassing the LVS master node.  The
 504       command <command>ctdb lvsmaster</command> will show which node
 505       is the current LVS master.
 506     </para>
 507
 508     <para>
 509       The path used for a client I/O is:
 510       <orderedlist>
 511         <listitem>
 512           <para>
 513             Client sends request packet to LVSMASTER.
 514           </para>
 515         </listitem>
 516         <listitem>
 517           <para>
 518             LVSMASTER passes the request on to one node across the
 519             internal network.
 520           </para>
 521         </listitem>
 522         <listitem>
 523           <para>
 524             Selected node processes the request.
 525           </para>
 526         </listitem>
 527         <listitem>
 528           <para>
 529             Node responds back to client.
 530           </para>
 531         </listitem>
 532       </orderedlist>
 533     </para>
 534
 535     <para>
 536       This means that all incoming traffic to the cluster will pass
 537       through one physical node, which limits scalability. You can
 538       send more data to the LVS address that one physical node can
 539       multiplex. This means that you should not use LVS if your I/O
 540       pattern is write-intensive since you will be limited in the
 541       available network bandwidth that node can handle.  LVS does work
 542       wery well for read-intensive workloads where only smallish READ
 543       requests are going through the LVSMASTER bottleneck and the
 544       majority of the traffic volume (the data in the read replies)
 545       goes straight from the processing node back to the clients. For
 546       read-intensive i/o patterns you can achieve very high throughput
 547       rates in this mode.
 548     </para>
 549
 550     <para>
 551       Note: you can use LVS and public addresses at the same time.
 552     </para>
 553
 554     <para>
 555       If you use LVS, you must have a permanent address configured for
 556       the public interface on each node. This address must be routable
 557       and the cluster nodes must be configured so that all traffic
 558       back to client hosts are routed through this interface. This is
 559       also required in order to allow samba/winbind on the node to
 560       talk to the domain controller.  This LVS IP address can not be
 561       used to initiate outgoing traffic.
 562     </para>
 563     <para>
 564       Make sure that the domain controller and the clients are
 565       reachable from a node <emphasis>before</emphasis> you enable
 566       LVS.  Also ensure that outgoing traffic to these hosts is routed
 567       out through the configured public interface.
 568     </para>
 569
 570     <refsect2>
 571       <title>Configuration</title>
 572
 573       <para>
 574         To activate LVS on a CTDB node you must specify the
 575         <varname>CTDB_LVS_PUBLIC_IFACE</varname>,
 576         <varname>CTDB_LVS_PUBLIC_IP</varname> and
 577         <varname>CTDB_LVS_NODES</varname> configuration variables.
 578         <varname>CTDB_LVS_NODES</varname> specifies a file containing
 579         the private address of all nodes in the current node's LVS
 580         group.
 581       </para>
 582
 583       <para>
 584         Example:
 585         <screen format="linespecific">
 586 CTDB_LVS_PUBLIC_IFACE=eth1
 587 CTDB_LVS_PUBLIC_IP=10.1.1.237
 588 CTDB_LVS_NODES=/usr/local/etc/ctdb/lvs_nodes
 589         </screen>
 590       </para>
 591
 592       <para>
 593         Example <filename>/usr/local/etc/ctdb/lvs_nodes</filename>:
 594       </para>
 595       <screen format="linespecific">
 596 192.168.1.2
 597 192.168.1.3
 598 192.168.1.4
 599       </screen>
 600
 601       <para>
 602         Normally any node in an LVS group can act as the LVS master.
 603         Nodes that are highly loaded due to other demands maybe
 604         flagged with the "slave-only" option in the
 605         <varname>CTDB_LVS_NODES</varname> file to limit the LVS
 606         functionality of those nodes.
 607       </para>
 608
 609       <para>
 610         LVS nodes file that excludes 192.168.1.4 from being
 611         the LVS master node:
 612       </para>
 613       <screen format="linespecific">
 614 192.168.1.2
 615 192.168.1.3
 616 192.168.1.4 slave-only
 617       </screen>
 618
 619     </refsect2>
 620   </refsect1>
 621
 622   <refsect1>
 623     <title>TRACKING AND RESETTING TCP CONNECTIONS</title>
 624
 625     <para>
 626       CTDB tracks TCP connections from clients to public IP addresses,
 627       on known ports.  When an IP address moves from one node to
 628       another, all existing TCP connections to that IP address are
 629       reset.  The node taking over this IP address will also send
 630       gratuitous ARPs (for IPv4, or neighbour advertisement, for
 631       IPv6).  This allows clients to reconnect quickly, rather than
 632       waiting for TCP timeouts, which can be very long.
 633     </para>
 634
 635     <para>
 636       It is important that established TCP connections do not survive
 637       a release and take of a public IP address on the same node.
 638       Such connections can get out of sync with sequence and ACK
 639       numbers, potentially causing a disruptive ACK storm.
 640     </para>
 641
 642   </refsect1>
 643
 644   <refsect1>
 645     <title>NAT GATEWAY</title>
 646
 647     <para>
 648       NAT gateway (NATGW) is an optional feature that is used to
 649       configure fallback routing for nodes.  This allows cluster nodes
 650       to connect to external services (e.g. DNS, AD, NIS and LDAP)
 651       when they do not host any public addresses (e.g. when they are
 652       unhealthy).
 653     </para>
 654     <para>
 655       This also applies to node startup because CTDB marks nodes as
 656       UNHEALTHY until they have passed a "monitor" event.  In this
 657       context, NAT gateway helps to avoid a "chicken and egg"
 658       situation where a node needs to access an external service to
 659       become healthy.
 660     </para>
 661     <para>
 662       Another way of solving this type of problem is to assign an
 663       extra static IP address to a public interface on every node.
 664       This is simpler but it uses an extra IP address per node, while
 665       NAT gateway generally uses only one extra IP address.
 666     </para>
 667
 668     <refsect2>
 669       <title>Operation</title>
 670
 671       <para>
 672         One extra NATGW public address is assigned on the public
 673         network to each NATGW group.  Each NATGW group is a set of
 674         nodes in the cluster that shares the same NATGW address to
 675         talk to the outside world.  Normally there would only be one
 676         NATGW group spanning an entire cluster, but in situations
 677         where one CTDB cluster spans multiple physical sites it might
 678         be useful to have one NATGW group for each site.
 679       </para>
 680       <para>
 681         There can be multiple NATGW groups in a cluster but each node
 682         can only be member of one NATGW group.
 683       </para>
 684       <para>
 685         In each NATGW group, one of the nodes is selected by CTDB to
 686         be the NATGW master and the other nodes are consider to be
 687         NATGW slaves.  NATGW slaves establish a fallback default route
 688         to the NATGW master via the private network.  When a NATGW
 689         slave hosts no public IP addresses then it will use this route
 690         for outbound connections.  The NATGW master hosts the NATGW
 691         public IP address and routes outgoing connections from
 692         slave nodes via this IP address.  It also establishes a
 693         fallback default route.
 694       </para>
 695     </refsect2>
 696
 697     <refsect2>
 698       <title>Configuration</title>
 699
 700       <para>
 701         NATGW is usually configured similar to the following example configuration:
 702       </para>
 703       <screen format="linespecific">
 704 CTDB_NATGW_NODES=/usr/local/etc/ctdb/natgw_nodes
 705 CTDB_NATGW_PRIVATE_NETWORK=192.168.1.0/24
 706 CTDB_NATGW_PUBLIC_IP=10.0.0.227/24
 707 CTDB_NATGW_PUBLIC_IFACE=eth0
 708 CTDB_NATGW_DEFAULT_GATEWAY=10.0.0.1
 709       </screen>
 710
 711       <para>
 712         Normally any node in a NATGW group can act as the NATGW
 713         master.  Some configurations may have special nodes that lack
 714         connectivity to a public network.  In such cases, those nodes
 715         can be flagged with the "slave-only" option in the
 716         <varname>CTDB_NATGW_NODES</varname> file to limit the NATGW
 717         functionality of those nodes.
 718       </para>
 719
 720       <para>
 721         See the <citetitle>NAT GATEWAY</citetitle> section in
 722         <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
 723         <manvolnum>5</manvolnum></citerefentry> for more details of
 724         NATGW configuration.
 725       </para>
 726     </refsect2>
 727
 728
 729     <refsect2>
 730       <title>Implementation details</title>
 731
 732       <para>
 733         When the NATGW functionality is used, one of the nodes is
 734         selected to act as a NAT gateway for all the other nodes in
 735         the group when they need to communicate with the external
 736         services.  The NATGW master is selected to be a node that is
 737         most likely to have usable networks.
 738       </para>
 739
 740       <para>
 741         The NATGW master hosts the NATGW public IP address
 742         <varname>CTDB_NATGW_PUBLIC_IP</varname> on the configured public
 743         interfaces <varname>CTDB_NATGW_PUBLIC_IFACE</varname> and acts as
 744         a router, masquerading outgoing connections from slave nodes
 745         via this IP address.  If
 746         <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is set then it
 747         also establishes a fallback default route to the configured
 748         this gateway with a metric of 10.  A metric 10 route is used
 749         so it can co-exist with other default routes that may be
 750         available.
 751       </para>
 752
 753       <para>
 754         A NATGW slave establishes its fallback default route to the
 755         NATGW master via the private network
 756         <varname>CTDB_NATGW_PRIVATE_NETWORK</varname>with a metric of 10.
 757         This route is used for outbound connections when no other
 758         default route is available because the node hosts no public
 759         addresses.  A metric 10 routes is used so that it can co-exist
 760         with other default routes that may be available when the node
 761         is hosting public addresses.
 762       </para>
 763
 764       <para>
 765         <varname>CTDB_NATGW_STATIC_ROUTES</varname> can be used to
 766         have NATGW create more specific routes instead of just default
 767         routes.
 768       </para>
 769
 770       <para>
 771         This is implemented in the <filename>11.natgw</filename>
 772         eventscript.  Please see the eventscript file and the
 773         <citetitle>NAT GATEWAY</citetitle> section in
 774         <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
 775         <manvolnum>5</manvolnum></citerefentry> for more details.
 776       </para>
 777
 778     </refsect2>
 779   </refsect1>
 780
 781   <refsect1>
 782     <title>POLICY ROUTING</title>
 783
 784     <para>
 785       Policy routing is an optional CTDB feature to support complex
 786       network topologies.  Public addresses may be spread across
 787       several different networks (or VLANs) and it may not be possible
 788       to route packets from these public addresses via the system's
 789       default route.  Therefore, CTDB has support for policy routing
 790       via the <filename>13.per_ip_routing</filename> eventscript.
 791       This allows routing to be specified for packets sourced from
 792       each public address.  The routes are added and removed as CTDB
 793       moves public addresses between nodes.
 794     </para>
 795
 796     <refsect2>
 797       <title>Configuration variables</title>
 798
 799       <para>
 800         There are 4 configuration variables related to policy routing:
 801         <varname>CTDB_PER_IP_ROUTING_CONF</varname>,
 802         <varname>CTDB_PER_IP_ROUTING_RULE_PREF</varname>,
 803         <varname>CTDB_PER_IP_ROUTING_TABLE_ID_LOW</varname>,
 804         <varname>CTDB_PER_IP_ROUTING_TABLE_ID_HIGH</varname>.  See the
 805         <citetitle>POLICY ROUTING</citetitle> section in
 806         <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
 807         <manvolnum>5</manvolnum></citerefentry> for more details.
 808       </para>
 809     </refsect2>
 810
 811     <refsect2>
 812       <title>Configuration</title>
 813
 814       <para>
 815         The format of each line of
 816         <varname>CTDB_PER_IP_ROUTING_CONF</varname> is:
 817       </para>
 818
 819       <screen>
 820 &lt;public_address&gt; &lt;network&gt; [ &lt;gateway&gt; ]
 821       </screen>
 822
 823       <para>
 824         Leading whitespace is ignored and arbitrary whitespace may be
 825         used as a separator.  Lines that have a "public address" item
 826         that doesn't match an actual public address are ignored.  This
 827         means that comment lines can be added using a leading
 828         character such as '#', since this will never match an IP
 829         address.
 830       </para>
 831
 832       <para>
 833         A line without a gateway indicates a link local route.
 834       </para>
 835
 836       <para>
 837         For example, consider the configuration line:
 838       </para>
 839
 840       <screen>
 841   192.168.1.99  192.168.1.1/24
 842       </screen>
 843
 844       <para>
 845         If the corresponding public_addresses line is:
 846       </para>
 847
 848       <screen>
 849   192.168.1.99/24     eth2,eth3
 850       </screen>
 851
 852       <para>
 853         <varname>CTDB_PER_IP_ROUTING_RULE_PREF</varname> is 100, and
 854         CTDB adds the address to eth2 then the following routing
 855         information is added:
 856       </para>
 857
 858       <screen>
 859   ip rule add from 192.168.1.99 pref 100 table ctdb.192.168.1.99
 860   ip route add 192.168.1.0/24 dev eth2 table ctdb.192.168.1.99
 861       </screen>
 862
 863       <para>
 864         This causes traffic from 192.168.1.1 to 192.168.1.0/24 go via
 865         eth2.
 866       </para>
 867
 868       <para>
 869         The <command>ip rule</command> command will show (something
 870         like - depending on other public addresses and other routes on
 871         the system):
 872       </para>
 873
 874       <screen>
 875   0:            from all lookup local
 876   100:          from 192.168.1.99 lookup ctdb.192.168.1.99
 877   32766:        from all lookup main
 878   32767:        from all lookup default
 879       </screen>
 880
 881       <para>
 882         <command>ip route show table ctdb.192.168.1.99</command> will show:
 883       </para>
 884
 885       <screen>
 886   192.168.1.0/24 dev eth2 scope link
 887       </screen>
 888
 889       <para>
 890         The usual use for a line containing a gateway is to add a
 891         default route corresponding to a particular source address.
 892         Consider this line of configuration:
 893       </para>
 894
 895       <screen>
 896   192.168.1.99  0.0.0.0/0       192.168.1.1
 897       </screen>
 898
 899       <para>
 900         In the situation described above this will cause an extra
 901         routing command to be executed:
 902       </para>
 903
 904       <screen>
 905   ip route add 0.0.0.0/0 via 192.168.1.1 dev eth2 table ctdb.192.168.1.99
 906       </screen>
 907
 908       <para>
 909         With both configuration lines, <command>ip route show table
 910         ctdb.192.168.1.99</command> will show:
 911       </para>
 912
 913       <screen>
 914   192.168.1.0/24 dev eth2 scope link
 915   default via 192.168.1.1 dev eth2
 916       </screen>
 917     </refsect2>
 918
 919     <refsect2>
 920       <title>Sample configuration</title>
 921
 922       <para>
 923         Here is a more complete example configuration.
 924       </para>
 925
 926       <screen>
 927 /usr/local/etc/ctdb/public_addresses:
 928
 929   192.168.1.98  eth2,eth3
 930   192.168.1.99  eth2,eth3
 931
 932 /usr/local/etc/ctdb/policy_routing:
 933
 934   192.168.1.98 192.168.1.0/24
 935   192.168.1.98 192.168.200.0/24 192.168.1.254
 936   192.168.1.98 0.0.0.0/0        192.168.1.1
 937   192.168.1.99 192.168.1.0/24
 938   192.168.1.99 192.168.200.0/24 192.168.1.254
 939   192.168.1.99 0.0.0.0/0        192.168.1.1
 940       </screen>
 941
 942       <para>
 943         The routes local packets as expected, the default route is as
 944         previously discussed, but packets to 192.168.200.0/24 are
 945         routed via the alternate gateway 192.168.1.254.
 946       </para>
 947
 948     </refsect2>
 949   </refsect1>
 950
 951   <refsect1>
 952     <title>NOTIFICATION SCRIPT</title>
 953
 954     <para>
 955       When certain state changes occur in CTDB, it can be configured
 956       to perform arbitrary actions via a notification script.  For
 957       example, sending SNMP traps or emails when a node becomes
 958       unhealthy or similar.
 959     </para>
 960     <para>
 961       This is activated by setting the
 962       <varname>CTDB_NOTIFY_SCRIPT</varname> configuration variable.
 963       The specified script must be executable.
 964     </para>
 965     <para>
 966       Use of the provided <filename>/usr/local/etc/ctdb/notify.sh</filename>
 967       script is recommended.  It executes files in
 968       <filename>/usr/local/etc/ctdb/notify.d/</filename>.
 969     </para>
 970     <para>
 971       CTDB currently generates notifications after CTDB changes to
 972       these states:
 973     </para>
 974
 975     <simplelist>
 976       <member>init</member>
 977       <member>setup</member>
 978       <member>startup</member>
 979       <member>healthy</member>
 980       <member>unhealthy</member>
 981     </simplelist>
 982
 983   </refsect1>
 984
 985   <refsect1>
 986     <title>DEBUG LEVELS</title>
 987
 988     <para>
 989       Valid values for DEBUGLEVEL are:
 990     </para>
 991
 992     <simplelist>
 993       <member>ERR</member>
 994       <member>WARNING</member>
 995       <member>NOTICE</member>
 996       <member>INFO</member>
 997       <member>DEBUG</member>
 998     </simplelist>
 999   </refsect1>
1000
1001
1002   <refsect1>
1003     <title>REMOTE CLUSTER NODES</title>
1004     <para>
1005 It is possible to have a CTDB cluster that spans across a WAN link.
1006 For example where you have a CTDB cluster in your datacentre but you also
1007 want to have one additional CTDB node located at a remote branch site.
1008 This is similar to how a WAN accelerator works but with the difference
1009 that while a WAN-accelerator often acts as a Proxy or a MitM, in
1010 the ctdb remote cluster node configuration the Samba instance at the remote site
1011 IS the genuine server, not a proxy and not a MitM, and thus provides 100%
1012 correct CIFS semantics to clients.
1013     </para>
1014
1015     <para>
1016         See the cluster as one single multihomed samba server where one of
1017         the NICs (the remote node) is very far away.
1018     </para>
1019
1020     <para>
1021         NOTE: This does require that the cluster filesystem you use can cope
1022         with WAN-link latencies. Not all cluster filesystems can handle
1023         WAN-link latencies! Whether this will provide very good WAN-accelerator
1024         performance or it will perform very poorly depends entirely
1025         on how optimized your cluster filesystem is in handling high latency
1026         for data and metadata operations.
1027     </para>
1028
1029     <para>
1030         To activate a node as being a remote cluster node you need to set
1031         the following two parameters in /etc/sysconfig/ctdb  for the remote node:
1032         <screen format="linespecific">
1033 CTDB_CAPABILITY_LMASTER=no
1034 CTDB_CAPABILITY_RECMASTER=no
1035         </screen>
1036     </para>
1037
1038     <para>
1039         Verify with the command "ctdb getcapabilities" that that node no longer
1040         has the recmaster or the lmaster capabilities.
1041     </para>
1042
1043   </refsect1>
1044
1045
1046   <refsect1>
1047     <title>SEE ALSO</title>
1048
1049     <para>
1050       <citerefentry><refentrytitle>ctdb</refentrytitle>
1051       <manvolnum>1</manvolnum></citerefentry>,
1052
1053       <citerefentry><refentrytitle>ctdbd</refentrytitle>
1054       <manvolnum>1</manvolnum></citerefentry>,
1055
1056       <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
1057       <manvolnum>1</manvolnum></citerefentry>,
1058
1059       <citerefentry><refentrytitle>ctdb_diagnostics</refentrytitle>
1060       <manvolnum>1</manvolnum></citerefentry>,
1061
1062       <citerefentry><refentrytitle>ltdbtool</refentrytitle>
1063       <manvolnum>1</manvolnum></citerefentry>,
1064
1065       <citerefentry><refentrytitle>onnode</refentrytitle>
1066       <manvolnum>1</manvolnum></citerefentry>,
1067
1068       <citerefentry><refentrytitle>ping_pong</refentrytitle>
1069       <manvolnum>1</manvolnum></citerefentry>,
1070
1071       <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
1072       <manvolnum>5</manvolnum></citerefentry>,
1073
1074       <citerefentry><refentrytitle>ctdb-statistics</refentrytitle>
1075       <manvolnum>7</manvolnum></citerefentry>,
1076
1077       <citerefentry><refentrytitle>ctdb-tunables</refentrytitle>
1078       <manvolnum>7</manvolnum></citerefentry>,
1079
1080       <ulink url="http://ctdb.samba.org/"/>
1081     </para>
1082   </refsect1>
1083
1084   <refentryinfo>
1085     <author>
1086       <contrib>
1087         This documentation was written by
1088         Ronnie Sahlberg,
1089         Amitay Isaacs,
1090         Martin Schwenke
1091       </contrib>
1092     </author>
1093
1094     <copyright>
1095       <year>2007</year>
1096       <holder>Andrew Tridgell</holder>
1097       <holder>Ronnie Sahlberg</holder>
1098     </copyright>
1099     <legalnotice>
1100       <para>
1101         This program is free software; you can redistribute it and/or
1102         modify it under the terms of the GNU General Public License as
1103         published by the Free Software Foundation; either version 3 of
1104         the License, or (at your option) any later version.
1105       </para>
1106       <para>
1107         This program is distributed in the hope that it will be
1108         useful, but WITHOUT ANY WARRANTY; without even the implied
1109         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1110         PURPOSE.  See the GNU General Public License for more details.
1111       </para>
1112       <para>
1113         You should have received a copy of the GNU General Public
1114         License along with this program; if not, see
1115         <ulink url="http://www.gnu.org/licenses"/>.
1116       </para>
1117     </legalnotice>
1118   </refentryinfo>
1119
1120 </refentry>