Actions¶

All actions have configurable retry behaviour to guard against potential failure. See Action Retry Behaviour for details.

Trap¶

A Trap action defined for an observation will send an SNMP trap to the specified destination when the observation fires.

Attributes

name (string): The name for the trap definition. If the name is used higher up in the action holder hierarchy then this definition will override its behaviour.
enabled (boolean): Whether the trap action is enabled.
retrycount (integer): See Action Retry Behaviour for details.
retrydelay (integer|period): See Action Retry Behaviour for details.

Parameters

destination (string)

Hostname or IP address of the manager that should receive the trap. The full format is:

[transport:]hostname[:port]

transport:	One of `udp`, `tcp`, `udp6`, `tcp6`. Defaults to `udp`.
hostname:	Can be a DNS hostname, IPv4 address or IPv6 address. When using an IPv6 address it must be enclosed in square brackets, e.g. `[fe80::223:64cf:fe32:b63a]` to avoid ambiguity with the port number.
port:	The TCP or UDP port to connect to, default to 162 which is the port assigned to SNMP by IANA.

Some examples:

hostname:162                    # UDP/IPv4 to *hostname*  port *162*
hostname                        # UDP/IPv4 to *hostname* port *162*
192.168.0.1                     # UDP/IPv4 to *192.168.0.1* port *162*
tcp:hostname:1162               # TCP/IPv4 to *hostname* port *1162*
udp6:hostname:1162              # UDP/IPv6 to *hostname* port *1162*
udp6:[fe80::2d0:b7ff:fe21:c6c0] # UDP/IPv6 to *fe80::2d0:b7ff:fe21:c6c0* port *162*
tcp6:[:;1]:1162                 # TCP/IPv6 to local host port *1162*

community (string)

SNMP community string.

version (string)

SNMP version to use.

oid (string)

Main object identifier. For example: enterprises.26788.100.

object (string)

Sub-object. There may be more than one of these same named parameters. The content must be a semi-colon delimited tuple of three items:

<id>; <snmp type> ; <data>

Here <snmp type> is a single character, one of:

i:	integer
u:	unsigned
c:	counter32
s:	string
x:	hex string
d:	decimal string
n:	nullobj
o:	objid
t:	timeticks
a:	ipaddress
b:	bits

For example:

1;s;MINOR

or:

2;s;%{message}

inform

When this parameter is present an INFORM PDU is sent instead of a TRAP PDU. This is only valid for v2c and v3 traps.

SNMP Version specific

See below for information on SNMP version specific parameters.

Basic example:

<!-- Default Trap Definition -->
<Trap name="defaultTrap">
  <Parameter index="1" name="destination">manager1-abilisoft.com</Parameter>
  <Parameter index="2" name="community">public</Parameter>
  <Parameter index="3" name="version">2c</Parameter>
  <Parameter index="4" name="oid">enterprises.26788.100</Parameter>
  <Parameter index="5" name="object">1;s;MINOR</Parameter>
  <Parameter index="6" name="object">2;s;%{hostname}</Parameter>
  <Parameter index="7" name="object">3;s;%{ip}</Parameter>
  <Parameter index="8" name="object">4;s;%{message}</Parameter>
</Trap>

Trap actions support SNMPv1, v2c & v3 traps. The parameters vary between versions and are described in the following sections.

SNMPv1¶

<Trap name="defaultTrap">
  <Parameter name="destination">127.0.0.1:162</Parameter>
  <Parameter name="version">1</Parameter>
  <Parameter name="community">public</Parameter>
  <Parameter name="enterpriseOid">.1.3.6.1.4.1.26788</Parameter>
  <Parameter name="agent"/>
  <Parameter name="genericTrap">0</Parameter>
  <Parameter name="specificTrap">0</Parameter>
  <Parameter index="1"
             name="object">.1.3.6.1.4.1.26788.0.200.1;s;MINOR</Parameter>
</Trap>

Here the enterpriseOid, agent, genericTrap and specificTrap parameters are all optional. However they are included with their default values in the example above.

Note that the default combination of genericTrap and specificTrap is more than likely not suitable, especially if your trap daemon pays attention to them. Since v1 traps do not have a trap OID parameter you must specify a full OID in the “object” parameters.

SNMPv2c¶

<Trap name="defaultTrap">
  <Parameter name="destination">127.0.0.1:162</Parameter>
  <Parameter name="version">2c</Parameter>
  <Parameter name="community">public</Parameter>
  <Parameter name="oid">.1.3.6.1.4.1.26788.0.200</Parameter>
  <Parameter index="1" name="object">1;s;MINOR</Parameter>
  <Parameter index="2" name="object">2;s;%{hostname}</Parameter>
  <Parameter index="3" name="object">3;s;%{ip}</Parameter>
  <Parameter index="4" name="object">.1.4;s;%{message}</Parameter>
</Trap>

Here the “object” parameters can be any required number according to the desired varbinds. (Note you can have as many varbinds as you like and their dispatch order is defined by the “index” attribute on the “Parameter” tag).

The “oid” parameter is the OID of the trap itself. The OIDs of the varbind are constructed by concatenating “oid” with the first part of the “object”, e.g. for the object with index 1 (1;s;MINOR) the OID of the varbind will be .1.3.6.1.4.1.26788.0.200.1. It is also possible to specify an entirely different OID in the varbind by using a full OID in the object instead of just one number, i.e. the object with index 4 (1.4;s;%{message}) would get the (albeit invalid) OID “.1.4”.

SNMPv3¶

For SNMPv3 traps the full definition is:

<Trap name="defaultTrap">
  <Parameter name="destination">127.0.0.1:162</Parameter>
  <Parameter name="version">3</Parameter>
  <Parameter name="seclevel">noAuthNoPriv</Parameter>
  <Parameter name="secName">abilisoft</Parameter>
  <Parameter name="authPassword"/>
  <Parameter name="authProtocol"/>
  <Parameter name="privPassword"/>
  <Parameter name="privProtocol"/>
  <Parameter name="oid">.1.3.6.1.4.1.26788</Parameter>
  <Parameter name="engineId”>0x800000020109840301</Parameter>
  <Parameter index="1" name="object">1;s;MINOR</Parameter>
</Trap>

For SNMPv3 traps the destination, version and secName parameters are required. The parameter seclevel will have a default value of noAuthNoPriv if it is not specified. If the seclevel parameter is set to authNoPriv then authPassword is required. If seclevel parameter is set to authPriv then the privPassword parameter is required. Engine ID must also be set appropriately. The table below describes allowable values:

Parameter	Allowed Values
seclevel	noAuthNoPriv, authNoPriv, authPriv
secName	any string
authPassword	any string
authProtocol	MD5, SHA
privProtocol	DES, AES
privPassword	any string
engineId	This MUST be a valid engine ID recognised by the management station and must begin with the characters “0x”.

Smtp¶

An Smtp action defined for an observation will send an SMTP message to the specified addressees when the observation fires.

Attributes

name (string): The name for the smtp definition. If the name is used higher up in the action holder hierarchy then this definition will override its behaviour.
enabled (boolean): Whether the smtp action is enabled.
retrycount (integer): See Action Retry Behaviour for details.
retrydelay (integer|period): See Action Retry Behaviour for details.

Parameters

fromaddr (string): The address from which the mail message should be sent.
subject (string): Mail message subject
body (string): Mail message body
server (string): SMTP server name or IP address
port (string): SMTP Port
username (string): Account username
password (string): Account password
recipient (string): E-mail address of a recipient for these messages. There may be more than one of these same named parameters. The content must be a valid e-mail address.

Example:

<!-- Default SMTP Settings -->
<Smtp name="defaultSmtp">
  <Parameter name="fromaddr">alert@abilisoft.com</Parameter>
  <Parameter name="subject">Abilisoft Alert</Parameter>
  <Parameter name="body">
Hello,

At %{dtsNice} the component %{appName} failed on %{hostname}

(IP Address: %{ip}).

Details:

%{message}

This message is automatically generated, please do not reply.
  </Parameter>
  <Parameter name="server">example.mail.com</Parameter>
  <Parameter name="port">25</Parameter>
  <Parameter name="username">exampleuser</Parameter>
  <Parameter name="password">xyzxyz</Parameter>
  <Parameter name="recipient">support-team@example.com</Parameter>
  <Parameter name="recipient">support-team-manager@example.com</Parameter>
</Smtp>

Cmd¶

A Cmd action defined for an observation will issue an operating system command when the observation fires.

Attributes

name (string): The name for the command definition. If the name is used higher up in the action holder hierarchy then this definition will override its behaviour.
enabled (boolean): Whether the cmd action is enabled.
retrycount (integer): See Action Retry Behaviour for details.
retrydelay (integer|period): See Action Retry Behaviour for details.

Parameters

cmd (string): The command to be executed

Example:

<!-- Default Cmd Settings -->
<Cmd name="defaultCommand">
  <Parameter name="cmd">/usr/bin/escalate.pl %{dts} %{hostname}
%{message}</Parameter>
</Cmd>

Control¶

A Control action defined for an observation enables one to turn monitors on and off in response to an observation firing. Note that monitors that are disabled at start-up may be started this way.

Attributes

name (string): The name for the Control definition. If the name is used higher up in the action holder hierarchy then this definition will override its behaviour.
enabled (boolean): Whether the Control action is enabled.
retrycount (integer): See Action Retry Behaviour for details.
retrydelay (integer|period): See Action Retry Behaviour for details.

Parameters

name (string): Fully qualified name of the monitor to control, in the form <Component Name>.<Monitor Name>, for example “memory.memUsage”. The value of the parameter should be a boolean value (e.g. on, off, true, false etc). There is a wildcard syntax for controlling an entire component as follows: <Component Name>.*

Example:

<!--
Start to peer monitor an agent after we've been running at least an hour
-->

<Component name="dynamic" type="GENERIC_EMPTY">

  <Control name="startPeerMon">
    <Parameter name="dynamic.peerMon">on</Parameter>
  </Control>

  <!-- Monitor System Info -->
  <Monitor name="systemInfo" type="agent.mon.systemInfo">
    <Observation name="rebootObservation">
      <Test type="compare">
        <Parameter name="arg0">$upTime</Parameter>
        <Parameter name="operator">gt</Parameter>
        <Parameter name="arg1">3600</Parameter>
      </Test>
      <Message>Agent on %{hostname} has been up an hour</Message>
      <Suppression numberOfTimes="1"/>
      <Control name="startPeerMon"/>
    </Observation>
  </Monitor>

  <Monitor name="peerMon" type="agent.mon.peerMonitor" enabled="false">
    <Parameter name="host">192.168.2.17</Parameter>
    <Parameter name="usr">admin</Parameter>
    <Parameter name="pwd">admin</Parameter>
    <Parameter name="stats">on</Parameter>
  </Monitor>

</Component>

Notify¶

A Notify Action defined for an observation will issue an Abilisoft Event when the observation fires. The event is basically an HTTP post with JSON encoded content, the JSON content being a structure containing the event data. Events issued are sent to an Abilisoft Reef Server instance for processing and display.

Attributes

name (string): The name for the Notify definition. If the name is used higher up in the action holder hierarchy then this definition will override its behaviour.
enabled (boolean): Whether the Notify action is enabled.
retrycount (integer): See Action Retry Behaviour for details.
retrydelay (integer|period): See Action Retry Behaviour for details.

Parameters

uri (string)

The only mandatory parameter that specifies the location of a live Reef instance, or a proxy for it.

key (string)

A key value that is shared between companion up/down events to enable correlation and de-duplication within Reef. For example %{hostname}.general.tomcat.proc-state. Setting this parameter will cause the reef_severity field to be set in the outbound event.

type (string)

The event type (some types recognised by Reef are fault, clear and info). Setting the right event type is also an important enabler for correlation within Reef. Setting this parameter will cause the reef_type field to be set in the outbound event.

severity (string)

The event severity, e.g. critical, major, minor or info. Setting this parameter will cause the reef_severity field to be set in the outbound event.

json (string)

JSON encoded event attributes that will add/update any attributes that have not been set, inferred or set in a parameter. For example:

{"reef_severity": "major", "custom_field": %{my_variable}}.

See http://json.org/ for guidance on JSON notation.

Example:

<!-- Notify Settings -->
<Notify name="reefNotify">
  <Parameter name="uri">http://reef.abilisoft.com:8000/reef/</Parameter>
</Notify>

This is the minimum configuration required to send an event. The following Reef event field values are set:

reef_source field is set to asagent
reef_ip field is set to the interface address the agent is configured to reside on
reef_node field is set to the hostname of the host agent is running on
reef_description field is set to the value of the observation message
reef_label field is set to a truncated version of the description field

Also note that:

Placeholders (e.g. %{hostname}) can be used in the parameter values including anywhere in the JSON parameter value.
You can add and override Notify parameters for a given definition elsewhere in the manifest.

A more comprehensive example:

<!-- Top level Notify Settings -->
<Notify name="defaultNotify">
  <Parameter name="uri">http://reef.abilisoft.com:8000/reef/</Parameter>
  <Parameter name="severity">critical</Parameter>
  <Parameter name="type">fault</Parameter>
</Notify>

...

<!-- Somewhere in a component... -->
<Monitor name="financeapp" type="agent.mon.processMonitor">
  ...
  <Observation name="procDown">
    ...
    <Notify name="defaultNotify">
      <Parameter name="key">%{hostname}.comp1.Mon1.proc-state</Parameter>
      <Parameter name="severity">critical</Parameter>
      <Parameter name="type">fault</Parameter>
      <Parameter name="json">{"reef_label":"%{hostname} process status",
                              "reef_group":"finance-apps"}
      </Parameter>
    </Notify>
  </Observation>

  <Observation  name="procUp">
    ...
    <Notify name="defaultNotify">
      <Parameter name="key">%{hostname}.comp1.Mon1.proc-state</Parameter>
      <Parameter name="severity">info</Parameter>
       <Parameter name="type">clear</Parameter>
      <Parameter name="json">{"reef_label":"%{hostname} process status",
                              "reef_group":"finance-apps"}
      </Parameter>
    </Notify>
  </Observation>
  ...
</Monitor>

Here an application is monitored and as expected the monitor has two observations, one to detect when the process is present and one to detect when it is not.

At the top of the configuration defaultNotify is defined for reuse around the manifest. Using it as-is will send a critical, fault Reef event to reef.abilisoft.com on port 8000. No key will be set so Reef will not de-duplicate these events.

However, here we reuse defaultNotify in our observations and override the definition to:

set the event key; a key shared between observations will cause Reef to de-duplicate those events
set the event type; fault when the application fails and clear when it is available.
set the json parameter so as to set the event label and group attributes to useful values.

Note that:

An SNMP Trap (or any other action) could be sent for the same observation, duplicating event propagation over different transports
One could specify multiple <Notify/> calls to primary and fail-over Reef instances providing fault tolerance

Table Of Contents

Previous topic

Next topic

Actions¶

Trap¶

SNMPv1¶

SNMPv2c¶

SNMPv3¶

Smtp¶

Cmd¶

Control¶

Notify¶

Navigation

Table Of Contents

Previous topic

Next topic

Quick search

Actions¶

Trap¶

SNMPv1¶

SNMPv2c¶

SNMPv3¶

Smtp¶

Cmd¶

Control¶

Notify¶

Navigation