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