You are here: Administration > Man Pages > sendevent(5)

sendevent(5)

NAME

sendevent(5) — initiate application-specific response to an alarm/event

SYNOPSIS

LKROOT/bin/sendevent -C class-of-event -E event -m monitor-name -n name-of-obj-inst [-c class-of-obj] [-i id-of-alarm/event] [-t YYMMDDHHMMSS][-T timestamp] [-s severity] [-o] [-z] [-w] [-a alarm/event-type] [-P problem-type] [-p problem-code] [-d problem-data] [-x problem-text] [-S system-name] [-O outfile-actfiles]

DESCRIPTION

The event notification facility consists of two parts: an event notification mechanism ($LKROOT/bin/sendevent) and an application registration environment.  Applications wishing to use the event facility should "register" to get notification of specific events or alarms (or all occurrences of event/alarms).

The sendevent command is a program invoked by a Linux daemon monitor process when the monitor has detected an event (failure or recovery) in the objects that it is monitoring. This command is not intended to be run directly at the shell level by a regular user or by a system administrator (only by a daemon process or another command). The sendevent command is used to notify a "registered" application of the occurrence of an event. For example, an application may want to be notified of an impending system shutdown so as to appropriately save files and data; or, in a client-server environment, the application may need to reconfigure itself to an alternate service provider.  The application is responsible for providing the appropriate command support to handle the event.

The sendevent command passes all of its options to the event-response commands of the application.

An application will register to receive notification of events or alarms by installing its event-response commands in a specific registration directory, $LKROOT/events. This should be done at application installation time. The application should install executable files using the same name given to the application and as supplied in the /usr/options directory with the .name suffix removed and truncated to 14 characters. The events under $LKROOT/events are further categorized in classes of events.  Each event class is represented by a separate subdirectory with the gen class (for general events) being the only class installed by default by the base system. A class called all is used by applications to register to be notified upon occurrence of any event. Note that if an event occurs such that an application has registered (that is, placed application-response commands) in both the specific event location and the all location, both scripts will be run. Each class directory contains a subdirectory for each event within that class. Each add-on package that monitors events and uses this event notification mechanism will document the events that it monitors and supports.

It is the responsibility of the application object monitor package to maintain a file called ACTIVE in the events subdirectories. If the ACTIVE file exists, it is a signal to the applications that a monitor is currently actively running and monitoring its objects for that specific event. If the package containing the monitor program is removed, the files named ACTIVE for the affected monitored events are removed too (by the package remove script) to indicate to applications that the event is no longer being monitored. The removal of the package should not remove event-response commands or event directories even if they are empty.

An example event is the shutdown event that appears under the gen class.  Applications wishing to be notified of an impending (administrative) system shutdown (that is, a shutdown started by the shutdown command) will install their event-response commands in the $LKROOT/events/gen/shutdown directory.

For those applications that may depend on standard commands from another application, the application registration environment provides other application-specific directories, $LKROOT/sybsys/application-name/actions, for applications to place "sharable" action commands. The application-name is the same name the application supplies in the /usr/options directory with the .name suffix removed and truncated to 14 characters. For example, application X may depend on application Y being up and running after an event recovery. If this is not the case, application X may invoke application Y's start command found in the directory $LKROOT/subsys/Y/actions/start.  Interdependencies between applications must be resolved and specified by the application developers.

The -C (class of event), -E (event), -m (monitor name), and -n (name of object instance) options are required. If the -s (severity) option is not specified, sendevent will default to a severity of MAJOR alarm. If the -c (class of object) option is not specified, sendevent will internally add a default object class of EQUIPMENT alarm. If either the -a (alarm/event type) or -P (problem type) options are not specified, sendevent will internally add defaults that depend on the -c (class of object) option (see DEFAULTS section). The option -A (advise of recovery) is reserved for sendevent to add internally and cannot be specified as an option to sendevent. All other options are optional. They are used to pass event-specific information from the event monitoring process to the application event-response commands. It is the responsibility of the application event-response commands to parse, interpret, or ignore these optional options.

The syntax and meaning of any future new options should be worked out between the developers of the event monitoring processes and the application developers. Note that sendevent ignores all options not shown in the SYNOPSIS section and passes them unchanged to the event-response commands.

Upon invocation of the sendevent command by a monitoring process, sendevent will determine which event class and event has occurred based on the arguments to the -C and -E options. The sendevent command will execute in the background (unless the -w option is used) all the event-response commands (if any) that have been placed in the registration directory corresponding to that class/event pair and all of the commands registered in the all directory.

The following options are supported:

Required Options:

-C class-of-event

Events are grouped together into classes. This required option indicates which class the event belongs to.

-E event

This required option indicates which event in class is being triggered.

-m monitor-name

Each application object monitor that can send alarms/events is identified by a name of the form:

OM-product-name:OM-component-name

OM-product-name is an ASCII string up to 8 characters long that is an abbreviated identifier specifying the product that monitors the objects that cause alarms or events. OM-component-name is an ASCII string up to 16 characters long that is defined by the object monitor. It is generally used to identify the component of the object monitor that detected the alarm or event.

For example, COREUNIX:SCSI-FM would identify the "Core Unix" product (COREUNIX) and the Small Computer System Interface (SCSI) Fault Monitor component. The "monitor names" are used to distinguish between different products that may be used to monitor the same object.

-n name-of-obj-inst

This option is used to name a specific instance of an application object.  It is an ASCII string of maximum length 64 characters. For example, /usr maybe the name of a file system application object, whereas 1234 could be used to identify a specific Unix process object.

Options Internally Added by sendevent

-c

The -c option specifies what class the object causing the event belongs to.  The representation of an object class is by an object identifier which consists of a sequence of sub-identifiers of the form .integers.

For example, the option .0.3.3134.0.8.1.21 represents the software object class as defined in the Accumaster Integrator Alarm Interface (AIAI) specifications.

Object classes are defined by standards bodies, or by individual product developers for private use. sendevent will accept any syntactically correct, fully qualified object identifier up to a maximum of 64 characters in length.

The object classes currently defined by the AIAI specification begin with the prefix ".0.3.3134.0.3.1." and have the suffix as follows:

3

circuit

9

equipment (default)

12

facility

15

multipoint circuit

21

software

34

LAN

An object class may be specified as a fully qualified set of sub-identifiers or by a 1- or 2-digit suffix, and the AIAI prefix will be automatically prepended to the suffix. If the argument to this option contains at least one dot (.) character, sendevent assumes the argument is fully qualified. Note that sendevent only checks the object class to make sure it contains only "." and digit characters and is less than 64 characters. It does not check if it is a valid object class.

-s severity

Each alarm or event must specify the severity of the problem it is reporting. If this option is not specified, sendevent will internally add a default severity for MAJOR alarm. Severity is an ASCII represented integer interpreted as follows:

0

CLEARED alarm specified by "id-of-alarm/event" has been recovered

1

INFORMATIONAL alarm (INFO message or Unix cmn_err() NOTICE message)

2

WARNING: alarm (WARNING: message)

3

MINOR alarm (MINOR message)

4

MAJOR alarm (MAJOR or ERROR message) (default)

5

CRITICAL alarm (CRITICAL message or Unix cmn_err() PANIC or HALT message)

-a alarm/event-type

This option specifies the type of alarm or event. If the option is not specified, sendevent will internally add a default alarm or event type that depends on the object class (see DEFAULTS section). The currently acceptable values are as follows:

1

Transmission alarm

2

Equipment alarm

3

Software alarm

-P problem-type

Within each alarm or event type, a problem is classified into one of several problem types. The following tables specify standard problem types which track the "Unified Network Management Architecture" (UNMA) standards. If the option is not specified, sendevent will internally add a default problem type that depends on the object class (see DEFAULTS section).

Problem Types for Software Alarms

0

Storage capacity

1

Memory mismatch

2

Corrupt data

3

Out of CPU cycles

4

Software Environment

Problem Types for Equipment Alarms

0

Power problem

1

Clock problem

2

Trunk card problem

3

Line card problem

4

Processor problem

5

Terminal problem

6

Environment problem

7

External device problem

8

Modem problem

9

Multiplexer problem

10

Switch problem

Problem Types for Transmission Alarms

0

Loss of signal

1

Framing Error

2

Transmission Error

3

Call set up failure

4

SSCP-SSCP failure

5

SSCP-PU failure

6

SSCP-LU failure

7

LU-LU failure

 

Suggested Application Options:

-i id-of-alarm/event

The -i option specified an integer number that acts as an identifier of the specific alarm or event. The sendevent command normally assigns an identifier to the event that is guaranteed to be unique by automatically adding and -i option to the argument list passed to all event-response commands. The identifier assigned is a number that is guaranteed to increase by one with each invocation of sendevent.

There are two situations when an object monitor would directly use the -i option. The first situation is when the severity of the event is set to CLEARED (indicated by a -s 0 option). In this instance, the -i option identifies the alarm/event as one that has already occurred, but has now been recovered from. The second situation is when an object monitor determines it should escalate the severity of a previously occurring alarm/event, the object monitor should reuse the id-of-alarm/event used previously.

Note that sendevent prints the id-of-alarm/event to stdout so that the object monitor can determine the id-of-alarm/event assigned to the event by sendevent, in case it needs to later clear it with the -s 0 option or escalate the severity.

For example, the RMP daemon monitor process may detect a "thermal warning" condition and trigger a tempwarn event for the thermal class the first time the event is detected. The sendevent command assigns an id-of-alarm/event of 1234 to the event (note that sendevent passes the id-of-alarm/event to the RMP monitor by printing it to stdout). If the RMP monitor later determines that the temperature has cooled below a predetermined threshold, the initial condition no longer exists. The applications are notified of the event recovery by the RMP monitor invoking the sendevent command with the -s 0 and -i 1234 options for the tempwarn event.

-o

This option is used to indicate that the failure or alarm that triggered the event is old. For example, if a monitor discovered a failure condition in a log file that had a timestamp of two hours ago, the failure may represent old information that had already been responded to manually.

-t YYMMDDHHMMSS

The argument to -t indicates a timestamp giving the date and time in UTC (GMT) format (YYMMDDHHMMSS) at which the alarm occurred. Remember the time is not local time, but Greenwich Mean Time (GMT).

-T timestamp

The argument to -T indicates a timestamp when the alarm or event occurred, but here it is given as the number of seconds since 00:00:00 UTC (GMT), January 1, 1970.

-O outfile-actfiles

By default, stdout and stderr of the event-response commands are redirected to /dev/null. This option specifies a file name where the stdout and stderr should be appended. Note that if there are more than one event-response commands, all of their output will be appended to the specified file. The file can also be a special device file such as /dev/console or /dev/tty, if the output needs to be directed to a terminal. Note that the stdout and stderr of the sendevent program is handled separately from the event-response commands.  This option has no effect on stdout and stderr.

-S system-name

This option indicates the system name associated with an event. The system-name is the string returned by the Linux uname(1) program or uname(2) system call.

-p problem-code

problem code is an ASCII string with a maximum length of 32 characters that uniquely identifies the problem. It is product specific, and is intended to allow application event-response commands to determine the exact problem without having to scan the unstructured problem text. It is usually an integer, although sendevent will accept any string. For example, this may be a SCSI error code. sendevent passes this string uninterpreted to application event-response commands.

-d problem-data

Each alarm or event may carry qualifying data about the condition. For example, a "filesystem space low" may carry the actual current available space in the option argument, or a process running too long may carry the command name of the process, or a system shutdown event may carry the number of seconds remaining before a system shutdown. problem-data is represented as an ASCII string of up to 64 characters. problem-data is problem specific, and may be used by applications to take corrective action. sendevent does not interpret the contents of this field, but passes it transparently to application event-response commands. Remember that if problem-data contains spaces, the string must be either single- or double-quoted to be interpreted correctly by the Linux shell.

-x problem-text

A readable free-format text message describing the alarm condition.  Remember that if problem-text contains spaces, the string must be either single- or double-quoted to satisfy the Linux shell option rules. It is an ASCII string with a maximum length of 160 characters.

The difference between problem-text and problem-data is that the problem-data may not necessarily provide easy-to-understand information, while the problem-text will be readable. The application response commands may choose to display the problem-text (if available) on the screen.

-z

If this option is present, it signifies that the message triggering this alarm/event appeared in Unix cmn-err() format.

-w

If this option is present, sendevent will wait for each event-response command to complete before starting another event-response command. Otherwise, all event-response commands are run nohup(1) and in the background. Note that in both cases, stdout and stderr are redirected to /dev/null.

DEFAULTS

If the -c options or object class is not specified, an object class of equipment will be used.

The default for alarm type and problem type changes depending on what the object class is either set or defaulted to:

object class is set or defaulted to:

alarm type defaults to:

problem type defaults to:

circuit

transmission

loss of signal

equipment

equipment

processor

facility

transmission

call set-up error

multipoint circuit

transmission

call set-up error

software

software

software environment

LAN

transmission

loss of signal

If the object class is "fully qualified" (the argument to -c option contains a "." character), or if the "object class" suffix is not one of the object classes in the above table, then the "alarm type" defaults to equipment and the "problem type" defaults to processor.

OUTPUT

The output this command generates occurs in one of two conditions:

  • Error messages are printed to Unix stderr and a nonzero exit code is returned.

  • The identifier for the alarm/event called id-of-alarm/event is printed to Linux stdout at each call to sendevent.

EXAMPLES

  1. The following is an example of how notification of an administrative system shutdown is sent from shutdown via sendevent to registered applications:

/opt/LifeKeeper/bin/sendevent -C gen -E shutdown -m COREUNIX:ADMIN -c 21 -n shutdown -s 5 -d 30

where "30" (30 seconds) represents the grace time period specified in the shutdown.

Assume two applications (StarGROUP and SCSI) have registered to receive notification of this event by placing event-response commands called stargroup and SCSI in the file /opt/LifeKeeper/events/gen/shutdown. Then, the following processes would be run in the background by sendevent:

nohup /opt/LifeKeeper/event/gen/shutdown/stargroup -a 3 -P 4 -C gen -E shutdown -m COREUNIX:ADMIN -c .0.3.3134.0.8.1.21 -n shutdown -s 5 -d 30 -i 23 &

nohup /opt/LifeKeeper/events/gen/shutdown/SCSI -a 3 -P 4 -C gen -E shutdown -m COREUNIX:ADMIN -c .0.3.3134.0.8.1.21 -n shutdown -s 5 -d 30 -I 23 &

  1. The next example is where the monitor process detects a "temperature warning" condition for the thermal event class and how it would call sendevent to communicate this event:

/opt/LifeKeeper/bin/sendevent -C thermal -E tempwarn -m RMP:RMC_FM -n /dev/rmc0 -P 6

If the LMX application has registered to be informed of this event and recovery is in the process of being performed (possibly by optional software that ensures system availability), sendevent would invoke the event-response command as follows:

nohup /opt/LifeKeeper/events/thermal/tempwarn/LMX -c .0.3.3134.0.8.1.0 -a 2 -C thermal -E tempwarn -m RMP:RMC_FM -n /dev/rmc- -P 6 -I 2019 -s 4 -A &

EXIT CODES

The following exit codes are returned by sendevent:

0

The sendevent command has completed successfully without errors.

1

Syntax error in the argument list.

2

No class corresponding to the string passed with the -C option exists in the /opt/LifeKeeper/events directory.

3

No event corresponding to the string passed with the -E option exists in the /opt/LifeKeeper/events/<class> directory.

4

The -A option is internally generated and may not be specified directly.

5

The -i option must be specified if the -s 0 (severity CLEARED) option is used.

NOTES

The location of this utility, LKROOT, is defined in the default file/etc/default/LifeKeeper.

FILES

/etc/default/LifeKeeper

© 2012 SIOS Technology Corp., the industry's leading provider of business continuity solutions, data replication for continuous data protection.