path: root/doc/stonith.xml.in

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<refentry id="re-stonith">
  <refentryinfo>
    <date>December 7, 2009</date>
    <productname>@PACKAGE_NAME@</productname>
    <productnumber>@VERSION@</productnumber>
    <authorgroup>
      <author>
	<firstname>Alan</firstname>
	<surname>Robertson</surname>
	<contrib>stonith</contrib>
	<email>alanr@unix.sh</email>
      </author>
      <author>
	<firstname>Simon</firstname>
	<surname>Horman</surname>
	<contrib>man page</contrib>
	<email>horms@vergenet.net</email>
      </author>
      <author>
	<firstname>Florian</firstname>
	<surname>Haas</surname>
	<contrib>man page</contrib>
	<email>florian.haas@linbit.com</email>
      </author>
    </authorgroup>
  </refentryinfo>
  <refmeta>
    <refentrytitle>stonith</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="manual">System administration utilities</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>stonith</refname>
    <refpurpose>extensible interface for remotely powering down a node
    in the cluster</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>stonith</command>
      <arg choice="plain"><option>-h</option></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>stonith</command>
      <arg choice="opt"><option>-s</option></arg>
      <arg choice="opt"><option>-h</option></arg>
      <arg choice="plain"><option>-L</option></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>stonith</command>
      <arg choice="opt"><option>-s</option></arg>
      <arg choice="opt"><option>-h</option></arg>
      <arg choice="plain"><option>-t</option> <replaceable>stonith-device-type</replaceable></arg>
      <arg choice="plain"><option>-n</option></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>stonith</command>
      <arg choice="opt"><option>-s</option></arg>
      <arg choice="opt"><option>-h</option></arg>
      <arg choice="plain"><option>-t</option> <replaceable>stonith-device-type</replaceable></arg>
      <group choice="req" rep="norepeat">
	<group choice="plain" rep="repeat">
	  <arg choice="plain"><replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
	</group>
	<arg choice="plain"><option>-p</option> <replaceable>stonith-device-parameters</replaceable></arg>
	<arg choice="plain"><option>-F</option> <replaceable>stonith-device-parameters-file</replaceable></arg>
      </group>
      <arg choice="opt"><option>-c</option> <replaceable>count</replaceable></arg>
      <arg choice="opt"><option>-l</option></arg>
      <arg choice="opt"><option>-S</option></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>stonith</command>
      <arg choice="opt"><option>-s</option></arg>
      <arg choice="opt"><option>-h</option></arg>
      <arg choice="plain"><option>-t</option> <replaceable>stonith-device-type</replaceable></arg>
      <group choice="req" rep="norepeat">
	<group choice="plain" rep="repeat">
	  <arg choice="plain"><replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
	</group>
	<arg choice="plain"><option>-p</option> <replaceable>stonith-device-parameters</replaceable></arg>
	<arg choice="plain"><option>-F</option> <replaceable>stonith-device-parameters-file</replaceable></arg>
      </group>
      <arg choice="opt"><option>-c</option> <replaceable>count</replaceable></arg>
      <arg choice="opt"><option>-T</option>
        <group choice="req">
	  <arg choice="plain">reset</arg>
	  <arg choice="plain">on</arg>
	  <arg choice="plain">off</arg>
	</group>
      </arg>
      <arg><replaceable>nodename</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsection id="rs-stonith-description">
    <title>Description</title>
    <para>The STONITH module provides an extensible interface for
    remotely powering down a node in the cluster (STONITH = Shoot The
    Other Node In The Head). The idea is quite simple: when the
    software running on one machine wants to make sure another machine
    in the cluster is not using a resource, pull the plug on the other
    machine. It's simple and reliable, albeit admittedly
    brutal.</para>
  </refsection>
  <refsection id="rs-stonith-options">
    <title>Options</title>
    <para>The following options are supported:</para>
    <variablelist>
      <varlistentry>
	<term>
	  <option>-c</option> <replaceable>count</replaceable>
	</term>
	<listitem>
	  <para>Perform any actions identified by the
	  <option>-l</option>, <option>-S</option> and
	  <option>-T</option> options <replaceable>count</replaceable>
	  times.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-F</option> <replaceable>stonith-device-parameters-file</replaceable>
	</term>
	<listitem>
	  <para>Path of file specifying parameters for a stonith
	  device. To determine the syntax of the parameters file for a
	  given device type run:</para>
	  <screen><computeroutput># </computeroutput><userinput>stonith -t stonith-device-type -n</userinput></screen>
	  <para>All of the listed parameters need to appear in order
	  on a single line in the parameters file and be delimited by
	  whitespace.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-h</option>
	</term>
	<listitem>
	  <para>Display detailed information about a stonith device
	  including description, configuration information, parameters
	  and any other related information.  When specified without a
	  stonith-device-type, detailed information on all stonith
	  devices is displayed.</para>
	  <para>If you don't yet own a stonith device and want to know
	  more about the ones we support, this information is likely
	  to be helpful.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-L</option>
	</term>
	<listitem>
	  <para>List the valid stonith device types, suitable for
	  passing as an argument to the <option>-t</option>
	  option.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-l</option>
	</term>
	<listitem>
	  <para>List the hosts controlled by the stonith device.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-n</option>
	</term>
	<listitem>
	  <para>Output the parameter names of the stonith device.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <replaceable>name</replaceable>=<replaceable>value</replaceable>
	</term>
	<listitem>
	  <para>Parameter, in the form of a name/value pair, to pass
	  directly to the stonith device.  To determine the syntax of
	  the parameters for a given device type run:</para>
	  <screen><computeroutput># </computeroutput><userinput>stonith -t stonith-device-type -n</userinput></screen>
	  <para>All of the listed parameter names need to be passed
	  with their corresponding values.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-p</option> <replaceable>stonith-device-parameters</replaceable>
	</term>
	<listitem>
	  <para>Parameters to pass directly to the stonith device.  To
	  determine the syntax of the parameters for a given device
	  type run:</para>
	  <screen><computeroutput># </computeroutput><userinput>stonith -t stonith-device-type -n</userinput></screen>
	  <para>All of the listed parameter names need to appear in
	  order and be delimited by whitespace.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-S</option>
	</term>
	<listitem>
	  <para>Show the status of the stonith device.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-s</option>
	</term>
	<listitem>
	  <para>Silent operation. Suppress logging of error messages to standard error.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-T</option> <replaceable>action</replaceable>
	</term>
	<listitem>
	  <para>The stonith action to perform on the node identified
	  by nodename.  Chosen from <token>reset</token>,
	  <token>on</token>, and <token>off</token>.</para>
	  <note>
	    <para>If a nodename is specified without the
	    <option>-T</option> option, the stonith action defaults to
	    <token>reset</token>.</para>
	  </note>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-t</option> <replaceable>stonith-device-type</replaceable>
	</term>
	<listitem>
	  <para>The type of the stonith device to be used to effect
	  stonith. A list of supported devices for an installation may
	  be obtained using the <option>-L</option> option.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <option>-v</option>
	</term>
	<listitem>
	  <para>Ignored.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsection>
  <refsection id="rs-stonith-examples">
    <title>Examples</title>
    <para>To determine which stonith devices are available on your installation, use the <option>-L</option> option:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -L</userinput></screen>
    <para>All of the supported devices will be displayed one per line.
    Choose one from this list that is best for your environment -
    let's use <code>wti_nps</code> for the rest of this example.  To get detailed
    information about this device, use the <option>-h</option> option:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps -h</userinput></screen>
    <para>Included in the output is the list of valid parameter names
    for <code>wti_nps</code>. To get <emphasis>just</emphasis> the
    list of valid parameter names, use the <option>-n</option> option
    instead:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps -n</userinput></screen>
    <para>All of the required parameter names will be displayed one
    per line.  For <code>wti_nps</code> the output is:</para>
    <screen><computeroutput>ipaddr</computeroutput>
<computeroutput>password</computeroutput></screen>
    <para>There are three ways to pass these parameters to the device.
    The first (and preferred) way is by passing name/value pairs on
    the <command>stonith</command> command line:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps ipaddr=my-dev-ip password=my-dev-pw ...</userinput></screen>
    <para>The second way, which is maintained only for backward
    compatibility with legacy clusters, is passing the values
    <emphasis>in order</emphasis> on the <command>stonith</command>
    command line with the <option>-p</option> option:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps -p "my-dev-ip my-dev-pw" ...</userinput></screen>
    <para>The third way, which is also maintained only for backward
    compatibility with legacy clusters, is placing the values <emphasis>in order</emphasis>
    on a single line in a config file:</para>
    <programlisting>my-dev-ip my-dev-pw</programlisting>
    <para>... and passing the name of the file on the stonith command
    line with the <option>-F</option> option:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps -F ~/my-wtinps-config ...</userinput></screen>
    <para>To make sure you have the configuration set up correctly and
    that the device is available for stonith operations, use the
    <option>-S</option> option:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps ipaddr=my-dev-ip password=my-dev-pw -S</userinput></screen>
    <para>If all is well at this point, you should see something similar to:</para>
    <screen><computeroutput>stonith: wti_nps device OK.</computeroutput></screen>
    <para>If you don't, some debugging may be necessary to determine
    if the config info is correct, the device is powered on, etc.  The
    <option>-d</option> option can come in handy here - you can add it
    to any <command>stonith</command> command to cause it to generate
    debug output.</para>
    <para>To get the list of hosts controlled by the device, use the
    <option>-l</option> option:</para>
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps ipaddr=my-dev-ip password=my-dev-pw -l</userinput></screen>
    <para>All of the hosts controlled by the device will be displayed one per line.  For <code>wti_nps</code> the output could be:</para>
    <screen><computeroutput>node1</computeroutput>
    <computeroutput>node2</computeroutput>
    <computeroutput>node3</computeroutput></screen>
    <para>To power off one of these hosts, use the <option>-T</option> option:
    <screen><computeroutput># </computeroutput><userinput>stonith -t wti_nps ipaddr=my-dev-ip password=my-dev-pw -T off <replaceable>node</replaceable></userinput></screen></para>
  </refsection>
  <refsection id="rs-stonith-seealso">
    <title>See also</title>
    <para>
      <citerefentry><refentrytitle>heartbeat</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>meatclient</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    </para>
  </refsection>
</refentry>