7.7. Writing an Alert Agent

⁠7.7. Writing an Alert Agent

Table 7.2. Environment variables passed to alert agents

Environment Variable	Description
`CRM_alert_kind`	The type of alert (`node`, `fencing`, `resource`, or `attribute`)
`CRM_alert_version`	The version of Pacemaker sending the alert
`CRM_alert_recipient`	The configured recipient
`CRM_alert_node_sequence`	A sequence number increased whenever an alert is being issued on the local node, which can be used to reference the order in which alerts have been issued by Pacemaker. An alert for an event that happened later in time reliably has a higher sequence number than alerts for earlier events. Be aware that this number has no cluster-wide meaning.
`CRM_alert_timestamp`	A timestamp created prior to executing the agent, in the format specified by the `timestamp-format` meta-attribute. This allows the agent to have a reliable, high-precision time of when the event occurred, regardless of when the agent itself was invoked (which could potentially be delayed due to system load, etc.).
`CRM_alert_timestamp_epoch`	The same time as `CRM_alert_timestamp`, expressed as the integer number of seconds since January 1, 1970. This (along with `CRM_alert_timestamp_usec`) can be useful for alert agents that need to format time in a specific way rather than let the user configure it.
`CRM_alert_timestamp_usec`	The same time as `CRM_alert_timestamp`, expressed as the integer number of microseconds since `CRM_alert_timestamp_epoch`.
`CRM_alert_node`	Name of affected node
`CRM_alert_desc`	Detail about event. For `node` alerts, this is the node’s current state (`member` or `lost`). For `fencing` alerts, this is a summary of the requested fencing operation, including origin, target, and fencing operation error code, if any. For `resource` alerts, this is a readable string equivalent of `CRM_alert_status`.
`CRM_alert_nodeid`	ID of node whose status changed (provided with `node` alerts only)
`CRM_alert_task`	The requested fencing or resource operation (provided with `fencing` and `resource` alerts only)
`CRM_alert_rc`	The numerical return code of the fencing or resource operation (provided with `fencing` and `resource` alerts only)
`CRM_alert_rsc`	The name of the affected resource (`resource` alerts only)
`CRM_alert_interval`	The interval of the resource operation (`resource` alerts only)
`CRM_alert_target_rc`	The expected numerical return code of the operation (`resource` alerts only)
`CRM_alert_status`	A numerical code used by Pacemaker to represent the operation result (`resource` alerts only)
`CRM_alert_exec_time`	The (wall-clock) time, in milliseconds, that it took to execute the action. If the action timed out, `CRM_alert_status` will be 2, `CRM_alert_desc` will be "Timed Out", and this value will be the action timeout. May not be supported on all platforms. (`resource` alerts only)
`CRM_alert_attribute_name`	The name of the node attribute that changed (`attribute` alerts only)
`CRM_alert_attribute_value`	The new value of the node attribute that changed (`attribute` alerts only)

Special concerns when writing alert agents:

Alert agents may be called with no recipient (if none is configured), so the agent must be able to handle this situation, even if it only exits in that case. (Users may modify the configuration in stages, and add a recipient later.)
If more than one recipient is configured for an alert, the alert agent will be called once per recipient. If an agent is not able to run concurrently, it should be configured with only a single recipient. The agent is free, however, to interpret the recipient as a list.
When a cluster event occurs, all alerts are fired off at the same time as separate processes. Depending on how many alerts and recipients are configured, and on what is done within the alert agents, a significant load burst may occur. The agent could be written to take this into consideration, for example by queueing resource-intensive actions into some other instance, instead of directly executing them.
Alert agents are run as the hacluster user, which has a minimal set of permissions. If an agent requires additional privileges, it is recommended to configure sudo to allow the agent to run the necessary commands as another user with the appropriate privileges.
As always, take care to validate and sanitize user-configured parameters, such as CRM_alert_timestamp (whose content is specified by the user-configured timestamp-format), CRM_alert_recipient, and all instance attributes. Mostly this is needed simply to protect against configuration errors, but if some user can modify the CIB without having hacluster-level access to the cluster nodes, it is a potential security concern as well, to avoid the possibility of code injection.

Note

The alerts interface is designed to be backward compatible with the external scripts interface used by the ocf:pacemaker:ClusterMon resource, which is now deprecated. To preserve this compatibility, the environment variables passed to alert agents are available prepended with CRM_notify_ as well as CRM_alert_. One break in compatibility is that ClusterMon ran external scripts as the root user, while alert agents are run as the hacluster user.