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             environment variable.  See the discussion of
  65             <filename>/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>SSH</envar> is set
  78             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       <varlistentry><term>lvs | lvsmaster</term>
 200         <listitem>
 201           <para>
 202             The current LVS master.
 203           </para>
 204         </listitem>
 205       </varlistentry>
 206       <varlistentry><term>natgw | natgwlist</term>
 207         <listitem>
 208           <para>
 209             The current NAT gateway.
 210           </para>
 211         </listitem>
 212       </varlistentry>
 213       <varlistentry><term>rm | recmaster</term>
 214         <listitem>
 215           <para>
 216             The current recovery master.
 217           </para>
 218         </listitem>
 219       </varlistentry>
 220     </variablelist>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>EXAMPLES</title>
 225
 226     <para>
 227       The following command would show the process ID of ctdbd on all nodes
 228     </para>
 229     <screen format="linespecific">
 230       onnode all ctdb getpid
 231     </screen>
 232
 233     <para>
 234       The following command would show the last 5 lines of log on each
 235       node, preceded by the node's hostname
 236     </para>
 237     <screen format="linespecific">
 238       onnode all "hostname; tail -5 /var/log/log.ctdb"
 239     </screen>
 240
 241     <para>
 242       The following command would restart the ctdb service on all
 243       nodes, in parallel.
 244     </para>
 245     <screen format="linespecific">
 246       onnode -p all service ctdb restart
 247     </screen>
 248
 249     <para>
 250       The following command would run ./foo in the current working
 251       directory, in parallel, on nodes 0, 2, 3 and 4.
 252     </para>
 253     <screen format="linespecific">
 254       onnode -c -p 0,2-4 ./foo
 255     </screen>
 256   </refsect1>
 257
 258   <refsect1>
 259     <title>ENVIRONMENT</title>
 260
 261     <variablelist>
 262       <varlistentry><term><envar>CTDB_BASE</envar></term>
 263         <listitem>
 264           <para>
 265             Directory containing CTDB configuration files.  The
 266             default is <filename>/etc/ctdb</filename>.
 267           </para>
 268         </listitem>
 269       </varlistentry>
 270
 271       <varlistentry><term><envar>CTDB_NODES_FILE</envar></term>
 272         <listitem>
 273           <para>
 274             Name of alternative nodes file to use instead of the
 275             default.  See the <citetitle>FILES</citetitle> section for
 276             more details.
 277           </para>
 278         </listitem>
 279       </varlistentry>
 280
 281     </variablelist>
 282   </refsect1>
 283
 284   <refsect1>
 285     <title>FILES</title>
 286
 287     <variablelist>
 288       <varlistentry><term><filename>/etc/ctdb/nodes</filename></term>
 289         <listitem>
 290           <para>
 291             Default file containing a list of each node's IP address
 292             or hostname.
 293           </para>
 294           <para>
 295             Actually, the default is
 296             <filename>$CTDB_BASE/nodes</filename>, where
 297             <envar>CTDB_BASE</envar> defaults to
 298             <filename>/etc/ctdb</filename>.  If a relative path is
 299             given (via the -f option or <envar>CTDB_BASE</envar>) and
 300             no corresponding file exists relative to the current
 301             directory then the file is also searched for in the
 302             <filename>$CTDB_BASE</filename> directory.
 303           </para>
 304         </listitem>
 305       </varlistentry>
 306
 307       <varlistentry><term><filename>/etc/ctdb/onnode.conf</filename></term>
 308         <listitem>
 309           <para>
 310             If this file exists it is sourced by onnode.  The main
 311             purpose is to allow the administrator to set
 312             <envar>SSH</envar> to something other than "ssh".  In this
 313             case the -t option is ignored.  For example, the
 314             administrator may choose to use use rsh instead of ssh.
 315           </para>
 316         </listitem>
 317       </varlistentry>
 318     </variablelist>
 319   </refsect1>
 320
 321   <refsect1>
 322     <title>SEE ALSO</title>
 323
 324     <para>
 325       <citerefentry><refentrytitle>ctdb</refentrytitle>
 326       <manvolnum>7</manvolnum></citerefentry>,
 327
 328       <ulink url="http://ctdb.samba.org/"/>
 329     </para>
 330   </refsect1>
 331
 332   <refentryinfo>
 333     <author>
 334       <contrib>
 335         This documentation was written by
 336         Andrew Tridgell,
 337         Martin Schwenke
 338       </contrib>
 339     </author>
 340
 341     <copyright>
 342       <year>2007</year>
 343       <holder>Andrew Tridgell</holder>
 344       <holder>Ronnie Sahlberg</holder>
 345     </copyright>
 346     <copyright>
 347       <year>2008</year>
 348       <holder>Martin Schwenke</holder>
 349     </copyright>
 350     <legalnotice>
 351       <para>
 352         This program is free software; you can redistribute it and/or
 353         modify it under the terms of the GNU General Public License as
 354         published by the Free Software Foundation; either version 3 of
 355         the License, or (at your option) any later version.
 356       </para>
 357       <para>
 358         This program is distributed in the hope that it will be
 359         useful, but WITHOUT ANY WARRANTY; without even the implied
 360         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 361         PURPOSE.  See the GNU General Public License for more details.
 362       </para>
 363       <para>
 364         You should have received a copy of the GNU General Public
 365         License along with this program; if not, see
 366         <ulink url="http://www.gnu.org/licenses"/>.
 367       </para>
 368     </legalnotice>
 369   </refentryinfo>
 370
 371 </refentry>