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