-=] Updated:

July 10, 2010
Digimer; digimer@alteeve.com


-=] Overview:

This is an overview of the Node Assassin Fence Agent and device.


-=] Building Your Own Node Assassin:

The installer puts a copy of the build documents in '/etc/fence_na/' as a
tarball called 'build.tar.gz'. This includes everything needed to build your
own Node Assassin. 


-=] Configuration File:

Be sure to review and edit '/etc/fence_na/fence_na.conf'!


-=] Note:

This fence agent supports CentOS 5.5 and Fedora 13. The install will run and
the setup will differ depending on the OS you are using.

This is a little random at the moment. I will update it later, or feel free to
send me an update if you feel so inclined. :)


-=] The Cluster 'cluster.conf' File:

Here is an example of the cluster related entries you will need to use in order
to properly use the Node Assassin.

------------------------------------------------------------------------------
<cluster name="an_cluster" config_version="1">
	<clusternodes>
		<clusternode name="an_node01.alteeve.com" nodeid="1">
			<fence>
				<method name="node_assassin">
					<device name="motoko" port="01" action="off"/>
				</method>
			</fence>
		</clusternode>
		<clusternode name="an_node02.alteeve.com" nodeid="2">
			<fence>
				<method name="node_assassin">
					<device name="motoko" port="02" action="off"/>
				</method>
			</fence>
		</clusternode>
	</clusternodes>
	<fencedevices>
		<fencedevice name="node_assassin" agent="fence_na" ipaddr="motoko.alteeve.com" name="motoko" passwd="secret"></fencedevice>
	</fencedevices>
</cluster>
------------------------------------------------------------------------------


-=] Step by step of a Fence Action:

When 'fenced' decides to fence "an_node01.alteeve.com", it will:

1. Call '/sbin/fence_na' because of the 'fencedevices' -> 'agent' value.
2. It will pass the following arguments to the fence agent, one pair per line:
    agent=fence_na		# From 'fencedevices' -> 'agent'
    name=motoko			# From 'fencedevices' -> 'name'
    ipaddr=motoko.alteeve.com	# From 'fencedevices' -> 'ipaddr'
    passwd=secret		# From 'fencedevices' -> 'passwd'
    port=01			# From 'clusternode' -> 'an_node01.alteeve.com'
				# -> 'port'
    action=fence_na		# From 'clusternode' -> 'an_node01.alteeve.com'
				# -> 'option'. This must be 'on', 'off', 
				# 'reboot', 'status' or 'monitor'. See below
				# for how these terms are interpreted by this
				# agent. In most cases, you will want to use
				# 'off'.
    				# NOTE: If 'option' is passed, its value will
    				# be stored in 'action'. That is, 'action' and
    				# 'option' are synonymous but 'option' is
				# deprecated.

- Node Assassin's implentation of options.
  - 'off'	This set's the node to state 1; Fenced. Internally, it will hit
		the reset switch for one second to immediately disable the
		node. Then it will release the reset switch for another second
		before pressing and holding the power switch. After five
		seconds, Node Assassin will check the node's power feed. If it
		is still on, it will wait another 25 seconds and check again.
		If the node is still on, an error will be generated. If the
		node turns off successfully, the fence is declared a success.
  - 'on'	This sets the node to state '0'; Not fenced. Both the power and
		reset switches are opened, the Node Assassin will pause for one
 		second and then the power switch will be closed for one second
		to boot the node (that is, the node is set to "state 2").
  - 'reboot'	This essentially just calls an 'off' and then an 'on'. However,
		the fence_na agent will return a success (exit 0) even if only
		the 'off' stage succeeded. As per the FenceAgentAPI, a reboot
		does not need to successfully boot the node to be considered a
		success.
  - 'status'	This checks the power feed for the requested node is checked.
		If the node is on, the agent will exit with code 0. If the node
		is off (or disconnected), it will exit with code 1. If an error
		occurred calling the Node Assassin, this will exit with code 2.
  - 'monitor'	Being a multi-port fence device, this simply call 'list'.
  - 'list'	This returns a CSV of the ports on your Node Assassin. Each
		node will be on a new line in the format "node,alias" where the
		alias is read from the config file.


-=] Command Line Arguments:

Any command line arguments used by this fence agent are not dictated by the
Fence Agent API. The following command line options are used to match the
precedent set by existing fence agents for other devices.

Options are:

  -a <ip>	# Maps the value to 'ipaddr'.
  -h		# Print the help message and then exits.
  -l <name>	# Maps the value to 'name'.
  -n <num>	# Maps the value to 'port'.
  -o <string>	# Maps the value to 'action'.
  -p <string>	# Maps the value to 'passwd'.
  -S <path>	# Maps the value to 'passwd_script'. This is not used by Node
  		# Assassin (yet) and is simply ignored.
  -q		# Sets quiet mode. Only errors will be printed. Logging
  		# proceeds as normal.
  -V		# Prints the 'fence_na' version and the version of any attached
  		# Node Assassin(s) and exits.


-=] Notes:

All verifications of actions is done by checking the state of the node's 
"Power LED". For this reason, it is critical that you connect this feed.

The power and reset buttons are polarized. That is, you *MUST* connect the 
positive terminals from your mainboard's power and reset switches to the
positive wires going to the Node Assassin.

                                   IMPORTANT!

If you connect the power or reset buttons backwards, the circuit will be closed
(that is, you will have pressed the button). This is by design!

	ALWAYS TEST YOUR Node Assassin!

Specifically, after connecting a new node, be sure to manually send the
'on' -> 'off' -> 'on' actions to make sure that the nodes are properly setup.
If there are any problems with your Node Assassin or with the cables connected
to your node, the fence agent will fail and generate errors. 

