[ClusterLabs] multiple action= lines sent to STDIN of fencing agents - why?

[Adam Spiers]

I inserted some debugging into fencing.py and found that stonithd
sends stuff like this to STDIN of the fencing agents it forks:

    action=list
    param1=value1
    param2=value2
    param3=value3
    action=list

where paramX and valueX come from the configuration of the primitive
for the fencing agent.

As a corollary, if the primitive for the fencing agent has 'action'
defined as one of its parameters, this means that there will be three
'action=' lines, and the middle one could have a different value to
the two sandwiching it.

When I first saw this, I had an extended #wtf moment and thought it
was a bug.  But on closer inspection, it seems very deliberate, e.g.

  https://github.com/ClusterLabs/pacemaker/commit/bfd620645f151b71fafafa279969e9d8bd0fd74f

The "regardless of what the admin configured" comment suggests to me
that there is an underlying assumption that any fencing agent will
ensure that if the same parameter is duplicated on STDIN, the final
value will override any previous ones.  And indeed fencing.py ensures
this, but presumably it is possible to write agents which don't use
fencing.py.

Is my understanding correct?  If so:

1) Is the first 'action=' line intended in order to set some kind of
   default action, in the case that the admin didn't configure the
   primitive with an 'action=' parameter *and* _action wasn't one of
   list/status/monitor/metadata?  In what circumstances would this
   happen?

2) Is this assumption of the agents always being order-sensitive
   (i.e. last value always wins) documented anywhere?  The best
   documentation on the API I could find was here:

      https://fedorahosted.org/cluster/wiki/FenceAgentAPI

   but it doesn't mention this.

Thanks!