 |
Index for
Section 4 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
evmlogger.conf(4)
NAME
evmlogger.conf - EVM logger configuration file
SYNOPSIS
eventlog {
name eventlog_name
type [formatted | binary]
show_template template
logfile log_path
alternate log_path
maxsize max_logsize
filter log_filter_spec
include filter_element
exclude filter_element
explicit_target bool_par
suppress {
filter supp_filter_spec
include filter_element
exclude filter_element
period supp_period
threshold supp_threshold
}
}
forward {
name forward_name
filter forward_filter_spec
include filter_element
exclude filter_element
command forward_command
maxqueue queue_limit
explicit_target bool_par
suppress {
filter supp_filter_spec
include filter_element
exclude filter_element
period supp_period
threshold supp_thresh
}
}
remote_hosts {
name remote_host_name
hostnames remote_host_list
hosts remote_host_list
targets target_list
filter filter_spec
include filter_element
exclude filter_element
retry retry_interval
}
configdir directory
DESCRIPTION
The evmlogger.conf file is the Event Manager (EVM) logger configuration
file. This file is read when the logger program, evmlogger, starts, and
when it reloads its configuration.
The evmlogger.conf file is a text file that contains values used to
configure the event logger. The values direct the display, forwarding, or
storage of events. Any portion of a line from an unquoted number sign (#)
to the end of line is a comment. Blank lines are ignored.
Any number of event logs and forwarders may be defined in a configuration
file. The following keywords are recognized:
eventlog
Introduces a group of keyword/value pairs, which define an event log.
Events that match the log's log_filter_spec are selected for handling
by this log.
name eventlog_name
The name used to refer to the event log.
type log_type
The type of the log -- either formatted or binary. If the log_path
specifies a terminal device, such as /dev/console, the type is
automatically set to formatted, and cannot be forced to binary. If
the log_path specifies a file, the default type is binary. Events
are written to formatted logs as single lines of text, and to
binary logs as raw EVM events.
show_template template
The template used to format lines of text for a formatted log. If
no template is specified, the event timestamp and message are
written. See evmshow(1) for show-template syntax.
logfile log_path
Pathname of the log file. If a log is a disk file, the logger
creates the file if necessary.
If the log name ends in the characters .dated, the logger replaces
that suffix with the current date in the form yyyymmdd. A new file
is begun when the first event is written to the log each day.
alternate log_path
Specifies an alternate path to be used in cases where the primary
log cannot be used. If the specified logfile becomes unusable, the
logger switches to the alternate log file.
If the logger is writing to the alternate log, and the error
condition which caused it to switch has been cleared, you can make
it revert to the primary path by using the evmreload -l command.
maxsize max_logsize
The maximum size, in kilobytes, that the log file may reach. If
adding an event to the file would cause this size to be exceeded,
the logger begins a new file, adding the suffix _n to the name of
the new file, where _n is a sequential generation number.
filter log_filter_spec
Event selection filter specification. Events passing this filter
are selected for logging to this event log; all others are ignored.
See EvmFilter(5) for a description of filter syntax.
include filter_element
Modifies the current log_filter_spec. See the description of the
include and exclude keywords below.
exclude filter_element
Modifies the current log_filter_spec. See the description of the
include and exclude keywords below.
explicit_target bool_par
If this keyword is not specified, or if it is specified and
bool_par has a value of FALSE, NO or 0 (zero), the event log will
handle events posted through the local daemon, in addition to those
received from any remote hosts that name the event log in their
targets lists. If
bool_par has a value of TRUE, YES or 1 (one), the event log will
only handle events from any remote hosts that name it in their
targets lists.
See the remote_hosts group definition below for more information.
suppress
The suppression facility minimizes resource waste by limiting the
number of identical events appearing in the log. A description of
the event suppression group follows.
Before being written to the log, each incoming event is matched
against the suppression group's supp_filter_spec. An event that
passes the filter is then compared with other events that have been
posted during the last period minutes, ignoring the timestamp,
last_timestamp, PID, PPID, event-id and repeat-count data items.
If a matching event is found, and at least threshold instances of
the event have been written to the log during the period, the
logger does not log the event -- instead, it inserts or updates the
repeat_count and last_timestamp data items in the last-logged
instance of the event. The suppression is indicated by the string
[n times] appearing in the message text when the event is
displayed, where n is the repeat_count.
Once an individual event becomes eligible for suppression, the
suppression is canceled automatically after the greater of four
hours or the supp_period, and is reinstated when the suppression
conditions occur again. Suppression is canceled automatically when
a change of logfile occurs.
Suppression directives are ignored for formatted logs.
The following keywords are recognized in a suppression group:
filter supp_filter_spec
Events selected by this filter are eligible for suppression
consideration. See EvmFilter(5) for the filter syntax.
include filter_element
Modifies the current supp_filter_spec. See the description of
the include and exclude keywords below.
exclude filter_element
Modifies the current supp_filter_spec. See the description of
the include and exclude keywords below.
period supp_period
The period, in minutes, over which events are counted for
suppression consideration.
threshold supp_threshold
The number of instances of an event that will be logged during
supp_period before suppression begins.
forward
Events meeting the filter specifications are to be forwarded using the
command specified.
name forward_name
A name used to identify the forwarding definition.
filter forward_filter_spec
Event forwarding filter specification. Events passing this filter
are selected for forwarding as specified by the forward_command.
See EvmFilter(5) for the filter syntax.
include filter_element
Modifies the current forward_filter_spec. See the description of
the include and exclude keywords below.
exclude filter_element
Modifies the current forward_filter_spec. See the description of
the include and exclude keywords below.
command forward_command
When an incoming event is selected for handling by this forwarder,
and is not eligible for suppression, the logger executes this
command, piping the event into the command's stdin stream.
maxqueue queue_limit
This keyword limits the number of events that can be queued by a
forwarder while a previous event is being handled by command. If
the maximum number of events is already queued when a new event
arrives, the event is ignored by this forwarder. If not specified,
this keyword has a default value of 100. If a value greater than
1000 is specified, the logger automatically limits it to 1000.
See evmlogger(8) for details of event queuing.
explicit_target bool_par
If this keyword is not specified, or if it is specified and
bool_par has a value of FALSE, NO or 0 (zero), the forwarder will
handle events posted through the local daemon, in addition to those
received from any remote hosts that name the forwarder in their
targets lists.
If bool_par has a value of TRUE, YES or 1 (one), the forwarder will
only handle events from any remote hosts that name it in their
targets lists.
See the remote_hosts group definition below for more information.
suppress
Event suppression as applied to forwarding is similar to event log
suppression, but limits the number of identical events that will be
forwarded over the suppression period. In this case, events which
are eligible for suppression are simply ignored by the forwarder.
This feature is intended to reduce the chance of a large volume of
mail being sent during a period of high event activity.
remote_hosts
Introduces a remote logging group. Entries in this group define local
handling of events posted on one or more remote systems.
name bool_par
A name used to identify the remote logging definition.
hostnames remote_host_list
This keyword is interchangeable with hosts. The remote_host_list
is a list of hosts to which the logger will subscribe for events.
The list may specify multiple hosts, separated by commas or spaces,
and multiple hostnames or hosts lines may be supplied. The list may
be made up of any combination of unqualified host names, fully
qualified host names and IP addresses. It must be enclosed in
double quotes if it contains spaces. If no hosts are specified, the
remote logging group is ignored.
hosts remote_host_list
This keyword is interchangeable with hostnames. The
remote_host_list is a list of hosts to which the logger will
subscribe for events. The list may specify multiple hosts,
separated by commas or spaces, and multiple hostnames or hosts
lines may be supplied. The list may be made up of any combination
of unqualified host names, fully qualified host names and IP
addresses. It must be enclosed in double quotes if it contains
spaces. If no hosts are specified, the remote logging group is
ignored.
targets target_list
The target_list is a list of names of eventlog and forward groups
(targets) defined in this configuration that will handle events
received from the remote hosts. The list may specify multiple
targets, separated by commas or spaces, and multiple targets lines
may be supplied. The list must be enclosed in double quotes if it
contains spaces. If no targets are specified, the remote logging
group is ignored.
filter filter_spec
Event filter specification. Events passing this filter are passed
to the logger by the EVM daemons running on the remote hosts. See
EvmFilter(5) for the filter syntax. If no filter is specified, a
default filter is produced by combining the filter strings from all
of the targets referred to by this remote logging group.
include filter_element
Modifies the current remote_filter_spec. See the description of
the include and exclude keywords below.
exclude filter_element
Modifies the current remote_filter_spec. See the description of
the include and exclude keywords below.
retry retry_interval
If the logger fails to establish a connection to any of the remote
hosts specified in this group, or if an established connection is
lost, it will attempt to establish or reestablish the connection
every retry_interval seconds until it is successful. The default
for this value is 60 seconds. If the specified value is less than
5 or more than 3600, it is silently modified to the closest of
these values.
configdir directory
This keyword specifies the path of a directory tree that holds zero or
more secondary configuration files. The directory tree is searched when
the logger is started and each time its configuration is reloaded.
Configuration file names must end with .conf, and must not begin with a
dot (.). Files must be owned by bin or root and their file permissions
must restrict writing to owner or group. Symbolic links and
subdirectory hierarchies can be used to reference configuration files
that physically are located elsewhere.
After installing, removing or modifying a secondary configuration file,
you must run the evmreload -l command to notify the logger of the
change and request a configuration reload.
Any number of configdir entries may be specified in the primary
configuration file, but configdir is not a valid keyword in a secondary
configuration file.
The include and exclude keywords can appear multiple times in an eventlog,
forward, remote_hosts or suppress specification, allowing you to build and
maintain a filter in simple single-line increments. Each filter_element
must be a valid filter string, conforming to the syntax described in the
EvmFilter(5) reference page. The logger assembles a complete filter string
by surrounding the initial filter with parentheses and appending the
filter_elements to it, separating each with a logical OR (for include) or
AND NOT (for exclude) operator. For example:
filter "[priority >= 200]"
include "[name *.mylog]"
exclude "[name *.oldlog]"
The previous filter lines are equivalent to this more complex single filter
line:
filter "([priority >= 200]) OR [name *.mylog] AND NOT [name *.oldlog]"
The first line selects all events with a priority of 200 or greater, the
next modifies this by selecting all events from mylog regardless of their
priorities, and the last line excludes all oldlog events regardless of
their priorities.
If you prefer, you can omit the filter command, and build the complete
filter string from include and exclude lines.
If no filter, include or exclude lines are supplied for an event log or
forwarder, it does not handle any events.
Keywords may be entered in a case-insensitive manner. 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
_________________________
alternate 3
command 4
configdir 7
eventlog 0
exclude 3
explicit_target 4
filter 4
forward 4
hostnames 4
hosts 4
include 3
logfile 3
maxqueue 4
maxsize 3
name 0
period 0
remote_hosts 8
retry 5
show_template 4
suppress 4
targets 6
threshold 0
type 0
_________________________
NOTES
1. The logger only allows a single instance of each forwarding command to
execute at one time and queues any events that arrive while an
instance is already running. The forwarder ignores events that arrive
while the queue is full. To minimize the chances of queuing or missing
events, you should avoid using the forwarding facility to run commands
that may take significant time to execute.
2. If you specify a forwarding command that may itself cause events to be
posted (for instance, mail commands may post syslog events that will
be routed to EVM), the forwarding filter explicitly should exclude
those events. Otherwise, it is possible that an infinite event loop
will occur.
3. 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
This example initiates an instance of the evmlogger command with the
following configuration:
1. Binary events are written to a file in the /var/evm/evmlog directory
named evmlog.xxx where xxx is the current year, month, and day -- for
example, /var/evm/evmlog/evmlog.19981217. An alternate log path is
specified in case of write failures to the primary path.
2. A new generation of the log is started automatically if the size
exceeds 256 Kbytes.
3. All events with a priority of at least 200 are selected for logging.
4. Duplicate events are suppressed.
5. Events with a priority of at least 600 are displayed on the system
console as formatted events, showing the timestamp, the priority and
the event's message.
6. Events with a priority of at least 600 are also mailed to root.
7. A maximum of 20 events will be queued for forwarding to root when an
instance of the forwarding command is already running.
eventlog
{
name evmlog
logfile /var/evm/evmlog/evmlog.dated
type binary
maxsize 256 # Kbytes
alternate /altlogs/evmlog/evmlog.dated
# Log all events with priority >= 200:
filter "[prio >= 200]"
# Suppress logging of duplicate events:
suppress
{ filter "[name *]"
period 30 # minutes
threshold 3 # No. of instances before suppression
}
}
# Log high-priority events to the system console:
eventlog {
name console_log
logfile /dev/console
filter "[prio >= 600]"
type formatted
show_template "@timestamp [@priority] @@"
}
# Forward details of high-priority events to root:
forward {
name priority_alert
# Don't forward mail events through mail (see note above):
filter "[prio >= 600] & ![name @SYS_VP@.syslog.mail]"
suppress
{ filter "[name *]"
period 120 # minutes
threshold 1 # No. of duplicates before suppression
}
# This evmshow command writes a subject line as the first line of
# output, followed by a detailed display of the contents of the
# event. The resulting message is distributed by mail(1).
command "evmshow -d -t 'Subject: EVM ALERT [@priority]: @@' \
| mail root"
}
FILES
/etc/evmlogger.conf
Location of the EVM logger configuration file.
/var/evm/adm/config/logger
Default location of the secondary EVM logger configuration files.
SEE ALSO
Commands: evmget(1), evmshow(1), evmd(8), evmlogger(8), evmreload(8)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
Event Filter: EvmFilter(5)
|
Index for
Section 4 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|