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>