Adding an Event Channel to EVM

The Get Function

The channel get function is executed by the EVM get_server, which is executed by the EVM daemon to handle event retrieval requests made through evmget. This function is always executed as superuser and must take appropriate security precautions.

The function must support the following invocation syntax:

function-name [-f filter-string]

If required, other arguments may be passed to the function by including them in the function's line in the channel configuration file.

When you run the get function, it performs the following actions:

If a filter-string is supplied, only events that match the filter can be written to stdout. Error messages can be written to stderr and are passed back to evmget for output to its stderr stream. Hence, ensure that they are clearly identified as originating in this function. Do not write anything other than EVM events to stdout.

The form of a get script depends on the form in which the native events are stored. Complete the following steps:

If your channel's log files are difficult to convert to EVM format — for example, because each entry is made up of multiple unstructured lines of text, which cannot be parsed easily — do not supply a get function, instead allow the events to be logged by the EVM logger as they are posted. This consumes more storage space, because the events are stored in two places, but it may significantly improve retrieval time and programming effort.

If you supply your own get function for the channel, be sure to change the filter strings in the EVM logger's configuration file, so that your events are not duplicated in the EVM log. For more information on how to change the logger's configuration file, see the HP_UX System Administration document.

The Details Function

The details function is invoked by evmshow command line with -d option. Although the function is currently run with the privileges of the user running evmshow, it is likely to change in a future release. Hence, it is important that the function takes appropriate security precautions.

The function must support the following invocation syntax:

function-name [arguments]

If arguments are specified in the details function line in the channel configuration file, they are passed directly to the function when it is executed. The details function must accept a stream of EVM events through stdin, and display a stream of text on stdout that describes the contents of each event. Various forms of evmshow (notably -x and -D) are likely to be useful in producing the output. However, you must not use the -d option because it results in a recursive loop.

Unless redirected, messages written to stderr appears on evmshow's stderr stream. Hence, if needed, they must be clearly identified as being written by this function.

You can use the evmlog channel function, /usr/share/evm/channels/evmlog/evmlog_details as a model for developing a details script for a new channel. If you do not supply a details function, evmshow displays a formatted dump of the contents of any event belonging to the channel whenever a detailed view is requested.

The Explain Function

The explain function is executed by evmshow when the command is invoked with the -x option. Although it is currently executed with the privileges of the user executing evmshow, this is likely to change in future release. Hence, it is important that the function takes appropriate security precautions. The function must support the following invocation syntax:

function-name event-name [reference]

The explain function is invoked with the name of the event requiring explanation and an optional reference value. If supplied, the reference is the contents of the event's reference data item. If no reference is available, evmshow passes a hyphen (-) for this argument, but the function must also allow the argument to be omitted.

The explain function must use its arguments to produce a formatted explanation for the supplied event name, and write it as lines of text to stdout. If no explanation can be found, an appropriate message must be written to stdout in place of the explanation. Unless redirected, messages written to stderr appears on evmshow's stderr stream. Hence, if they are needed, they must be clearly identified as being written by this function.

Your explain function can invoke the evmlog explain function, /usr/share/evm/channels/evmlog/evmlog_explain, provided the following conditions are met:

The message catalog must be located according to normal I18N rules. To minimize search time, group the explanations into sets and provide the set numbers in the reference data items of the events. For information about procedures to generate a catalog file, see mkcatdefs(1) and gencat(1).

The Monitor Function

The monitor function is executed by the EVM channel manager. It is executed with an -init argument when the channel manager starts. Each time the channel manager is reconfigured with evmreload, execute the function without the -init argument. The execution period is controlled with the mon_period channel value. This function is always executed as superuser and must take appropriate security precautions.

The function must support the following invocation syntax:

function-name [init]

You can use the presence or absence of the Init argument to decide whether the function needs to initialize any work files that it has to maintain. If required, you can pass additional arguments to the function by including them on the command line in the channel configuration file.

	NOTE: The init argument is always passed as the last argument.

There are no restrictions on the actions that can be taken by the monitor function, although its job is to check the status and post events if it detects a change of state.

The function is invoked with no stdout and stderr assigned to the channel manager's log file. If the function does not reassign stderr, any messages written to it must have the same format as the channel manager's log entries and must be clearly identifiable as coming from your channel. Alternatively, you can post error messages as EVM events. However, you must not report the same condition unnecessarily each time the function in invoked.

Example 4-11 “ Sample Monitor Script” illustrates the monitor script that initializes itself by counting the number of lines in a log file, and saving the count in a state file. On subsequent invocations, it compares the number of lines in the file with the previous number, extracts each new line with the UNIX tail command, and posts it as an EVM event with evmpost.

Example 4-11  Sample Monitor Script

#! /bin/shINIT=$1STATE=/tmp/mylog.stateLOG=/tmp/mylogEVENT_NAME=sys.unix.evm# No log? Create one!if [ ! -f $LOG ]then touch $LOGfi# If we're initializing then save the current logfile# state and exit:if [ "$INIT" != "" ]then # Count the lines in the demolog, and save the count# in the state file: wc -l $LOG | awk '{print $1}' > $STATE exitfi# Find out how many lines there were in the file last time# we checked:OLDCOUNT=`cat $STATE`# How many now?NEWCOUNT=`wc -l $LOG | awk '{print $1}'`if [ $NEWCOUNT > $OLDCOUNT ]then # Save the new line count to the state file: echo $NEWCOUNT > $STATE# What's the difference between the old and new counts? diff=`expr $NEWCOUNT - $OLDCOUNT | awk '{print $1}'`# Post an event for each new line:tail -$diff $LOG | while read LINE do echo 'event { name '${EVENT_NAME} \ ' var {name msg type STRING value "'$LINE'"} }' | evmpost donefi

The Cleanup Function

The cleanup function is executed daily by the EVM channel manager, at the time specified in the channel configuration file, to perform housekeeping actions such as archiving and deleting the channel's log files. This function is always executed as superuser and must take appropriate security precautions.

The cleanup function can be run from the command-line along with the arguments. The function is allowed to take whatever action is appropriate. It is executed with no stdout or stderr assigned to the channel manager's log file. Hence, any desired status messages must generally be issued in the form of EVM events by using evmpost, instead of being written to stderr. If the function does not reassign stderr, any messages written to it must have the same format as those written by the channel manager and must be clearly identifiable as coming from your channel. Nothing must be written to stdout.

Write the function so that it has the same effect regardless of the time of day at which it is run. For example, it can use the -m time option of the find command to identify log files to be archived.

Channel Security

In most cases, channel functions are executed by processes that are children of the EVM daemon, and, as a result, they are run with full root privileges. Hence, you must protect your system's integrity by ensuring the following: