doc/ctdb.1.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="ctdb.1">
   4
   5 <refmeta>
   6         <refentrytitle>ctdb</refentrytitle>
   7         <manvolnum>1</manvolnum>
   8 </refmeta>
   9
  10
  11 <refnamediv>
  12         <refname>ctdb</refname>
  13         <refpurpose>clustered tdb database management utility</refpurpose>
  14 </refnamediv>
  15
  16 <refsynopsisdiv>
  17         <cmdsynopsis>
  18                 <command>ctdb [ OPTIONS ] COMMAND ...</command>
  19         </cmdsynopsis>
  20
  21         <cmdsynopsis>
  22                 <command>ctdb</command>
  23                 <arg choice="opt">-n &lt;node&gt;</arg>
  24                 <arg choice="opt">-Y</arg>
  25                 <arg choice="opt">-t &lt;timeout&gt;</arg>
  26                 <arg choice="opt">-? --help</arg>
  27                 <arg choice="opt">--usage</arg>
  28                 <arg choice="opt">-d --debug=&lt;INTEGER&gt;</arg>
  29                 <arg choice="opt">--socket=&lt;filename&gt;</arg>
  30         </cmdsynopsis>
  31
  32 </refsynopsisdiv>
  33
  34   <refsect1><title>DESCRIPTION</title>
  35     <para>
  36       ctdb is a utility to view and manage a ctdb cluster.
  37     </para>
  38   </refsect1>
  39
  40
  41   <refsect1>
  42     <title>OPTIONS</title>
  43
  44     <variablelist>
  45       <varlistentry><term>-n &lt;node&gt;</term>
  46         <listitem>
  47           <para>
  48             This specifies on which node to execute the command. Default is
  49             to run the command on the deamon running on the local host.
  50           </para>
  51         </listitem>
  52       </varlistentry>
  53
  54       <varlistentry><term>-Y</term>
  55         <listitem>
  56           <para>
  57             Produce output in machinereadable form for easier parsing by scripts. Not all commands support this option.
  58           </para>
  59         </listitem>
  60       </varlistentry>
  61
  62       <varlistentry><term>-t &lt;timeout&gt;</term>
  63         <listitem>
  64           <para>
  65             How long should ctdb wait for a command to complete before timing out. Default is 3 seconds.
  66           </para>
  67         </listitem>
  68       </varlistentry>
  69
  70       <varlistentry><term>-? --help</term>
  71         <listitem>
  72           <para>
  73             Print some help text to the screen.
  74           </para>
  75         </listitem>
  76       </varlistentry>
  77
  78       <varlistentry><term>--usage</term>
  79         <listitem>
  80           <para>
  81             Print useage information to the screen.
  82           </para>
  83         </listitem>
  84       </varlistentry>
  85
  86       <varlistentry><term>-d --debug=&lt;debuglevel&gt;</term>
  87         <listitem>
  88           <para>
  89             Change the debug level for the command. Default is 0.
  90           </para>
  91         </listitem>
  92       </varlistentry>
  93
  94       <varlistentry><term>--socket=&lt;filename&gt;</term>
  95         <listitem>
  96           <para>
  97             Specify the socketname to use when connecting to the local ctdb
  98             daemon. The default is /tmp/ctdb.socket .
  99           </para>
 100           <para>
 101             You only need to specify this parameter if you run multiple ctdb
 102             daemons on the same physical host and thus can not use the default
 103             name for the domain socket.
 104           </para>
 105         </listitem>
 106       </varlistentry>
 107
 108     </variablelist>
 109   </refsect1>
 110
 111
 112   <refsect1><title>Administrative Commands</title>
 113     <para>
 114       These are commands used to monitor and administrate a CTDB cluster.
 115     </para>
 116
 117     <refsect2><title>status</title>
 118       <para>
 119         This command shows the current status of the ctdb node.
 120       </para>
 121
 122       <refsect3><title>node status</title>
 123         <para>
 124           Node status reflects the current status of the node. There are four possible states:
 125         </para>
 126         <para>
 127           OK - This node is fully functional.
 128         </para>
 129         <para>
 130           DISCONNECTED - This node could not be connected through the network and is currently not parcipitating in the cluster. If there is a public IP address associated with this node it should have been taken over by a different node. No services are running on this node.
 131         </para>
 132         <para>
 133           DISABLED - This node has been administratively disabled. This node is still functional and participates in the CTDB cluster but its IP addresses have been taken over by a different node and no services are currently being hosted.
 134         </para>
 135         <para>
 136           UNHEALTHY - A service provided by this node is malfunctioning and should be investigated. The CTDB daemon itself is operational and participates in the cluster. Its public IP address has been taken over by a different node and no services are currnetly being hosted. All unhealthy nodes should be investigated and require an administrative action to rectify.
 137         </para>
 138         <para>
 139           BANNED - This node failed too many recovery attempts and has been banned from participating in the cluster for a period of RecoveryBanPeriod seconds. Any public IP address has been taken over by other nodes. This node does not provide any services. All banned nodes should be investigated and require an administrative action to rectify. This node does not perticipate in the CTDB cluster but can still be communicated with. I.e. ctdb commands can be sent to it.
 140         </para>
 141       </refsect3>
 142
 143       <refsect3><title>generation</title>
 144         <para>
 145           The generation id is a number that indicates the current generation
 146           of a cluster instance. Each time a cluster goes through a
 147           reconfiguration or a recovery its generation id will be changed.
 148         </para>
 149       </refsect3>
 150
 151       <refsect3><title>VNNMAP</title>
 152         <para>
 153           The list of Virtual Node Numbers. This is a list of all nodes that actively participates in the cluster and that share the workload of hosting the Clustered TDB database records.
 154           Only nodes that are parcipitating in the vnnmap can become lmaster or dmaster for a database record.
 155         </para>
 156       </refsect3>
 157
 158       <refsect3><title>Recovery mode</title>
 159         <para>
 160           This is the current recovery mode of the cluster. There are two possible modes:
 161         </para>
 162         <para>
 163           NORMAL - The cluster is fully operational.
 164         </para>
 165         <para>
 166           RECOVERY - The cluster databases have all been frozen, pausing all services while the cluster awaits a recovery process to complete. A recovery process should finish within seconds. If a cluster is stuck in the RECOVERY state this would indicate a cluster malfunction which needs to be investigated.
 167         </para>
 168       </refsect3>
 169
 170       <refsect3><title>Recovery master</title>
 171         <para>
 172           This is the cluster node that is currently designated as the recovery master. This node is responsible of monitoring the consistency of the cluster and to perform the actual recovery process when reqired.
 173         </para>
 174       </refsect3>
 175
 176       <para>
 177         Example: ctdb status
 178       </para>
 179       <para>Example output:</para>
 180       <screen format="linespecific">
 181 Number of nodes:4
 182 vnn:0 11.1.2.200       OK (THIS NODE)
 183 vnn:1 11.1.2.201       OK
 184 vnn:2 11.1.2.202       OK
 185 vnn:3 11.1.2.203       OK
 186 Generation:1362079228
 187 Size:4
 188 hash:0 lmaster:0
 189 hash:1 lmaster:1
 190 hash:2 lmaster:2
 191 hash:3 lmaster:3
 192 Recovery mode:NORMAL (0)
 193 Recovery master:0
 194       </screen>
 195     </refsect2>
 196
 197     <refsect2><title>ping</title>
 198       <para>
 199         This command will "ping" all CTDB daemons in the cluster to verify that they are processing commands correctly.
 200       </para>
 201       <para>
 202         Example: ctdb ping
 203       </para>
 204       <para>
 205         Example output:
 206       </para>
 207       <screen format="linespecific">
 208 response from 0 time=0.000054 sec  (3 clients)
 209 response from 1 time=0.000144 sec  (2 clients)
 210 response from 2 time=0.000105 sec  (2 clients)
 211 response from 3 time=0.000114 sec  (2 clients)
 212       </screen>
 213     </refsect2>
 214
 215     <refsect2><title>ip</title>
 216       <para>
 217         This command will display the list of public addresses that are provided by the cluster and which physical node is currently serving this ip.
 218       </para>
 219       <para>
 220         Example: ctdb ip
 221       </para>
 222       <para>
 223         Example output:
 224       </para>
 225       <screen format="linespecific">
 226 Number of nodes:4
 227 12.1.1.1         0
 228 12.1.1.2         1
 229 12.1.1.3         2
 230 12.1.1.4         3
 231       </screen>
 232     </refsect2>
 233
 234     <refsect2><title>getvar &lt;name&gt;</title>
 235       <para>
 236         Get the runtime value of a tuneable variable.
 237       </para>
 238       <para>
 239         Example: ctdb getvar MaxRedirectCount
 240       </para>
 241       <para>
 242         Example output:
 243       </para>
 244       <screen format="linespecific">
 245 MaxRedirectCount    = 3
 246       </screen>
 247     </refsect2>
 248
 249     <refsect2><title>setvar &lt;name&gt; &lt;value&gt;</title>
 250       <para>
 251         Set the runtime value of a tuneable variable.
 252       </para>
 253       <para>
 254         Example: ctdb setvar MaxRedirectCount 5
 255       </para>
 256     </refsect2>
 257
 258     <refsect2><title>listvars</title>
 259       <para>
 260         List all tuneable variables.
 261       </para>
 262       <para>
 263         Example: ctdb listvars
 264       </para>
 265       <para>
 266         Example output:
 267       </para>
 268       <screen format="linespecific">
 269 MaxRedirectCount    = 5
 270 SeqnumFrequency     = 1
 271 ControlTimeout      = 60
 272 TraverseTimeout     = 20
 273 KeepaliveInterval   = 2
 274 KeepaliveLimit      = 3
 275 MaxLACount          = 7
 276 RecoverTimeout      = 5
 277 RecoverInterval     = 1
 278 ElectionTimeout     = 3
 279 TakeoverTimeout     = 5
 280 MonitorInterval     = 15
 281 EventScriptTimeout  = 20
 282 RecoveryGracePeriod = 60
 283 RecoveryBanPeriod   = 300
 284       </screen>
 285     </refsect2>
 286
 287     <refsect2><title>statistics</title>
 288       <para>
 289         Collect statistics from the CTDB daemon about how many calls it has served.
 290       </para>
 291       <para>
 292         Example: ctdb statistics
 293       </para>
 294       <para>
 295         Example output:
 296       </para>
 297       <screen format="linespecific">
 298 CTDB version 1
 299  num_clients                        3
 300  frozen                             0
 301  recovering                         0
 302  client_packets_sent           360489
 303  client_packets_recv           360466
 304  node_packets_sent             480931
 305  node_packets_recv             240120
 306  keepalive_packets_sent             4
 307  keepalive_packets_recv             3
 308  node
 309      req_call                       2
 310      reply_call                     2
 311      req_dmaster                    0
 312      reply_dmaster                  0
 313      reply_error                    0
 314      req_message                   42
 315      req_control               120408
 316      reply_control             360439
 317  client
 318      req_call                       2
 319      req_message                   24
 320      req_control               360440
 321  timeouts
 322      call                           0
 323      control                        0
 324      traverse                       0
 325  total_calls                        2
 326  pending_calls                      0
 327  lockwait_calls                     0
 328  pending_lockwait_calls             0
 329  memory_used                     5040
 330  max_hop_count                      0
 331  max_call_latency                   4.948321 sec
 332  max_lockwait_latency               0.000000 sec
 333       </screen>
 334     </refsect2>
 335
 336     <refsect2><title>statisticsreset</title>
 337       <para>
 338         This command is used to clear all statistics counters in a node.
 339       </para>
 340       <para>
 341         Example: ctdb statisticsreset
 342       </para>
 343     </refsect2>
 344
 345     <refsect2><title>getdebug</title>
 346       <para>
 347         Get the current debug level for the node. the debug level controls what information is written to the log file.
 348       </para>
 349     </refsect2>
 350
 351     <refsect2><title>setdebug &lt;debuglevel&gt;</title>
 352       <para>
 353         Set the debug level of a node. This is a number between 0 and 9 and controls what information will be written to the logfile.
 354       </para>
 355     </refsect2>
 356
 357     <refsect2><title>getpid</title>
 358       <para>
 359         This command will return the process id of the ctdb daemon.
 360       </para>
 361     </refsect2>
 362
 363     <refsect2><title>disable</title>
 364       <para>
 365         This command is used to administratively disable a node in the cluster.
 366         A disabled node will still participate in the cluster and host
 367         clustered TDB records but its public ip address has been taken over by
 368         a different node and it no longer hosts any services.
 369       </para>
 370     </refsect2>
 371
 372     <refsect2><title>enable</title>
 373       <para>
 374         Re-enable a node that has been administratively disabled.
 375       </para>
 376     </refsect2>
 377
 378     <refsect2><title>ban &lt;bantime|0&gt;</title>
 379       <para>
 380         Administratively ban a node for bantime seconds. A bantime of 0 means that the node should be permanently banned.
 381       </para>
 382       <para>
 383         A banned node does not participate in the cluster and does not host any records for the clustered TDB. Its ip address has been taken over by an other node and no services are hosted.
 384       </para>
 385       <para>
 386         Nodes are automatically banned if they are the cause of too many
 387         cluster recoveries.
 388       </para>
 389     </refsect2>
 390
 391     <refsect2><title>unban</title>
 392       <para>
 393         This command is used to unban a node that has either been
 394         administratively banned using the ban command or has been automatically
 395         banned by the recovery daemon.
 396       </para>
 397     </refsect2>
 398
 399     <refsect2><title>shutdown</title>
 400       <para>
 401         This command will shutdown a specific CTDB daemon.
 402       </para>
 403     </refsect2>
 404
 405     <refsect2><title>recover</title>
 406       <para>
 407         This command will trigger the recovery daemon to do a cluster
 408         recovery.
 409       </para>
 410     </refsect2>
 411
 412     <refsect2><title>killtcp &lt;srcip:port&gt; &lt;dstip:port&gt;</title>
 413       <para>
 414         This command will kill the specified TCP connection by issuing a
 415         TCP RST to the srcip:port endpoint.
 416       </para>
 417     </refsect2>
 418
 419     <refsect2><title>tickle &lt;srcip:port&gt; &lt;dstip:port&gt;</title>
 420       <para>
 421         This command will will send a TCP tickle to the source host for the
 422         specified TCP connection.
 423         A TCP tickle is a TCP ACK packet with an invalis sequence and
 424         acknowledge number and will when received by the source host result
 425         in it sending an immediate correct ACK back to the other end.
 426       </para>
 427       <para>
 428         TCP tickles are useful to "tickle" clients after a ip failover has
 429         occured since this will make the client immediately recognize the
 430         tcp connection has been disrupted and that the client will need
 431         to reestablish. This greatly speeds up the time it takes for a client
 432         to detect and reestablish after an ip failover in the ctdb cluster.
 433       </para>
 434     </refsect2>
 435
 436   </refsect1>
 437
 438
 439   <refsect1><title>Debugging Commands</title>
 440     <para>
 441       These commands are primarily used for CTDB development and testing and
 442       should not be used for normal administration.
 443     </para>
 444     <refsect2><title>process-exists &lt;pid&gt;</title>
 445       <para>
 446         This command checks if a specific process exists on the CTDB host. This is mainly used by Samba to check if remote instances of samba are still running or not.
 447       </para>
 448     </refsect2>
 449
 450     <refsect2><title>getdbmap</title>
 451       <para>
 452         This command lists all clustered TDB databases that the CTDB daemon has attahced to.
 453       </para>
 454       <para>
 455         Example: ctdb getdbmap
 456       </para>
 457       <para>
 458         Example output:
 459       </para>
 460       <screen format="linespecific">
 461 Number of databases:4
 462 dbid:0x42fe72c5 name:locking.tdb path:/var/ctdb/locking.tdb.0
 463 dbid:0x1421fb78 name:brlock.tdb path:/var/ctdb/brlock.tdb.0
 464 dbid:0x17055d90 name:connections.tdb path:/var/ctdb/connections.tdb.0
 465 dbid:0xc0bdde6a name:sessionid.tdb path:/var/ctdb/sessionid.tdb.0
 466       </screen>
 467     </refsect2>
 468
 469     <refsect2><title>catdb &lt;dbname&gt;</title>
 470       <para>
 471         This command will dump a clustered TDB database to the screen. This is a debugging command.
 472       </para>
 473     </refsect2>
 474
 475     <refsect2><title>getmonmode</title>
 476       <para>
 477         This command returns the monutoring mode of a node. The monitoring mode is either ACTIVE or DISABLED. Normally a node will continously monitor that all other nodes that are expected are in fact connected and that they respond to commands.
 478       </para>
 479       <para>
 480         ACTIVE - This is the normal mode. The node is actively monitoring all other nodes, both that the transport is connected and also that the node responds to commands. If a node becomes unavailable, it will be marked as DISCONNECTED and a recovery is initiated to restore the cluster.
 481       </para>
 482       <para>
 483         DISABLED - This node is not monitoring that other nodes are available. In this mode a node failure will not be detected and no recovery will be performed. This mode is useful when for debugging purposes one wants to attach GDB to a ctdb process but wants to prevent the rest of the cluster from marking this node as DISCONNECTED and do a recovery.
 484       </para>
 485     </refsect2>
 486
 487
 488     <refsect2><title>setmonmode &lt;0|1&gt;</title>
 489       <para>
 490         This command can be used to explicitely disable/enable monitoring mode on a node. The main purpose is if one wants to attach GDB to a running ctdb daemon but wants to prevent the other nodes from marking it as DISCONNECTED and issuing a recovery. To do this, set monitoring mode to 0 on all nodes before attaching with GDB. Remember to set monitoring mode back to 1 afterwards.
 491       </para>
 492     </refsect2>
 493
 494     <refsect2><title>attach &lt;dbname&gt;</title>
 495       <para>
 496         This is a debugging command. This command will make the CTDB daemon create a new CTDB database and attach to it.
 497       </para>
 498     </refsect2>
 499
 500     <refsect2><title>dumpmemory</title>
 501       <para>
 502         This is a debugging command. This command will make the ctdb daemon to write a fill memory allocation map to the log file.
 503       </para>
 504     </refsect2>
 505
 506     <refsect2><title>freeze</title>
 507       <para>
 508         This command will lock all the local TDB databases causing clients
 509         that are accessing these TDBs such as samba3 to block until the
 510         databases are thawed.
 511       </para>
 512       <para>
 513         This is primarily used by the recovery daemon to stop all samba
 514         daemons from accessing any databases while the database is recovered
 515         and rebuilt.
 516       </para>
 517     </refsect2>
 518
 519     <refsect2><title>thaw</title>
 520       <para>
 521         Thaw a previously frozen node.
 522       </para>
 523     </refsect2>
 524
 525   </refsect1>
 526
 527
 528   <refsect1><title>SEE ALSO</title>
 529     <para>
 530       ctdbd(1), onnode(1)
 531       <ulink url="http://ctdb.samba.org/"/>
 532     </para>
 533   </refsect1>
 534   <refsect1><title>COPYRIGHT/LICENSE</title>
 535 <literallayout>
 536 Copyright (C) Andrew Tridgell 2007
 537 Copyright (C) Ronnie sahlberg 2007
 538
 539 This program is free software; you can redistribute it and/or modify
 540 it under the terms of the GNU General Public License as published by
 541 the Free Software Foundation; either version 2 of the License, or (at
 542 your option) any later version.
 543
 544 This program is distributed in the hope that it will be useful, but
 545 WITHOUT ANY WARRANTY; without even the implied warranty of
 546 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 547 General Public License for more details.
 548
 549 You should have received a copy of the GNU General Public License
 550 along with this program; if not, write to the Free Software
 551 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 552 </literallayout>
 553   </refsect1>
 554 </refentry>