pyldb: avoid segfault when adding an element with no name
[vlendec/samba-autobuild/.git] / ctdb / doc / onnode.1.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="onnode.1">
6
7   <refmeta>
8     <refentrytitle>onnode</refentrytitle>
9     <manvolnum>1</manvolnum>
10     <refmiscinfo class="source">ctdb</refmiscinfo>
11     <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
12   </refmeta>
13
14   <refnamediv>
15     <refname>onnode</refname>
16     <refpurpose>run commands on CTDB cluster nodes</refpurpose>
17   </refnamediv>
18
19   <refsynopsisdiv>
20     <cmdsynopsis>
21       <command>onnode</command>
22       <arg rep="repeat"><replaceable>OPTION</replaceable></arg>
23       <arg choice="req"><replaceable>NODES</replaceable></arg>
24       <arg choice="req"><replaceable>COMMAND</replaceable></arg>
25     </cmdsynopsis>
26   </refsynopsisdiv>
27
28   <refsect1>
29     <title>DESCRIPTION</title>
30     <para>
31       onnode is a utility to run commands on a specific node of a CTDB
32       cluster, or on all nodes.
33     </para>
34     <para>
35       <replaceable>NODES</replaceable> specifies which node(s) to run
36       a command on.  See section <citetitle>NODES
37       SPECIFICATION</citetitle> for details.
38     </para>
39     <para>
40       <replaceable>COMMAND</replaceable> can be any shell command. The
41       onnode utility uses ssh or rsh to connect to the remote nodes
42       and run the command.
43     </para>
44   </refsect1>
45
46   <refsect1>
47     <title>OPTIONS</title>
48
49     <variablelist>
50       <varlistentry><term>-c</term>
51         <listitem>
52           <para>
53             Execute COMMAND in the current working directory on the
54             specified nodes.
55           </para>
56         </listitem>
57       </varlistentry>
58
59       <varlistentry><term>-f <parameter>FILENAME</parameter></term>
60       <listitem>
61         <para>
62           Specify an alternative nodes FILENAME to use instead of
63           the default.  See the discussion of
64           <filename>/usr/local/etc/ctdb/nodes</filename> in the
65           FILES section for more details.
66           </para>
67       </listitem>
68       </varlistentry>
69
70       <varlistentry><term>-i</term>
71         <listitem>
72           <para>
73             Keep standard input open, allowing data to be piped to
74             onnode.  Normally onnode closes stdin to avoid surprises
75             when scripting.  Note that this option is ignored when
76             using <option>-p</option> or if <envar>ONNODE_SSH</envar>
77             is set to anything other than "ssh".
78           </para>
79         </listitem>
80       </varlistentry>
81
82       <varlistentry><term>-n</term>
83         <listitem>
84           <para>
85             Allow nodes to be specified by name rather than node
86             numbers.  These nodes don't need to be listed in the nodes
87             file.  You can avoid the nodes file entirely by combining
88             this with <code>-f /dev/null</code>.
89           </para>
90         </listitem>
91       </varlistentry>
92
93       <varlistentry><term>-o <parameter>PREFIX</parameter></term>
94         <listitem>
95           <para>
96             Causes standard output from each node to be saved into a
97             file with name PREFIX.<replaceable>IP</replaceable>.
98           </para>
99         </listitem>
100       </varlistentry>
101
102       <varlistentry><term>-p</term>
103         <listitem>
104           <para>
105             Run COMMAND in parallel on the specified nodes.  The
106             default is to run COMMAND sequentially on each node.
107           </para>
108         </listitem>
109       </varlistentry>
110
111       <varlistentry><term>-P</term>
112         <listitem>
113           <para>
114             Push files to nodes.  Names of files to push are specified
115             rather than the usual command.  Quoting is fragile/broken
116             - filenames with whitespace in them are not supported.
117           </para>
118         </listitem>
119       </varlistentry>
120
121       <varlistentry><term>-q</term>
122         <listitem>
123           <para>
124             Do not print node addresses.  Normally, onnode prints
125             informational node addresses if more than one node is
126             specified.  This overrides -v.
127           </para>
128         </listitem>
129       </varlistentry>
130
131       <varlistentry><term>-v</term>
132         <listitem>
133           <para>
134             Print node addresses even if only one node is specified.
135             Normally, onnode prints informational node addresses when
136             more than one node is specified.
137           </para>
138         </listitem>
139       </varlistentry>
140
141       <varlistentry><term>-h, --help</term>
142         <listitem>
143           <para>
144             Show a short usage guide.
145           </para>
146         </listitem>
147       </varlistentry>
148     </variablelist>
149   </refsect1>
150
151   <refsect1>
152     <title>NODES SPECIFICATION</title>
153
154     <para>
155       Nodes can be specified via numeric node numbers (from 0 to N-1)
156       or mnemonics.  Multiple nodes are specified using lists of
157       nodes, separated by commas, and ranges of numeric node numbers,
158       separated by dashes.  If nodes are specified multiple times then
159       the command will be executed multiple times on those nodes.  The
160       order of nodes is significant.
161     </para>
162
163     <para>
164       The following mnemonics are available:
165     </para>
166
167     <variablelist>
168       <varlistentry><term>all</term>
169         <listitem>
170           <para>
171             All nodes.
172           </para>
173         </listitem>
174       </varlistentry>
175       <varlistentry><term>any</term>
176         <listitem>
177           <para>
178              A node where ctdbd is running.  This semi-random but
179              there is a bias towards choosing a low numbered node.
180           </para>
181         </listitem>
182       </varlistentry>
183       <varlistentry><term>ok | healthy</term>
184         <listitem>
185           <para>
186             All nodes that are not disconnected, banned, disabled or
187             unhealthy.
188           </para>
189         </listitem>
190       </varlistentry>
191       <varlistentry><term>con | connected</term>
192         <listitem>
193           <para>
194             All nodes that are not disconnected.
195           </para>
196         </listitem>
197       </varlistentry>
198     </variablelist>
199   </refsect1>
200
201   <refsect1>
202     <title>EXAMPLES</title>
203
204     <para>
205       The following command would show the process ID of ctdbd on all nodes
206     </para>
207     <screen format="linespecific">
208       onnode all ctdb getpid
209     </screen>
210
211     <para>
212       The following command would show the last 5 lines of log on each
213       node, preceded by the node's hostname
214     </para>
215     <screen format="linespecific">
216       onnode all "hostname; tail -5 /usr/local/var/log/log.ctdb"
217     </screen>
218
219     <para>
220       The following command would restart the ctdb service on all
221       nodes, in parallel.
222     </para>
223     <screen format="linespecific">
224       onnode -p all service ctdb restart
225     </screen>
226
227     <para>
228       The following command would run ./foo in the current working
229       directory, in parallel, on nodes 0, 2, 3 and 4.
230     </para>
231     <screen format="linespecific">
232       onnode -c -p 0,2-4 ./foo
233     </screen>
234   </refsect1>
235
236   <refsect1>
237     <title>FILES</title>
238
239     <variablelist>
240       <varlistentry><term><filename>/usr/local/etc/ctdb/nodes</filename></term>
241         <listitem>
242           <para>
243             Default file containing a list of each node's IP address
244             or hostname.
245           </para>
246           <para>
247             As above, a file specified via the <option>-f</option>
248             is given precedence.  If a
249             relative path is specified and no corresponding file
250             exists relative to the current directory then the file is
251             also searched for in the CTDB configuration directory.
252           </para>
253           <para>
254             Otherwise the default is
255             <filename>/usr/local/etc/ctdb/nodes</filename>.
256           </para>
257         </listitem>
258       </varlistentry>
259
260       <varlistentry>
261         <term><filename>/usr/local/etc/ctdb/onnode.conf</filename></term>
262         <listitem>
263           <para>
264             If this file exists it is sourced by onnode.  The main
265             purpose is to allow the administrator to set
266             <envar>ONNODE_SSH</envar> to something other than "ssh".
267             In this case the -t option is ignored.
268           </para>
269         </listitem>
270       </varlistentry>
271     </variablelist>
272   </refsect1>
273
274   <refsect1>
275     <title>SEE ALSO</title>
276
277     <para>
278       <citerefentry><refentrytitle>ctdb</refentrytitle>
279       <manvolnum>7</manvolnum></citerefentry>,
280
281       <ulink url="http://ctdb.samba.org/"/>
282     </para>
283   </refsect1>
284
285   <refentryinfo>
286     <author>
287       <contrib>
288         This documentation was written by
289         Andrew Tridgell,
290         Martin Schwenke
291       </contrib>
292     </author>
293
294     <copyright>
295       <year>2007</year>
296       <holder>Andrew Tridgell</holder>
297       <holder>Ronnie Sahlberg</holder>
298     </copyright>
299     <copyright>
300       <year>2008</year>
301       <holder>Martin Schwenke</holder>
302     </copyright>
303     <legalnotice>
304       <para>
305         This program is free software; you can redistribute it and/or
306         modify it under the terms of the GNU General Public License as
307         published by the Free Software Foundation; either version 3 of
308         the License, or (at your option) any later version.
309       </para>
310       <para>
311         This program is distributed in the hope that it will be
312         useful, but WITHOUT ANY WARRANTY; without even the implied
313         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
314         PURPOSE.  See the GNU General Public License for more details.
315       </para>
316       <para>
317         You should have received a copy of the GNU General Public
318         License along with this program; if not, see
319         <ulink url="http://www.gnu.org/licenses"/>.
320       </para>
321     </legalnotice>
322   </refentryinfo>
323
324 </refentry>