 |
Index for
Section 4 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
evmchannel.conf(4)
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(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:
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. 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 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.
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) reference page 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.
______________________
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 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 command evmshow -d 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 command evmshow -x 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
Commands: evmget(1), evmshow(1), evmchmgr(8), evmd(8)
Files: evmdaemon.conf(4), evmlogger.conf(4)
Event Management: EVM(5)
Event Filter: EvmFilter(5)
|
Index for
Section 4 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|