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>ENVIRONMENT</title>
 238
 239     <variablelist>
 240       <varlistentry><term><envar>CTDB_BASE</envar></term>
 241         <listitem>
 242           <para>
 243             Directory containing CTDB configuration files.  The
 244             default is <filename>/usr/local/etc/ctdb</filename>.
 245           </para>
 246         </listitem>
 247       </varlistentry>
 248
 249     </variablelist>
 250   </refsect1>
 251
 252   <refsect1>
 253     <title>FILES</title>
 254
 255     <variablelist>
 256       <varlistentry><term><filename>/usr/local/etc/ctdb/nodes</filename></term>
 257         <listitem>
 258           <para>
 259             Default file containing a list of each node's IP address
 260             or hostname.
 261           </para>
 262           <para>
 263             As above, a file specified via the <option>-f</option>
 264             is given precedence.  If a
 265             relative path is specified and no corresponding file
 266             exists relative to the current directory then the file is
 267             also searched for in the <filename>$CTDB_BASE</filename>
 268             directory.
 269           </para>
 270           <para>
 271             Otherwise the default is
 272             <filename>/usr/local/etc/ctdb/nodes</filename>.
 273           </para>
 274         </listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term><filename>/usr/local/etc/ctdb/onnode.conf</filename></term>
 279         <listitem>
 280           <para>
 281             If this file exists it is sourced by onnode.  The main
 282             purpose is to allow the administrator to set
 283             <envar>ONNODE_SSH</envar> to something other than "ssh".
 284             In this case the -t option is ignored.
 285           </para>
 286         </listitem>
 287       </varlistentry>
 288     </variablelist>
 289   </refsect1>
 290
 291   <refsect1>
 292     <title>SEE ALSO</title>
 293
 294     <para>
 295       <citerefentry><refentrytitle>ctdb</refentrytitle>
 296       <manvolnum>7</manvolnum></citerefentry>,
 297
 298       <ulink url="http://ctdb.samba.org/"/>
 299     </para>
 300   </refsect1>
 301
 302   <refentryinfo>
 303     <author>
 304       <contrib>
 305         This documentation was written by
 306         Andrew Tridgell,
 307         Martin Schwenke
 308       </contrib>
 309     </author>
 310
 311     <copyright>
 312       <year>2007</year>
 313       <holder>Andrew Tridgell</holder>
 314       <holder>Ronnie Sahlberg</holder>
 315     </copyright>
 316     <copyright>
 317       <year>2008</year>
 318       <holder>Martin Schwenke</holder>
 319     </copyright>
 320     <legalnotice>
 321       <para>
 322         This program is free software; you can redistribute it and/or
 323         modify it under the terms of the GNU General Public License as
 324         published by the Free Software Foundation; either version 3 of
 325         the License, or (at your option) any later version.
 326       </para>
 327       <para>
 328         This program is distributed in the hope that it will be
 329         useful, but WITHOUT ANY WARRANTY; without even the implied
 330         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 331         PURPOSE.  See the GNU General Public License for more details.
 332       </para>
 333       <para>
 334         You should have received a copy of the GNU General Public
 335         License along with this program; if not, see
 336         <ulink url="http://www.gnu.org/licenses"/>.
 337       </para>
 338     </legalnotice>
 339   </refentryinfo>
 340
 341 </refentry>