ctdb/doc/onnode.1.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry
   3         PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <refentry id="onnode.1">
   6
   7 <refmeta>
   8         <refentrytitle>onnode</refentrytitle>
   9         <manvolnum>1</manvolnum>
  10         <refmiscinfo class="source"> </refmiscinfo>
  11         <refmiscinfo class="manual"> </refmiscinfo>
  12 </refmeta>
  13
  14
  15 <refnamediv>
  16         <refname>onnode</refname>
  17         <refpurpose>run commands on ctdb nodes</refpurpose>
  18 </refnamediv>
  19
  20 <refsynopsisdiv>
  21         <cmdsynopsis>
  22                 <command>onnode [OPTION] ... NODES COMMAND ...</command>
  23         </cmdsynopsis>
  24 </refsynopsisdiv>
  25
  26   <refsect1><title>DESCRIPTION</title>
  27     <para>
  28       onnode is a utility to run commands on a specific node of a CTDB
  29       cluster, or on all nodes.
  30     </para>
  31     <para>
  32       The NODES option specifies which node to run a command on.  You
  33       can specify a numeric node number (from 0 to N-1) or a
  34       descriptive node specification (see DESCRIPTIVE NODE
  35       SPECIFICATIONS below).  You can also specify lists of nodes,
  36       separated by commas, and ranges of numeric node numbers,
  37       separated by dashes.  If nodes are specified multiple times then
  38       the command will be executed multiple times on those nodes.  The
  39       order of nodes is significant.
  40     </para>
  41     <para>
  42       The COMMAND can be any shell command. The onnode utility uses
  43       ssh or rsh to connect to the remote nodes and run the command.
  44     </para>
  45   </refsect1>
  46
  47   <refsect1><title>DESCRIPTIVE NODE SPECIFICATIONS</title>
  48
  49     <para>
  50       The following descriptive node specification can be used in
  51       place of numeric node numbers:
  52     </para>
  53
  54     <variablelist>
  55       <varlistentry><term>all</term>
  56         <listitem>
  57           <para>
  58             All nodes.
  59           </para>
  60         </listitem>
  61       </varlistentry>
  62       <varlistentry><term>any</term>
  63         <listitem>
  64           <para>
  65              A node where ctdbd is running.  This semi-random but
  66              there is a bias towards choosing a low numbered node.
  67           </para>
  68         </listitem>
  69       </varlistentry>
  70       <varlistentry><term>ok | healthy</term>
  71         <listitem>
  72           <para>
  73             All nodes that are not disconnected, banned, disabled or
  74             unhealthy.
  75           </para>
  76         </listitem>
  77       </varlistentry>
  78       <varlistentry><term>con | connected</term>
  79         <listitem>
  80           <para>
  81             All nodes that are not disconnected.
  82           </para>
  83         </listitem>
  84       </varlistentry>
  85       <varlistentry><term>lvs | lvsmaster</term>
  86         <listitem>
  87           <para>
  88             The current LVS master.
  89           </para>
  90         </listitem>
  91       </varlistentry>
  92       <varlistentry><term>natgw | natgwlist</term>
  93         <listitem>
  94           <para>
  95             The current NAT gateway.
  96           </para>
  97         </listitem>
  98       </varlistentry>
  99       <varlistentry><term>rm | recmaster</term>
 100         <listitem>
 101           <para>
 102             The current recovery master.
 103           </para>
 104         </listitem>
 105       </varlistentry>
 106     </variablelist>
 107   </refsect1>
 108
 109   <refsect1><title>OPTIONS</title>
 110
 111     <variablelist>
 112       <varlistentry><term>-c</term>
 113         <listitem>
 114           <para>
 115             Execute COMMAND in the current working directory on the
 116             specified nodes.
 117           </para>
 118         </listitem>
 119       </varlistentry>
 120
 121       <varlistentry><term>-o &lt;prefix&gt;</term>
 122         <listitem>
 123           <para>
 124             Causes standard output from each node to be saved into a
 125             file with name &lt;prefix&gt;.&lt;ip&gt;.
 126           </para>
 127         </listitem>
 128       </varlistentry>
 129
 130       <varlistentry><term>-p</term>
 131         <listitem>
 132           <para>
 133             Run COMMAND in parallel on the specified nodes.  The
 134             default is to run COMMAND sequentially on each node.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138
 139       <varlistentry><term>-q</term>
 140         <listitem>
 141           <para>
 142             Do not print node addresses.  Normally, onnode prints
 143             informational node addresses if more than one node is
 144             specified.  This overrides -v.
 145           </para>
 146         </listitem>
 147       </varlistentry>
 148
 149       <varlistentry><term>-n</term>
 150         <listitem>
 151           <para>
 152             Allow nodes to be specified by name rather than node
 153             numbers.  These nodes don't need to be listed in the nodes
 154             file.  You can avoid the nodes file entirely by combining
 155             this with <code>-f /dev/null</code>.
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry><term>-f &lt;file&gt;</term>
 161         <listitem>
 162           <para>
 163             Specify an alternative nodes file to use instead of the
 164             default.  This option overrides the CTDB_NODES_FILE
 165             environment variable.  See the discussion of
 166             <filename>/etc/ctdb/nodes</filename> in the FILES section
 167             for more details.
 168           </para>
 169         </listitem>
 170       </varlistentry>
 171
 172       <varlistentry><term>-v</term>
 173         <listitem>
 174           <para>
 175             Print a node addresses even if only one node is specified.
 176             Normally, onnode prints informational node addresses when
 177             more than one node is specified.
 178           </para>
 179         </listitem>
 180       </varlistentry>
 181
 182       <varlistentry><term>-P</term>
 183         <listitem>
 184           <para>
 185             Push files to nodes.  Names of files to push are specified
 186             rather than the usual command.  Quoting is fragile/broken
 187             - filenames with whitespace in them are not supported.
 188           </para>
 189         </listitem>
 190       </varlistentry>
 191
 192       <varlistentry><term>-h, --help</term>
 193         <listitem>
 194           <para>
 195             Show a short usage guide.
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199     </variablelist>
 200   </refsect1>
 201
 202   <refsect1><title>EXAMPLES</title>
 203     <para>
 204       The following command would show the process ID of ctdb on all nodes
 205     </para>
 206     <screen format="linespecific">
 207       onnode all pidof ctdbd
 208     </screen>
 209
 210     <para>
 211       The following command would show the last 5 lines of log on each
 212       node, preceded by the node's hostname
 213     </para>
 214     <screen format="linespecific">
 215       onnode all "hostname; tail -5 /var/log/log.ctdb"
 216     </screen>
 217
 218     <para>
 219       The following command would restart the ctdb service on all nodes.
 220     </para>
 221     <screen format="linespecific">
 222       onnode all service ctdb restart
 223     </screen>
 224
 225     <para>
 226       The following command would run ./foo in the current working
 227       directory, in parallel, on nodes 0, 2, 3 and 4.
 228     </para>
 229     <screen format="linespecific">
 230       onnode -c -p 0,2-4 ./foo
 231     </screen>
 232   </refsect1>
 233
 234   <refsect1><title>ENVIRONMENT</title>
 235
 236     <variablelist>
 237       <varlistentry><term><envar>CTDB_NODES_FILE</envar></term>
 238         <listitem>
 239           <para>
 240             Name of alternative nodes file to use instead of the
 241             default.  See the discussion of
 242             <filename>/etc/ctdb/nodes</filename> in the FILES section
 243             for more details.
 244           </para>
 245         </listitem>
 246       </varlistentry>
 247
 248     </variablelist>
 249   </refsect1>
 250
 251   <refsect1><title>FILES</title>
 252
 253     <variablelist>
 254       <varlistentry><term><filename>/etc/ctdb/nodes</filename></term>
 255         <listitem>
 256           <para>
 257             Default file containing a list of each node's IP address
 258             or hostname.
 259           </para>
 260           <para>
 261             Actually, the default is
 262             <filename>$<envar>CTDB_BASE</envar>/nodes</filename>,
 263             where <envar>$CTDB_BASE</envar> defaults to
 264             <filename>/etc/ctdb</filename>.  If a relative path is
 265             given (via the -f option or <envar>$CTDB_BASE</envar>) and
 266             no corresponding file exists relative to the current
 267             directory then the file is also searched for in the
 268             <filename>$<envar>CTDB_BASE</envar></filename> directory.
 269           </para>
 270         </listitem>
 271       </varlistentry>
 272
 273       <varlistentry><term><filename>/etc/ctdb/onnode.conf</filename></term>
 274         <listitem>
 275           <para>
 276             If this file exists it is sourced by onnode.  The main
 277             purpose is to allow the administrator to set $SSH to
 278             something other than "ssh".  In this case the -t option is
 279             ignored.  For example, the administrator may choose to use
 280             use rsh instead of ssh.
 281           </para>
 282         </listitem>
 283       </varlistentry>
 284     </variablelist>
 285   </refsect1>
 286
 287   <refsect1><title>SEE ALSO</title>
 288     <para>
 289       ctdbd(1), ctdb(1), <ulink url="http://ctdb.samba.org/"/>
 290     </para>
 291   </refsect1>
 292   <refsect1><title>COPYRIGHT/LICENSE</title>
 293 <literallayout>
 294 Copyright (C) Andrew Tridgell 2007
 295 Copyright (C) Ronnie sahlberg 2007
 296 Copyright (C) Martin Schwenke 2008
 297
 298 This program is free software; you can redistribute it and/or modify
 299 it under the terms of the GNU General Public License as published by
 300 the Free Software Foundation; either version 3 of the License, or (at
 301 your option) any later version.
 302
 303 This program is distributed in the hope that it will be useful, but
 304 WITHOUT ANY WARRANTY; without even the implied warranty of
 305 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 306 General Public License for more details.
 307
 308 You should have received a copy of the GNU General Public License
 309 along with this program; if not, see http://www.gnu.org/licenses/.
 310 </literallayout>
 311   </refsect1>
 312 </refentry>