|
|
evmchannel.conf(4)
Contents
|
evmchannel.conf - EVM channel configuration file
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
}
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: 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. 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
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 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]
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 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.
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 upperand
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
-----------------------
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.
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/channels/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/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.
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)
[ Back ] |
