evmlogger.conf(4)evmlogger.conf(4)NAMEevmlogger.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 configura‐
tion file. The following keywords are recognized: 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. The
name used to refer to the event log. 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. The template used to for‐
mat 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. 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. 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. 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. Event selection filter specification. Events passing
this filter are selected for logging to this event log; all oth‐
ers are ignored. See EvmFilter(5) for a description of filter
syntax. Modifies the current log_filter_spec. See the descrip‐
tion of the include and exclude keywords below. Modifies the
current log_filter_spec. See the description of the include and
exclude keywords below. 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 informa‐
tion. The suppression facility minimizes resource waste by lim‐
iting 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 time‐
stamp, 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:
Events selected by this filter are eligible for suppression con‐
sideration. See EvmFilter(5) for the filter syntax. Modifies
the current supp_filter_spec. See the description of the
include and exclude keywords below. Modifies the current
supp_filter_spec. See the description of the include and
exclude keywords below. The period, in minutes, over which
events are counted for suppression consideration. The number of
instances of an event that will be logged during supp_period
before suppression begins. Events meeting the filter specifica‐
tions are to be forwarded using the command specified. A name
used to identify the forwarding definition. Event forwarding
filter specification. Events passing this filter are selected
for forwarding as specified by the forward_command. See EvmFil‐
ter(5) for the filter syntax. Modifies the current forward_fil‐
ter_spec. See the description of the include and exclude key‐
words below. Modifies the current forward_filter_spec. See the
description of the include and exclude keywords below. When an
incoming event is selected for handling by this forwarder, and
is not eligible for suppression, the logger executes this com‐
mand, piping the event into the command's stdin stream. This
keyword limits the number of events that can be queued by a for‐
warder 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 speci‐
fied, 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. 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 informa‐
tion. 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. Introduces a remote logging group.
Entries in this group define local handling of events posted on
one or more remote systems. A name used to identify the remote
logging definition. 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, sepa‐
rated 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. 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, sepa‐
rated 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. 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 spec‐
ify multiple targets, separated by commas or spaces, and multi‐
ple targets lines may be supplied. The list must be enclosed in
double quotes if it contains spaces. If no targets are speci‐
fied, the remote logging group is ignored. Event filter speci‐
fication. 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 fil‐
ter is produced by combining the filter strings from all of the
targets referred to by this remote logging group. Modifies the
current remote_filter_spec. See the description of the include
and exclude keywords below. Modifies the current remote_fil‐
ter_spec. See the description of the include and exclude key‐
words below. If the logger fails to establish a connection to
any of the remote hosts specified in this group, or if an estab‐
lished 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. 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. Sym‐
bolic links and subdirectory hierarchies can be used to refer‐
ence configuration files that physically are located elsewhere.
After installing, removing or modifying a secondary configura‐
tion 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 event‐
log, 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 parenthe‐
ses and appending the filter_elements to it, separating each with a
logical OR (for include) or AND NOT (for exclude) operator. For exam‐
ple:
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 *.old‐
log]"
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 regard‐
less 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
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. 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 fil‐
ter explicitly should exclude those events. Otherwise, it is possible
that an infinite event loop will occur. 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: 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. A new generation of the log is started automatically if
the size exceeds 256 Kbytes. All events with a priority of at least
200 are selected for logging. Duplicate events are suppressed. 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. Events with a priority of at least 600 are also mailed to
root. 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
Location of the EVM logger configuration file. 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)evmlogger.conf(4)
