APIs in Category: alarm
 API version 5.0

 
alarm-create
alarm-destroy
alarm-get-defaults
alarm-list-info-iter-end
alarm-list-info-iter-next
alarm-list-info-iter-start
alarm-modify
alarm-test
When an event is generated in DFM, there is a mechanism to notify users of the event. This is configured through "alarms". When an alarm is triggered, DFM can notify the user in multiple ways:
  • An email message may be sent to either a specific email address or the email address associated with a DFM administrator.
  • A shortened email message can be sent to either a specific email address or the email address of a DFM administrator.
  • A script may be run. The script parameters describe the event so that automated actions can be performed in the background.
  • A SNMP trap can be sent.
In addition, alarms may be configured to only trigger at certain times of the day and for particular events, event classes, or event severities. Alarms may be configured to trigger only for certain groups of objects. Finally, alarms may be configured to repeat their notification on a regular basis so that they don't get forgotten.

NetApp Manage ONTAP
 
alarm-create [top]

Create a DFM alarm. The alarm-info element specifies all the parameters of the new alarm.

Note that it is possible to specify a combination of the event-name, event-severity and event-class such that this alarm will never be triggered. It is the user's responsibility to verify these settings are useful.

Error Conditions:

  • EINVALIDEMAILADDR - If the email address has spaces, semi-colons or unprintable characters.
  • EINVALIDEVENTSEVERITY - If the event-severity specified is not one of 'normal', 'information', 'unknown', 'warning', 'error', 'critical', 'emergency'.
  • EINVALIDEVENTCLASSEXP - If the regular expression specified for the event-class is not a valid POSIX.1 regular expression.
  • EINVALIDALARMTIME - If the time-specified for time-from or time-to is greater than 86399 ((24 * 60 * 60) - 1) seconds or if only one of time-from and time-to values are specified.
  • EINVALIDTRAPADDR - If the trap host specified is not reachable or when the port is greater than 65535 (2^15 - 1)
  • ENOSUCHEVENT - If the event name specified is not a valid event-name of DFM.
  • EGROUPDOESNOTEXIST - If the group specified in the alarm parameters is not a DFM resource group.
  • ENOTFOUNDUSER - If the administrator name specified in the alarm parameters is not a DFM administrator.
  • ERUNASUNSUPPORTED - If script-runas parameter is specified on a Windows DFM platform.
  • EINVALIDINPUT - If the event-severity value is less than the severity of the event-name event.
  • EDATABASEERROR - A database error occured during processing.
  • EACCESSDENIED - When the user does not have DFM.Event.Write capability on the resource group on which the alarm is being configured. It is also set when the user sets script-runas parameter for the alarm and he does not have global DFM.Database.Write capability.
Input Name Range Type Description
alarm-info alarm-info
Parameters of the new alarm.
 
Output Name Range Type Description
alarm-id integer
ID of newly created alarm. Range: [1..2^15-1]
 Errno  Description
 EINVALIDEMAILADDR
 EINVALIDEVENTSEVERITY
 EINVALIDEVENTCLASSEXP
 EINVALIDALARMTIME
 EINVALIDTRAPADDR
 ENOSUCHEVENT
 EGROUPDOESNOTEXIST
 ENOTFOUNDUSER
 ERUNASUNSUPPORTED
 EDATABASEERROR
 EACCESSDENIED

 
alarm-destroy [top]
Delete an alarm.

Error Conditions:

  • EALARMDOESNOTEXIST - If an alarm by the specified id does not exist.
  • EDATABASEERROR - A database error occured during processing.
  • EACCESSDENIED - When the user does not have DFM.Event.Write capability on the resource group on which the alarm being destroyed is configured.
Input Name Range Type Description
alarm-id integer
validate
Identifier of the alarm. Range: [1..2^15-1]
 Errno  Description
 EALARMDOESNOTEXIST
 EDATABASEERROR
 EACCESSDENIED

 
alarm-get-defaults [top]
Get the default values of attributes defined by this ZAPI set.
Output Name Range Type Description
alarm-defaults alarm-defaults
The default values of the attributes defined by this ZAPI.

 
alarm-list-info-iter-end [top]
Ends listing of alarms.
Input Name Range Type Description
tag string
Tag returned from alarm-list-info-iter-start.
 Errno  Description
 EINVALIDTAG

 
alarm-list-info-iter-next [top]
Returns items from list generated by alarm-list-info-iter-start.
Input Name Range Type Description
maximum integer
validate
The maximum number of entries to retrieve.
tag string
The tag returned in alarm-list-info-iter-start call.
 
Output Name Range Type Description
alarm-list alarm-info[]
Array of alarm information.
records integer
optional
The number of records actually returned. Range: [1..2^31-1].
 Errno  Description
 EINVALIDTAG

 
alarm-list-info-iter-start [top]
List all configured alarms.
Input Name Range Type Description
alarm-id integer
optional
validate
Identifier of the alarm to list. Range: [1..2^15-1]. If alarm-id is not specified, list all alarms.
 
Output Name Range Type Description
records integer
validate
Number indicating how many items are available for future retrieval with alarm-list-info-iter-next.
tag string
Tag to be used in subsequent calls to alarm-list-info-iter-next or alarm-list-info-iter-end.
 Errno  Description
 EALARMDOESNOTEXIST
 EACCESSDENIED
 EDATABASEERROR

 
alarm-modify [top]
Modify settings of a DFM alarm.

Error Conditions:

  • EALARMDOESNOTEXIST - If an alarm by the specified id does not exist.
  • EINVALIDEMAILADDR - If the email address has spaces, semi-colons or unprintable characters.
  • EINVALIDEVENTSEVERITY - If the event-severity specified is not one of 'normal', 'information', 'unknown', 'warning', 'error', 'critical', 'emergency'.
  • EINVALIDEVENTCLASSEXP - If the regular expression specified for the event-class is not a valid POSIX.1 regular expression.
  • EINVALIDALARMTIME - If the time-specified for time-from or time-to is greater than 86399 ((24 * 60 * 60) - 1) seconds or if only one of time-from and time-to values are specified.
  • EINVALIDTRAPADDR - If the trap host specified is not reachable or when the port is greater than 65535 (2^15 - 1)
  • ENOSUCHEVENT - If the event name specified is not a valid event-name of DFM.
  • EGROUPDOESNOTEXIST - If the group specified in the alarm parameters is not a DFM resource group.
  • ENOTFOUNDUSER - If the administrator name specified in the alarm parameters is not a DFM administrator.
  • ERUNASUNSUPPORTED - If script-runas parameter is specified on a Windows DFM platform.
  • EINVALIDINPUT - If the event-severity value is less than the severity of the event-name event.
  • EDATABASEERROR - A database error occured during processing.
  • EACCESSDENIED - When the user does not have DFM.Event.Write capability on the resource group on which the alarm is being configured. It is also set when the user sets script-runas parameter for the alarm and he does not have DFM.Database.Write capability at global level.
Input Name Range Type Description
alarm-info alarm-info
Parameters to be modfied for the alarm. Any value specified in alarm-info replaces values configured for the alarm. Specifying any optional attributes with a blank value removes that setting from the alarm. Specifying an empty array for attributes that take an array will remove all the entries. Specifying an array element with values replaces the existing values. If an array element is not specified, then no change happens. If none of the optional parameters are specified, then this API does nothing.

Note that it is possible to specify a combination of the event-name, event-severity and event-class such that this alarm will never be triggered. It is the user's responsibility to verify these settings are useful.

 Errno  Description
 EALARMDOESNOTEXIST
 EINVALIDEMAILADDR
 EINVALIDEVENTSEVERITY
 EINVALIDALARMTIME
 EINVALIDTRAPADDR
 ENOSUCHEVENT
 EINVALIDEVENTCLASSEXP
 EGROUPDOESNOTEXIST
 ENOTFOUNDUSER
 ERUNASUNSUPPORTED
 EDATABASEERROR
 EINVALIDINPUT
 EACCESSDENIED
 EAPIMISSINGARGUMENT

 
alarm-test [top]
Test an alarm by performing it's trigger actions. The test will be performed irrespective of whether the alarm is enabled or disabled.

Error Conditions:

  • EALARMDOESNOTEXIST - If an alarm by the specified id does not exist.
  • EALARMTESTFAILED - If there is an error sending the test alarm event to DataFabric Manager Event service.
  • EDATABASEERROR - A database error occured during processing.
  • EACCESSDENIED - When the user does not have DFM.Event.Write capability on the resource group on which the alarm is configured.
Input Name Range Type Description
alarm-id integer
validate
Identifier of the alarm. Range: [1..2^15-1]
 Errno  Description
 EALARMDOESNOTEXIST
 EALARMTESTFAILED
 EDATABASEERROR
 EACCESSDENIED

 
Element definition: alarm-defaults [top]
The default values of the attributes defined by this ZAPI.
Name Range Type Description
group-id integer
The default group id for an alarm is 0, representing the "global group". This value is returned.
is-disabled boolean
Unless otherwise specified, the is-disabled attribute is set to false when the alarm is created.
is-repeat-notify boolean
Unless otherwise specified, the is-repeat-notify attribute is set to false when the alarm is created.
repeat-interval integer
Unless otherwise specified, the repeat-interval is set to this default minimum number of seconds between repeat notifications. If is-repeat-notify is false, it does not apply. Range: [60..3932100]
trap-port integer
The default port for trap destinations. Range: [1..65535].

 
Element definition: alarm-info [top]
Information about a single alarm. This structure is used in three places: creating new alarms, modifying alarms, and listing alarms.
Name Range Type Description
admin-login-names admin-name[]
optional
Names of DFM administrators who will receive an alarm email when the alarm is triggered. The alarm email is sent to the email address configured for the administrator.
alarm-id integer
optional
validate
Identifier of the alarm. Required for list and modify, ignored on create. Range: [1..2^15-1]
alarm-script string
optional
Path on DFM station of a script to run when the alarm is triggered. The script path is not validated.
alarm-script-runas string
optional
Name of user to run alarm script. If not present, the alarm script runs with the same user ID as the DFM event process. This may only be specified as an input if alarm-script is set and may only be specified for DFM stations not running Windows.
email-addresses email-address[]
optional
Email addresses of non administrators who will receive alarm email when this alarm is triggered.
event-class string
optional
Regular expression specifying the event class of events that trigger this alarm. Only events whose event class match the regular expression will trigger the alarm. The regular expression is of POSIX.1 standard.
event-name string
optional
Event name of events that trigger this alarm. This should exactly match the short name or pretty name of the event.
event-severity obj-status
optional
Minimum event severity to trigger this alarm. If an event's severity is equal to or more severe than this value, the alarm will be triggered. Valid values are only 'normal', 'information', 'unknown', 'warning', 'error', 'critical', 'emergency'.
group-id integer
optional
DFM group id which triggers alarm. If the event source object is in this group, the alarm will be triggered. Default is 0 which is the global group. Range: [0..2^31-1]
group-name string
optional
DFM group name which triggers alarm. If the event source object is in this group, the alarm will be triggered. This is returned in the output of alarm-list. If group-id element is not present during input, then this element is considered. If both group-id and group-name are not present, then the alarm is configured for global group.
is-disabled boolean
optional
Whether this alarm is disabled. If it is disabled, it will never be triggered. Default value is false.
is-repeat-notify boolean
optional
Whether to repeat the notification for this alarm if the triggering event is not acknowledged. Default value is false.
pager-admin-login-names admin-name[]
optional
Name of DFM administrators who will receive a shortened alarm email. The email messages are formatted to be easy to read on a pager. The alarm email is sent to the pager email address configured for the administrator.
pager-email-addresses email-address[]
optional
Email addresses of non administrators who will receive shortened alarm email. The email messages are formatted to be easy to read on a pager.
repeat-interval integer
optional
validate
Seconds between repeat notifications of the alarm. This will only be returned if repeat-notify is true and may only be specified as an input if is-repeat-notify is set to true. The value is rounded off to the nearest minute. It can have a maximum value of 65535 minutes. Default value is 1800 seconds (30 minutes) Range: [60..3932100]
time-from integer
optional
validate
Start time of day when alarm may be triggered, in seconds since Midnight UTC. The value is rounded off to the nearest minute. The default is to always trigger the alarm. Range: [0..86399]
time-to integer
optional
validate
End time of day when alarm may be triggered, in seconds since Midnight UTC. The value is rounded off to the nearest minute. The default is to always trigger the alarm. time-to value is generally greater than time-from value. If it is lesser than time-from value, then it is considered as inverted time-range. In this case, if the values of the fields are 20:00 and 2:00, then the alarm is triggered between 0:00 and 2:00 and 20:00 to 23:59. Range: [0..86399]
trap-destinations trap-destination[]
optional
IP address or host name, SNMP community and port to which a SNMP trap is sent as part of this alarm.

 
Element definition: admin-name [top]
The name of a DFM administrator to receive alarm notifications.
[none]

 
Element definition: email-address [top]
A single email address. It cannot contain spaces, semi-colons or unprintable characters.
[none]

 
Element definition: obj-status [top]
A status value which can be associated with a DFM object. This typedef is an alias for the builtin ZAPI type string. The severity associated with an event has this type.

Possible values are: 'unknown', 'normal', 'information', 'unmanaged' 'warning', 'error', 'critical', 'emergency'.

  • unknown: An object has an unknown status when it transitions from one state to another. Ideally, an object will have this status briefly. For example, when an object has been added, but not yet discovered.
  • normal: An object has normal status when it is working within the thresholds specified in DFM.
  • information: The information events are normal occurrences on an object for which you can define alarms.
  • unmanaged: An object is considered to be unmanaged when the login and password are not set for the storage system or agent.
  • warning: An object has the warning status when an event related to the object occurred that an administrator should know about. The event will not cause service disruption.
  • error: An object has error status when it does not cause any service disruption, but it may affect performance.
  • critical: An object has critical status when it is still performing, but service disruption may occur if corrective action is not taken immediately.
  • emergency: An object is in emergency status when it stops performing unexpectedly and could lose data.
In some contexts, it is important that severities are ordered (as above). For example, an alarm might be triggered if an event with a given severity "or worse" occurs. In this example, worse means "after" in the list above.
[none]

 
Element definition: trap-destination [top]
Destination parameters for a SNMP trap.
Name Range Type Description
trap-community string
optional
SNMP community to use when sending trap. Default is "public".
trap-host string
Hostname or IP address of trap destination.
trap-port integer
optional
validate
Port number where to send trap. Range: [1..65535]. Default value is port 162.