evmchannel.conf(4)evmchannel.conf(4)NAMEevmchannel.conf - EVM channel configuration file
SYNOPSISDESCRIPTION
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, defines the available event chan‐
nels and the functions that operate on them. The file is read by:
· The EVM channel manager, to identify the available channels,
and to determine when to run monitoring and cleanup func‐
tions.
· The command, when it is invoked with the or option, to iden‐
tify 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 server program, 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:
The ch_path variable specifies a default directory containing
executable programs that perform the various channel func‐
tions. 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 keyword, for each chan‐
nel. If no cleanup time is specified, the default is 2:00
a.m. local time. For example, The channel manager exe‐
cutes cleanup functions sequentially.
The 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 defini‐
tions 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
When is run with the or option, it must find an event chan‐
nel matching each event it receives, so that it can deter‐
mine 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 server program each time is run.
The server executes get_function for each channel in turn,
in the order in which the channels appear in the configura‐
tion file. If the keyword is omitted from a channel defi‐
nition, no events are retrieved for that channel.
A get_function program must return a stream of zero or more
EVM events to its directing any error messages to for dis‐
play on error stream. The program is executed as specified
in the configuration line, including any arguments, but
must accept an optional option and a filter string as
trailing arguments. If a filter is supplied, the program
must return only events that match the filter. See EvmFil‐
ter(5) for more information about filters.
When is invoked with the 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 keyword is omitted from a channel definition, pro‐
duces a formatted dump of any events it receives that
belong to the channel.
A details_function program must accept EVM events on and
output text to Error messages must be directed to for dis‐
play on error stream. The program is executed as specified
on the configuration line, including any arguments.
When is invoked with the 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 for display by on error stream.
If the keyword is omitted from a channel definition, dis‐
plays 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 com‐
mand syntax:
event_name The event's name.
reference The event's 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 and 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 is started by the EVM daemon,
it searches the channel configuration file for channels
that define a monitor_function program. The channel man‐
ager runs each monitor_function program, including any
arguments present in the configuration line, and with the
value appended as a trailing argument. The channel manager
executes each program periodically thereafter, without the
argument, at the frequency defined by the channel's moni‐
tor_period value. The program should use the presence or
absence of the 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 or 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 com‐
mand syntax:
If the 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 speci‐
fied by
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
or 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 speci‐
fied in the configuration line, and does not supply addi‐
tional arguments.
If the 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:
All fields are optional, but the appropriate number of
colon characters must be included in order to specify the
higher-order components, for example, would be interpreted
as one minute and zero seconds. The days, hours, and min‐
utes 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 natu‐
ral limit for any component, regardless of what other com‐
ponents are included: for example, is interpreted as 90
seconds, and 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 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 sys‐
tems that support EVM in the future, you should use the built-in macro
in place of the first two components 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:
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
3. All channel functions are found in a directory named
4. This channel applies to events having as the first three components
of their names.
5. Whenever is run, the program is invoked to retrieve events of this
class. The arguments are passed to the program each time it is exe‐
cuted -- these arguments may be followed by and a filter string.
6. Whenever the command encounters an event in this class, the program
is invoked to provide the detailed description.
7. Whenever the command encounters an explanation for an event in this
class, the program is invoked to provide the explanation.
8. The program is run daily at 3:00 a.m. The arguments and are passed
to the program each time it is executed.
9. The channel manager invokes the function on startup (with the param‐
eter) and every 15 minutes thereafter.
FILES
Location of the EVM channel configuration file.
SEE ALSO
Commands
evmget(1), evmshow(1), evmchmgr(1M), evmd(1M).
Files
evmdaemon.conf(4), evmlogger.conf(4).
Event Management
EVM(5).
Event Filter
EvmFilter(5).
evmchannel.conf(4)
