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>-p</term>
  94         <listitem>
  95           <para>
  96             Run COMMAND in parallel on the specified nodes.  The
  97             default is to run COMMAND sequentially on each node.
  98           </para>
  99         </listitem>
 100       </varlistentry>
 101
 102       <varlistentry><term>-P</term>
 103         <listitem>
 104           <para>
 105             Push files to nodes.  Names of files to push are specified
 106             rather than the usual command.  Quoting is fragile/broken
 107             - filenames with whitespace in them are not supported.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry><term>-q</term>
 113         <listitem>
 114           <para>
 115             Do not print node addresses.  Normally, onnode prints
 116             informational node addresses if more than one node is
 117             specified.  This overrides -v.
 118           </para>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry><term>-v</term>
 123         <listitem>
 124           <para>
 125             Print node addresses even if only one node is specified.
 126             Normally, onnode prints informational node addresses when
 127             more than one node is specified.
 128           </para>
 129         </listitem>
 130       </varlistentry>
 131
 132       <varlistentry><term>-h, --help</term>
 133         <listitem>
 134           <para>
 135             Show a short usage guide.
 136           </para>
 137         </listitem>
 138       </varlistentry>
 139     </variablelist>
 140   </refsect1>
 141
 142   <refsect1>
 143     <title>NODES SPECIFICATION</title>
 144
 145     <para>
 146       Nodes can be specified via numeric node numbers (from 0 to N-1)
 147       or mnemonics.  Multiple nodes are specified using lists of
 148       nodes, separated by commas, and ranges of numeric node numbers,
 149       separated by dashes.  If nodes are specified multiple times then
 150       the command will be executed multiple times on those nodes.  The
 151       order of nodes is significant.
 152     </para>
 153
 154     <para>
 155       The following mnemonics are available:
 156     </para>
 157
 158     <variablelist>
 159       <varlistentry><term>all</term>
 160         <listitem>
 161           <para>
 162             All nodes.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry><term>any</term>
 167         <listitem>
 168           <para>
 169              A node where ctdbd is running.  This semi-random but
 170              there is a bias towards choosing a low numbered node.
 171           </para>
 172         </listitem>
 173       </varlistentry>
 174       <varlistentry><term>ok | healthy</term>
 175         <listitem>
 176           <para>
 177             All nodes that are not disconnected, banned, disabled or
 178             unhealthy.
 179           </para>
 180         </listitem>
 181       </varlistentry>
 182       <varlistentry><term>con | connected</term>
 183         <listitem>
 184           <para>
 185             All nodes that are not disconnected.
 186           </para>
 187         </listitem>
 188       </varlistentry>
 189     </variablelist>
 190   </refsect1>
 191
 192   <refsect1>
 193     <title>EXAMPLES</title>
 194
 195     <para>
 196       The following command would show the process ID of ctdbd on all nodes
 197     </para>
 198     <screen format="linespecific">
 199       onnode all ctdb getpid
 200     </screen>
 201
 202     <para>
 203       The following command would show the last 5 lines of log on each
 204       node, preceded by the node's hostname
 205     </para>
 206     <screen format="linespecific">
 207       onnode all "hostname; tail -5 /usr/local/var/log/log.ctdb"
 208     </screen>
 209
 210     <para>
 211       The following command would restart the ctdb service on all
 212       nodes, in parallel.
 213     </para>
 214     <screen format="linespecific">
 215       onnode -p all service ctdb restart
 216     </screen>
 217
 218     <para>
 219       The following command would run ./foo in the current working
 220       directory, in parallel, on nodes 0, 2, 3 and 4.
 221     </para>
 222     <screen format="linespecific">
 223       onnode -c -p 0,2-4 ./foo
 224     </screen>
 225   </refsect1>
 226
 227   <refsect1>
 228     <title>FILES</title>
 229
 230     <variablelist>
 231       <varlistentry><term><filename>/usr/local/etc/ctdb/nodes</filename></term>
 232         <listitem>
 233           <para>
 234             Default file containing a list of each node's IP address
 235             or hostname.
 236           </para>
 237           <para>
 238             As above, a file specified via the <option>-f</option>
 239             is given precedence.  If a
 240             relative path is specified and no corresponding file
 241             exists relative to the current directory then the file is
 242             also searched for in the CTDB configuration directory.
 243           </para>
 244           <para>
 245             Otherwise the default is
 246             <filename>/usr/local/etc/ctdb/nodes</filename>.
 247           </para>
 248         </listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term><filename>/usr/local/etc/ctdb/onnode.conf</filename></term>
 253         <listitem>
 254           <para>
 255             If this file exists it is sourced by onnode.  The main
 256             purpose is to allow the administrator to set
 257             <envar>ONNODE_SSH</envar> to something other than "ssh".
 258             In this case the -t option is ignored.
 259           </para>
 260         </listitem>
 261       </varlistentry>
 262     </variablelist>
 263   </refsect1>
 264
 265   <refsect1>
 266     <title>SEE ALSO</title>
 267
 268     <para>
 269       <citerefentry><refentrytitle>ctdb</refentrytitle>
 270       <manvolnum>7</manvolnum></citerefentry>,
 271
 272       <ulink url="http://ctdb.samba.org/"/>
 273     </para>
 274   </refsect1>
 275
 276   <refentryinfo>
 277     <author>
 278       <contrib>
 279         This documentation was written by
 280         Andrew Tridgell,
 281         Martin Schwenke
 282       </contrib>
 283     </author>
 284
 285     <copyright>
 286       <year>2007</year>
 287       <holder>Andrew Tridgell</holder>
 288       <holder>Ronnie Sahlberg</holder>
 289     </copyright>
 290     <copyright>
 291       <year>2008</year>
 292       <holder>Martin Schwenke</holder>
 293     </copyright>
 294     <legalnotice>
 295       <para>
 296         This program is free software; you can redistribute it and/or
 297         modify it under the terms of the GNU General Public License as
 298         published by the Free Software Foundation; either version 3 of
 299         the License, or (at your option) any later version.
 300       </para>
 301       <para>
 302         This program is distributed in the hope that it will be
 303         useful, but WITHOUT ANY WARRANTY; without even the implied
 304         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 305         PURPOSE.  See the GNU General Public License for more details.
 306       </para>
 307       <para>
 308         You should have received a copy of the GNU General Public
 309         License along with this program; if not, see
 310         <ulink url="http://www.gnu.org/licenses"/>.
 311       </para>
 312     </legalnotice>
 313   </refentryinfo>
 314
 315 </refentry>