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