update lib/replace from samba4
[vlendec/samba-autobuild/.git] / ctdb / 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 invalid 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 3 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>