= Receiving Notification for Cluster Events =

//// 
We prefer [[ch-notifications]], but older versions of asciidoc don't deal well
with that construct for chapter headings
////
anchor:ch-notifications[Chapter 7, Receiving Notification for Cluster Events]
indexterm:[Resource,Notification]

A Pacemaker cluster is an event-driven system. In this context, an 'event'
might be a resource failure or a configuration change, among others.

The *ocf:pacemaker:ClusterMon* resource can monitor the cluster status and
trigger alerts on each cluster event. This resource runs `crm_mon` in the
background at regular (configurable) intervals and uses `crm_mon` capabilities
to trigger emails (SMTP), SNMP traps or external programs (via the
+extra_options+ parameter).

[NOTE]
=====
Depending on your system settings and compilation settings, SNMP or email
alerts might be unavailable. Check the output of `crm_mon --help` to see whether these
options are available to you. In any case, executing an external agent will
always be available, and you can use this agent to send emails, SNMP traps
or whatever action you develop.
=====

[[s-notification-snmp]]
== Configuring SNMP Notifications ==
indexterm:[Resource,Notification,SNMP]

Requires an IP to send SNMP traps to, and an SNMP community string.
The Pacemaker MIB is provided with the source, and is typically
installed in +/usr/share/snmp/mibs/PCMK-MIB.txt+.

This example uses +snmphost.example.com+ as the SNMP IP and
+public+ as the community string:

.Configuring ClusterMon to send SNMP traps
=====
[source,XML]
-----
<clone id="ClusterMon-clone">
    <primitive class="ocf" id="ClusterMon-SNMP" provider="pacemaker" type="ClusterMon">
	<instance_attributes id="ClusterMon-instance_attributes">
	    <nvpair id="ClusterMon-instance_attributes-user" name="user" value="root"/>
	    <nvpair id="ClusterMon-instance_attributes-update" name="update" value="30"/>
	    <nvpair id="ClusterMon-instance_attributes-extra_options" name="extra_options" value="-S snmphost.example.com -C public"/>
	</instance_attributes>
    </primitive>
</clone>
-----
=====

[[s-notification-email]]
== Configuring Email Notifications ==
indexterm:[Resource,Notification,SMTP,Email]

Requires the recipient e-mail address. You can also optionally configure
the sender e-mail address, the hostname of the SMTP relay, and a prefix string
for the subject line.

.Configuring ClusterMon to send email alerts
=====
[source,XML]
-----
<clone id="ClusterMon-clone">
    <primitive class="ocf" id="ClusterMon-SMTP" provider="pacemaker" type="ClusterMon">
	<instance_attributes id="ClusterMon-instance_attributes">
	    <nvpair id="ClusterMon-instance_attributes-user" name="user" value="root"/>
	    <nvpair id="ClusterMon-instance_attributes-update" name="update" value="30"/>
	    <nvpair id="ClusterMon-instance_attributes-extra_options" name="extra_options" value="-T pacemaker@example.com -F pacemaker@node2.example.com -P PACEMAKER -H mail.example.com"/>
	</instance_attributes>
    </primitive>
</clone>
-----
=====

[[s-notification-external]]
== Configuring Notifications via External-Agent ==

Requires a program (external-agent) to run when resource operations take
place, and an external-recipient (IP address, email address, URI). When
triggered, the external-agent is fed with dynamically filled environment
variables describing precisely the cluster event that occurred. By making
smart usage of these variables in your external-agent code, you can trigger
any action.

.Configuring ClusterMon to execute an external-agent
=====
[source,XML]
-----
<clone id="ClusterMon-clone">
    <primitive class="ocf" id="ClusterMon" provider="pacemaker" type="ClusterMon">
	<instance_attributes id="ClusterMon-instance_attributes">
	    <nvpair id="ClusterMon-instance_attributes-user" name="user" value="root"/>
	    <nvpair id="ClusterMon-instance_attributes-update" name="update" value="30"/>
	    <nvpair id="ClusterMon-instance_attributes-extra_options" name="extra_options" value="-E /usr/local/bin/example.sh -e 192.168.12.1"/>
	</instance_attributes>
    </primitive>
</clone>
-----
=====

.Environment Variables Passed to the External Agent
[width="95%",cols="1m,2<",options="header",align="center"]
|=========================================================

|Environment Variable
|Description

|CRM_notify_recipient
| The static external-recipient from the resource definition.
 indexterm:[Environment Variable,CRM_notify_recipient]

|CRM_notify_node
| The node on which the status change happened.
 indexterm:[Environment Variable,CRM_notify_node]

|CRM_notify_rsc
| The name of the resource that changed the status.
 indexterm:[Environment Variable,CRM_notify_rsc]

|CRM_notify_task
| The operation that caused the status change.
 indexterm:[Environment Variable,CRM_notify_task]

|CRM_notify_desc
| The textual output relevant error code of the operation (if any) that caused the status change.
 indexterm:[Environment Variable,CRM_notify_desc]

|CRM_notify_rc
| The return code of the operation.
 indexterm:[Environment Variable,CRM_notify_rc]

|CRM_notify_target_rc
| The expected return code of the operation.
 indexterm:[Environment Variable,CRM_notify_target_rc]

|CRM_notify_status
| The numerical representation of the status of the operation.
 indexterm:[Environment Variable,CRM_notify_target_rc]

|=========================================================
