evmlogger.conf(4)

NAME

evmlogger.conf — EVM logger configuration file

SYNOPSIS

eventlog {                       } }   forward {                    } }   configdir

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 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 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 evmlogger reloads the configuration file.

When evmlogger reloads the configuration file, it reconfigures itself by reading its configuration file, evmlogger.conf, again and updates its settings.

The EVM daemon starts the Event Manager (EVM) logger automatically at startup. The EVM logger reads its configuration file to find a set of definitions of event logs and forwarders. By default, the EVM logger reads its configuration from the /etc/evmlogger.conf file. The evmlogger -c config_file command can override the default configuration file by specifying a different file. See evmlogger(1M). If the logger's configuration file is changed while the logger is running, use the evmreload -l command to instruct the logger to reconfigure itself.

The logger also reconfigures itself upon receipt of a SIGHUP signal.

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 can 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 of the event log.

type log_type

The type of the log. Specify 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 the evmshow(1) manpage for the template syntax.

logfile log_path

Path name 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 started 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 log file specified by logfile log_path 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 the logger to switch has been cleared, you can revert to the primary log file 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. The logger adds the suffix _n to the name of the new file. The n is a sequentially generated number.

filter log_filter_spec

Specifies the event selection filter. Events passing this filter are selected for logging to this event log; all others are ignored. See the EvmFilter(5) manpage for a description of filter syntax.

include filter_element

Modifies the current log_filter_spec. See the description of include and exclude keywords in the The include and exclude Keywords subsection.

exclude filter_element

Modifies the current log_filter_spec. See the description of include and exclude keywords in the The include and exclude Keywords subsection.

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 handles events posted through the local daemon. Because EVM currently supports only local connection, this argument should not be set to TRUE.

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, the logger 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.

When an individual event becomes eligible for suppression, the suppression is canceled automatically after four hours or after supp_period, which ever is the greater amount of time. The individual event 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 in the The include and exclude Keywords subsection.
exclude filter_element: Modifies the current supp_filter_spec. See the description of the include and exclude keywords in the The include and exclude Keywords subsection.
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 is 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 the EvmFilter(5) manpage for the filter syntax.

include filter_element

Modifies the current forward_filter_spec. See the description of the include and exclude keywords in the The include and exclude Keywords subsection.

exclude filter_element

Modifies the current forward_filter_spec. See the description of the include and exclude keywords in the The include and exclude Keywords subsection.

command forward_command

When an incoming event is selected for handling by this forwarder, and the event 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(1M) 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 handles events posted through the local daemon. Because EVM currently supports only local connection, this argument should not be set to TRUE.

suppress

Event suppression as applied to forwarding is similar to event log suppression. The difference is that event suppression for forwarding limits the number of identical events that are forwarded over the suppression period. In this case, events which are eligible for suppression are simply ignored by the forwarder. This feature reduces the chance of a large volume of mail being sent during a period of high event activity.

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 to 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

The include and exclude keywords can appear multiple times in an eventlog, forward, 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

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`
`include`	`3`
`logfile`	`3`
`maxqueue`	`4`
`maxsize`	`3`
`name`	`0`
`period`	`0`
`show_template`	`4`
`suppress`	`4`
`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, 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 are routed to EVM), the forwarding filter explicitly should exclude those events. Otherwise, it is possible that an infinite event loop will occur.

3.

To allow your file to be used on or ported to other systems that support EVM in the future, use the built-in macro @SYS_VP@ instead of the first two components (sys.unix) of the name of any system event.

Using the built-in macro makes it unnecessary to change the file if the other system uses a different event name prefix.

EXAMPLES

This example initiates 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 log path.

A new generation of the log is started automatically if the size exceeds 256 KB.

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 is 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  # KB 
  
    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.

evmlogger.conf(4)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

DESCRIPTION

The include and exclude Keywords

Keywords

Notes

EXAMPLES

FILES

SEE ALSO

Commands

Event Management

EVM Events

Event Filter