evmchannel.conf(4)evmchannel.conf(4)NAMEevmchannel.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 avail‐
able 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 explana‐
tion 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(8), evmshow(1) and evmget(1) reference pages 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: The ch_path variable specifies a
default directory containing executable programs that perform the vari‐
ous channel functions. This path may be overridden by a ch_path vari‐
able 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. 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. Speci‐
fies 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 match‐
ing 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 chan‐
nel 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 the get_functions
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 con‐
figured 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 giv‐
ing 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]
The event's name. 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) reference page 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 fre‐
quency defined by the channel's monitor_period value. The pro‐
gram 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 start‐
ing 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 argu‐
ments.
If the fn_cleanup keyword is omitted from a channel definition,
no cleanup function is run on behalf of that channel. The moni‐
tor_period value determines the frequency at which the monitor
function will be run for a particular channel. It has the fol‐
lowing 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 abso‐
lute, 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 char‐
acters is shown in the following table. A minimum of zero (0) indi‐
cates that all characters are required.
───────────────────────
Keyword Minimum
───────────────────────
channel 4
cleanup_time 0
events 5
fn_cleanup 8
fn_details 0
fn_explain 6
fn_get 0
fn_monitor 6
mon_period 0
name 0
path 0
───────────────────────
NOTES
If you are concerned with allowing your file to be used on other sys‐
tems 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: 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 command evmshow -d encounters an event in
this class, the program /var/evm/adm/chan‐
nels/my_events/my_events_details is invoked to provide the detailed
description. Whenever the command evmshow -x encounters an explanation
for an event in this class, the program /var/evm/adm/chan‐
nels/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.
FILES
Location of the EVM channel configuration file.
SEE ALSO
Commands: evmget(1), evmshow(1), evmchmgr(8), evmd(8)
Files: evmdaemon.conf(4), evmlogger.conf(4)
Event Management: EVM(5)
Event Filter: EvmFilter(5)evmchannel.conf(4)
