Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > E

evmchannel.conf(4)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

evmchannel.conf — EVM channel configuration file

SYNOPSIS

path ch_path cleanup_time [[hh:]mm:]ss channel { name ch_name path ch_path events evt_class fn_get get_function [arguments] fn_details details_function [arguments] fn_explain explain_function fn_monitor monitor_function [arguments] fn_cleanup cleanup_function mon_period monitor_period }

DESCRIPTION

The term event channel describes any facility used to publish or retrieve event information. It might refer to any of the following:

  • A simple log file

  • An event management system

  • A program that runs in order to obtain a snapshot of status information

The EVM channel configuration file, evmchannel.conf, defines the available event channels and the functions that operate on them. The file is read by:

  • The EVM channel manager, /usr/sbin/evmchmgr, to identify the available channels, and to determine when to run monitoring and cleanup functions.

  • The evmshow command, when it is invoked with the -d or -x option, to identify the channel to which each event belongs, and the program that must be run to produce a detailed view or an explanation of the event

  • The evmget server program, /usr/sbin/evmget_srv, to identify the available channels and their event retrieval functions

Refer to the evmchmgr(1M), evmshow(1), and evmget(1) manpages for more information.

The channel configuration file is a text file containing keyword/value or keyword/group pairs. Values containing spaces must be enclosed in double quotes.

Any portion of a line from an unquoted number sign (#) to the end of line is a comment. Blank lines are ignored.

The following keywords are recognized:

path ch_path

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.

cleanup_time [[hh:]mm:]ss

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.

channel

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.

name ch_name

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

events evt_class

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.

fn_get get_function [arguments]

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.

fn_details details_function [arguments]

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.

fn_explain explain_function

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]

event_name

The event's name.

reference

The event's ref data item, if it has one. This value is intended to be used in conjunction with the event name to retrieve the explanation for the event from a database of explanation text.

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

fn_monitor monitor_function [arguments]

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.

fn_cleanup cleanup_function

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.

mon_period monitor_period

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.

Each ch_path specified may be either relative or absolute. The path is prepended to each function specified unless the function specifier is absolute (begins with a slash). If the function specifier is not absolute, then standard search rules are applied to find the executable file.

The keywords described may be entered in any mix of upper- and lower-case characters. The allowable strings and the minimum number of characters is shown in the following table. A minimum of zero (0) indicates that all characters are required.

KeywordMinimum
channel4
cleanup_time0
events5
fn_cleanup8
fn_details0
fn_explain6
fn_get0
fn_monitor6
mon_period0
name0
path0

Notes

If you are concerned with allowing your file to be used on other systems that support EVM in the future, you should use the built-in macro @SYS_VP@ in place of the first two components (sys.unix) of the name of any system event. This will make it unnecessary to change the file if the other system uses a different event name prefix.

EXAMPLES

The following is an example of a channel configuration file:

cleanup_time 03:00:00 channel { name my_events path /var/evm/adm/channels/my_events events myco.myapp.my_events fn_get "my_events_get -r 8" fn_details my_events_details fn_explain my_events_explain fn_monitor my_events_monitor fn_cleanup "my_events_cleanup 7 31" mon_period 15:0 }

The channel configuration file does the following:

1.

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

2.

The event channel has the name my_events.

3.

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

4.

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

5.

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.

6.

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.

7.

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.

8.

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.

9.

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.

FILES

/etc/evmchannel.conf

Location of the EVM channel configuration file.

SEE ALSO

Event Management

EVM(5).

Event Filter

EvmFilter(5).

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.