evmchannel.conf(4)

The ch_path variable specifies a default directory containing executable programs that perform the various channel functions. This path may be overridden by a ch_path variable specified for an individual event channel. The syntax for a global path and a channel specific path are the same.

The time of day when the EVM channel manager executes the channel cleanup function, specified by the fn_cleanup keyword, for each channel. If no cleanup time is specified, the default is 2:00 a.m. local time. For example, cleanup_time 02:00:00. The channel manager executes cleanup functions sequentially.

The channel keyword introduces a channel definition. The configuration keywords and values for each channel must be enclosed in braces. There is no limit to the number of channel definitions that can be included in the file.

Specifies a name to be associated with the event channel. The name can include any printable character.

The class of events associated with this channel. The evt_class is a dot delimited field with the same syntax as an event name.

When evmshow is run with the -d or -x option, it must find an event channel matching each event it receives, so that it can determine which channel function to run. The program scans the evt_class value of each configured channel in turn, in the order in which they appear in the configuration file, searching for a class that exactly matches the first few components of the event's name. It stops searching when it finds the first matching channel, and does not attempt to find a better match.

If a star (*) is supplied as the evt_class the channel is regarded as the default channel, meaning that its functions will be invoked to provide details and explanations for any events whose names do not match the evt_class for any other channel. The default channel should be specified as the last channel in the file, since no further searching takes place once this channel has been found.

The get_function parameter identifies an executable program that is invoked by the evmget server program each time evmget is run. The server executes get_function for each channel in turn, in the order in which the channels appear in the configuration file. If the fn_get keyword is omitted from a channel definition, no events are retrieved for that channel.

A get_function program must return a stream of zero or more EVM events to its stdout, directing any error messages to stderr for display on evmget's error stream. The program is executed as specified in the configuration line, including any arguments, but must accept an optional -f option and a filter string as trailing arguments. If a filter is supplied, the program must return only events that match the filter. See EvmFilter(5) for more information about filters.

When evmshow is invoked with the -d option, for each event it receives it searches the configured channels for one whose evt_class matches the event's name, and then executes the program defined as the channel's details_function. The program should output lines of text giving a detailed view of the contents of the event.

If the fn_details keyword is omitted from a channel definition, evmshow -d produces a formatted dump of any events it receives that belong to the channel.

A details_function program must accept EVM events on stdin, and output text to stdout. Error messages must be directed to stderr, for display on evmshow's error stream. The program is executed as specified on the configuration line, including any arguments.

When evmshow is invoked with the -x option, for each event it receives, it searches the configured channels for one whose evt_class matches the event's name, and then executes the program defined as the channel's explain_function. The program should output lines of text explaining the meaning of the event and, if appropriate, any necessary action. Error messages may be written to stderr, for display by on evmshow's error stream.

If the fn_explain keyword is omitted from a channel definition, evmshow -x displays a message in place of an explanation for any events it receives that belong to the channel.

An explain_function program must support the following command syntax:

my_events_explain event_name [reference]

Refer to the EvmEvent(5) manpage for more information about an event's name and ref data items.

The monitor function provides a mechanism for monitoring the status of a channel and posting events as necessary.

When the EVM Channel Manager (evmchmgr) is started by the EVM daemon, it searches the channel configuration file for channels that define a monitor_function program. The channel manager runs each monitor_function program, including any arguments present in the configuration line, and with the value -init appended as a trailing argument. The channel manager executes each program periodically thereafter, without the -init argument, at the frequency defined by the channel's monitor_period value. The program should use the presence or absence of the -init argument to decide whether it must perform any initialization work.

The purpose of the monitor program is generally to check status and to post events if it detects a significant change of state, although it is not restricted to this type of activity. The program should not write to stdout or stderr, and since the channel manager waits for the program to complete before starting the next action, the program should execute as quickly as possible.

A monitor_function program must support the following command syntax:

my_events_monitor [program_specific_arguments][-init]

If the fn_monitor keyword is omitted from a channel definition, no monitoring function is run on behalf of that channel.

The cleanup_function identifies an executable program that is invoked daily by the EVM Channel Manager at the time specified by cleanup_time.

The purpose of the cleanup program is generally to archive or purge old log information, although it is not restricted to this type of activity. The program should not write to stdout or stderr, and since the channel manager waits for the program to complete before starting the next action, the program should execute as quickly as possible.

The channel manager executes the cleanup command as specified in the configuration line, and does not supply additional arguments.

If the fn_cleanup keyword is omitted from a channel definition, no cleanup function is run on behalf of that channel.

The monitor_period value determines the frequency at which the monitor function will be run for a particular channel. It has the following syntax:

[[[days:]hours:]minutes:]seconds

All fields are optional, but the appropriate number of colon characters (:) must be included in order to specify the higher-order components, for example, 1: would be interpreted as one minute and zero seconds. The days, hours, and minutes components can be any integer up to 9999, and seconds can be any integer up to 9999999. Omitted values are interpreted as zero. It is acceptable to exceed the natural limit for any component, regardless of what other components are included: for example, 90 is interpreted as 90 seconds, and 1:90 is interpreted as 150 seconds.

A monitor period of zero is valid, and causes monitoring of the channel to be disabled.

The cleanup program for this and all other defined channels will be run at 3:00 a.m. each day.

The event channel has the name my_events.

All channel functions are found in a directory named /var/evm/adm/channels/my_events.

This channel applies to events having myco.myapp.my_events as the first three components of their names.

Whenever evmget is run, the program /var/evm/adm/channels/my_events/my_events_get is invoked to retrieve events of this class. The arguments -r 8 are passed to the program each time it is executed -- these arguments may be followed by -f and a filter string.

Whenever the evmshow -d command encounters an event in this class, the program /var/evm/adm/channels/my_events/my_events_details is invoked to provide the detailed description.

Whenever the evmshow -x command encounters an explanation for an event in this class, the program /var/evm/adm/channels/my_events/my_events_explain is invoked to provide the explanation.

The program /var/evm/adm/channels/my_events/my_events_cleanup is run daily at 3:00 a.m. The arguments 7 and 31 are passed to the program each time it is executed.

The channel manager invokes the function /var/evm/adm/channels/my_events/my_events_monitor on startup (with the -init parameter) and every 15 minutes thereafter.

Location of the EVM channel configuration file.