This site best when viewed with a modern standards-compliant browser. We recommend Firefox Get Firefox!.

Linux-HA project logo
Providing Open Source High-Availability Software for Linux and other OSes since 1999.

USA Flag UK Flag

Japanese Flag


About Us

Contact Us

Legal Info

How To Contribute

Security Issues

This web page is no longer maintained. Information presented here exists only to avoid breaking historical links.
The Project stays maintained, and lives on: see the Linux-HA Reference Documentation.
To get rid of this notice, you may want to browse the old wiki instead.

1 February 2010 Hearbeat 3.0.2 released see the Release Notes

18 January 2009 Pacemaker 1.0.7 released see the Release Notes

16 November 2009 LINBIT new Heartbeat Steward see the Announcement

Last site update:
2020-07-16 13:11:32

External STONITH Plugins

Required STONITH operations

Each of the operations below are mandatory for any external STONITH device.


Reset the given node.


Return the list of hosts (i.e. the hostname (uname -n) of each host) that can be reached using this device. Note that it is by far preferable to retrieve this from the STONITH device - if it knows what it can reset. Otherwise you have to ask the adminstrator to tell you that information in the configuration parameters which is a potential source of error.


Exit with return code zero if this device can be reached, non-zero if this device cannot be reached.


Return the list of mandatory environment variables that you need to be configured. For R1 (legacy) configurations, the order in which these are returned dictates the order in which the values must be passed in the config file or on the stonith_host line. Do not return any optional parameters in this list.


Return something specifically identifying this class of STONITH devices (does not require configuration information in the environment).


Return something specifically identifying this specific STONITH device (typically requires configuration information in the environment).


Return the description of this type of device.


Return a URL pointing to more information on this device.


Return an XML fragment defining all of the parameters and their descriptions, etc. A sample of such information is shown below.

 <parameter name=hostlist unique=1>
  <content type="string"/>
  <shortdesc lang="en">hostlist</shortdesc>
  <longdesc lang=en>
The list of hosts that the ssh STONITH device controls

Note that some of this information may duplicate information obtainable from some of the other getinfo calls.

Optional STONITH operations

If you can power off the device, and power it on, then you should also support these two commands:

off (optional)

on (optional)

Configuration information

To create your own external plugin, write a script that supports the above operations and place it in the /usr/lib/stonith/plugins/external directory - the script must be a regular executable file that is NOT writable by group or others in order to be recognized as an external plugin. If the action requires information to be returned, such as the list of hosts or config names or any of the getinfo calls, simply write the information to stdout. When complete, return zero to indicate the action succeeded or non-zero to indicate the action failed. You can use the ssh (sh) and riloe (pyhton) scripts already in that directory as working examples.

To make sure that your external plugin is recognized, run "stonith -L" and look for its name in the output, something along the lines of:


If it does appear in stonith's output, you are ready to configure your external plugin.

R1 (legacy) configuration

To configure the plugin on an R1 (legacy) cluster, add a line similar to the following to /etc/ha.d/

stonith external/yourplugin /etc/ha.d/yourplugin.cfg

where /etc/ha.d/yourplugin.cfg contains a single line with all of your plugin's parameters:

parm1-value parm2-value ...

Another way to configure the plugin on a legacy cluster is to add a line similiar to the following to /etc/ha.d/ instead:

stonith_host * external/yourplugin parm1-value parm2-value ...

where all of your plugin's parameters are placed at the end of the line.

Please note that all parameters come in to the plugin in name/value (environment variable) form, but in R1 configurations, they appear as a list of parameters. They are ordered in the config file or on the stonith_host line according to the ordering specified in the output of the getconfignames operation.

R2 configuration

To configure the plugin on an R2 cluster, place lines similar to the following into the <resources> section of your CIB, which is contained in /var/lib/heartbeat/crm/cib.xml:

<clone id="DoFencing">
      <nvpair name="clone_max" value="2"/>
      <nvpair name="clone_node_max" value="1"/>
  <primitive id="child_DoFencing" class="stonith" type="external/yourplugin" provider="heartbeat">
      <op name="monitor" interval="5s" timeout="20s" prereq="nothing"/>
      <op name="start" timeout="20s" prereq="nothing"/>
        <nvpair name="parm1-name" value="parm1-value"/>
        <nvpair name="parm2-name" value="parm2-value"/>
        <!-- ... -->

Whatever <nvpair> parameters specified in the <attributes> section of the CIB are passed to the script as environment variables. For the example above, the parameters are passed as parm1-name=parm1-value, parm2-name=parm2-value and so on.

(!) Also have a look at predefined snippets for stonith devices at CIB/Idioms.