diff options
Diffstat (limited to 'doc/stonith.xml.in')
| -rw-r--r-- | doc/stonith.xml.in | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/doc/stonith.xml.in b/doc/stonith.xml.in new file mode 100644 index 0000000..575c339 --- /dev/null +++ b/doc/stonith.xml.in @@ -0,0 +1,315 @@ +<?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> |