Softpanorama (slightly skeptical) Open Source Software Educational Society

May the source be with you, but remember the KISS principle ;-) Softpanorama Search

Configuration File

Most adapters come with a configuration file containing configuration options and filters. This file is read by an adapter when it is started. By modifying this file, you can reconfigure an adapter at anytime, without having to modify the adapter source code. To have your configuration changes take effect, simply stop and restart the adapter. A configuration file usually has an extension of .conf; see each specific adapter chapter for exact file names.

The TME UNIX log file adapter receives raw log file information from the UNIX syslogd daemon, formats it, and sends it to the IBM Tivoli Enterprise Console gateway. The IBM Tivoli Enterprise Console gateway then sends the information to the event server. The non-TME UNIX log file adapter sends information directly to the event server.

The UNIX log file adapter adds entries into the /etc/syslog.conf file to enable the adapter to monitor events that the syslogd daemon writes to various log files. The adapter can also be configured to monitor any ASCII log file for information that is important to the operation of your enterprise.

The UNIX log file adapter can only parse log files that create raw event information in single-line form for each event. You must preprocess log files that contain raw event information in multiple-line form or if the update quantity or rate is extremely high.

This chapter explains how to configure and start the UNIX log file adapter.

Configuration File

The configuration file defines the behavior of the adapter. The configuration file can have the common keywords described in Configuration File, as well as the following custom keywords:

LogSources

Specifies the log files to poll. The complete path to each file must be specified, and file names must be separated by commas; no spaces or other separators can be used. A log source need not exist when the adapter is started; it will be polled when it is created.

If a file truncates while the adapter is active, the adapter automatically resets its internal pointer to the beginning of the file. If during the polling interval the file is overwritten, removed, or recreated with more lines than the previous poll, only the number of lines greater than the previous line count is read. For example, the file has one line. After the poll interval elapses, the file is overwritten with two lines. Only the second line is read on the next polling.

Note:

The maximum number of lines that can be concatenated to a log file is 16 384.

 

PollInterval

Specifies the frequency, in seconds, to poll each file listed in the LogSources field for new messages. The default value is 120 seconds.

 

UnmatchLog

Specifies a file to log discarded events that cannot be parsed into an IBM Tivoli Enterprise Console event class by the adapter. The discarded events can then be analyzed to determine if modifications are needed to the adapter format file.

Configuration File Location

By default, an adapter expects its configuration file (along with its format, CDS, and error files) to be located as shown in the following table. For Windows and Windows NT, the syntax shown is correct when running the bash interpreter.
 

For information about directory structures and system variables (those beginning with $), see the Tivoli Management Framework Planning for Deployment Guide.

File Format

Each non-blank line that does not begin with the comment sign (#) is of one of the following forms:

• To specify configuration options:

  keyword=value
  

• To specify event filters:

  Filter:CLASS=class_name;attribute=value;
  

• To specify event buffer filters:

  FilterCache:CLASS=class_name;attribute=value;
  

Example

#   
# Communication Parameters   
#   
ServerLocation=ravel   
ServerPort=5529 
#
# Event Filters
#
Filter:Class=disk_event
Filter:Class=Su_Success;origin=126.32.2.14

Keywords

Keywords use the following format: keyword=value

Some adapters have additional keywords specific to them. See each specific adapter chapter for descriptions of these keywords. Adapters do not issue error messages for misspelled keywords or keywords set to a value that is not valid. Do not use blank spaces in keyword statements unless enclosed in single quotation marks (however, you cannot use quotation marks at all with the HPOVFilter keyword in the HPOV adapter). Do not use class names not defined in a BAROC file with configuration options.

A configuration file can contain the following keywords, which are common to most adapters:

 

AdapterCdsFile=path

Specifies the full path name of the CDS file. This keyword is required if the CDS file is not in the same directory as the configuration file.

 

AdapterErrorFile=path

Specifies the full path name of the error file. This keyword is required if the error file is not in the same directory as the configuration file.

 

BufEvtMaxSize

Specifies the maximum size, in kilobytes, of the adapter cache file. The default value is 64. The cache file stores events on disk when they cannot be sent to the event server.

The BufEvtMaxSize keyword is optional.

 

BufEvtPath

Specifies the full path name of the adapter cache file. On endpoint adapters, the BufEvtPath keyword uses the $TIVOLIHOME variable to resolve file location and drive letter differences over different environments by using a path relative to the endpoint installation. The

ACF defines $TIVOLIHOME on each endpoint; you cannot change its value.
 

Operating System	Default Path	$TIVOLIHOME Value
UNIX	$TIVOLIHOME/tec/ tecad_adapter.cache	/etc/Tivoli
Windows, Windows NT	$TIVOLIHOME\tec\ tecad_adapter.cache	%SystemRoot%\system32\ drivers\etc\Tivoli

The AS/400^(R) adapters do not use this keyword.

This keyword is required when the BufferEvents keyword is set to YES.

 

BufferEvents

Specifies whether or not event caching is enabled. If BufferEvents is set to anything other than YES, events are not cached. The value is not case-sensitive. The default value is YES.

The BufferEvents keyword is optional.

 

BufferFlushRate

Specifies the number of events sent per minute. Once the adapter has recovered the lost connection, and there are events in the buffer, the events are sent at this rate per minute. The default value is zero (0); all events are sent in one burst.

The BufferFlushRate keyword is optional.

 

ConnectionMode

Specifies the connection mode to use to connect to the IBM Tivoli Enterprise Console gateway or event server. Valid values are connection_oriented (or its abbreviations CO and co) and connection_less. The default value is connection_less, except for the AS/400 adapters and the IBM Tivoli Enterprise Console gateway, which have connection_oriented as the default value.

When connection_less is specified or used by default, a new connection is established (and discarded) for each event or group of events that is sent. When connection_oriented or one of its abbreviations is specified, a connection is established at adapter initialization and is maintained for all events sent. A new connection is established only if the initial connection is lost. The connection is discarded when the adapter is stopped.

The ConnectionMode keyword is optional.

 

Filter

Works with the FilterMode keyword to determine how events are filtered. An event matches a Filter statement when each attribute=value pair in the Filter statement is identical to the corresponding attribute=value pair in the event.

A Filter statement must contain the event class, and optionally can include any other attribute=value pair that is defined for the event class. The format of a filtering statement is the following:

Filter:Class=class_name;[attribute=value;...;attribute=value]

Each statement must be on a single line. The attribute=value pair is case sensitive.

This keyword is optional.

 

FilterCache

Works with the FilterMode and Filter keywords to determine which events are stored in the cache when events cannot be sent successfully to the event server. To store events in the cache, you must set BufferEvents=YES. An event matches a FilterCache statement when each attribute=value pair in the FilterCache statement is identical to the corresponding attribute=value pair in the event.

A FilterCache statement must contain the event class (class_name) and can include any attribute=value pair that is defined for that event class. The format of a filtering statement is the following:

Filter:Class=class_name;[attribute=value;...;attribute=value]

Each statement must be on a single line. The attribute=value pair is case sensitive. You must specify the Filter keyword, when you use the FilterCache keyword. Additionally, the FilterCache statement must specify the same class or subset of classes that the Filter statement specifies.

This keyword is optional.

Note:

When using FilterCache with endpoint adapters and the IBM Tivoli Enterprise Console gateway, you must set the filtering statements at both locations to the same specifications.

 

FilterMode

Specifies whether events that match a Filter or FilterCache statement are sent to the event server (FilterMode=IN) or discarded (FilterMode=OUT). The default value is OUT. The valid values are IN or OUT, without regard for case. If you set FilterMode=IN, you must have one or more Filter and FilterCache statements defined.

For information about how to use filtering keywords to send, cache, and discard events, see Event Filtering.

This keyword is optional.

 

getport_timeout_seconds

Specifies the number of seconds to wait before re-sending the UDP call for a port, if no response is heard. It re-transmits until the RPC call times out. The default value is zero (0) seconds.

 

getport_timeout_usec

Specifies the number of microseconds to add to the seconds specified with the getport_timeout_seconds keyword. The default value is 50 000 microseconds.

 

getport_total_timeout_seconds

Specifies the number of seconds to wait on getting a port after making a all to the portmapper. The default value is zero (0) seconds.

 

getport_total_timeout_usec

Specifies the number of microseconds to add to the seconds specified with the getport_total_timeout_seconds keyword. The default value is 50 000 microseconds.

 

NO_UTF8_CONVERSION

Specifies whether to encode event data in UTF-8. When this options is set to YES, the IBM Tivoli Enterprise Console product does not encode event data in UTF-8. The data is assumed to already be in UTF-8 encoding when passed to the IBM Tivoli Enterprise Console product. It does, however, prepend the flag indicating that the data is in UTF-8 encoding if the flag does not exist at the beginning of the event data.

The default value for this option is NO.

 

Pre37Server

Specifies whether the adapter is to send its events in the encoding of the event server host or in UTF-8 encoding. Event server host versions earlier than the IBM Tivoli Enterprise Console 3.7 product do not support UTF-8 encoding of events. When set to YES, this keyword disables UTF-8 encoding and allows the adapter to communicate with event server host versions earlier than the IBM Tivoli Enterprise Console 3.7 product. When this keyword is set to NO, the adapter sends events in UTF-8 encoding. The values are not case-sensitive. The default is NO.

When this keyword is set to YES, you must also specify the Pre37ServerEncoding keyword.

 

Pre37ServerEncoding

Determines which language to use when a non-TME adapter communicates with a non-UTF-8 event server host (versions earlier than the IBM Tivoli Enterprise Console 3.7 product). This keyword is active only when Pre37Server is set to YES. This keyword only applies to the log file adapters (UNIX, NetWare, OS/2, Windows, and Windows NT).

 

RetryInterval

When ConnectionMode=connection_oriented, and the connection to the event server is lost, an adapter waits the specified number of seconds before connecting to a secondary server or buffering the events. While the adapter is waiting for the expiration of this interval, no new events are processed by the adapter.

This option allows an adapter to send all events to the primary event server even if the primary event server is stopped briefly, such as when loading a new rule base.

If you use this option to wait for restarting an event server, set the value for a period of time longer than necessary for the event server to be stopped and then restarted.

The RetryInterval keyword is optional. The default is 120 seconds.

 

ServerLocation

Specifies the name of the host on which the event server is installed. The value of this field must be one of the formats shown in the following table, depending on whether the adapter is a TME adapter or a non-TME adapter, and whether the event server is part of an interconnected Tivoli management region:
 

Adapter Type	Format
TME	EventServer
TME in an interconnected Tivoli management region	EventServer#region_name
non-TME	host_name or IP_address. Use the dotted format for IP_address.

 

Note:

AS/400 adapters are non-TME adapters.

For TME adapters on managed nodes and non-TME adapters, ServerLocation can contain up to eight values, separated by commas. The first location is the primary event server, while others are secondary servers to be used in the order specified when the primary server is down.

For endpoint adapters, secondary event servers, if any, are defined in the IBM Tivoli Enterprise Console gateway configuration file. Only specify a primary event server in an endpoint adapter configuration file.

The default is EventServer. To use a non-TME value for ServerLocation, see Configuration File for more information.

The ServerLocation keyword is required.

Note:

ServerLocation defines the path and name of the file for logging events, instead of the event server, when used with the TestMode keyword.

 

ServerPort

Specifies the port number on a non-TME adapter on which the event server listens for events. Set this keyword value to zero (0), the default value unless the portmapper is not available on the event server, which is the case if the event server is running on Windows or the event server is a Tivoli Availability Intermediate Manager (see the following note). If the port number is specified as zero (0) or it is not specified, the port number is retrieved using the portmapper.

 

The ServerPort keyword can contain up to eight values, separated by commas. For non-TME adapters that send events to a UNIX event server, use the default value of zero (0) (only one value of zero, even if multiple UNIX event servers are specified with the ServerLocation keyword). For non-TME adapters that send events to a Windows event server or a Tivoli Availability Intermediate Manager (AIM), specify one value for each event server defined with the ServerLocation keyword.

The ServerPort keyword is optional when the event server is running on UNIX, but mandatory when running on Windows.

Note:

If the event server is running on Windows: There is no portmapper daemon on a Windows machine that allows the adapter to query the reception port at runtime. The event server listens on a fixed reception port (tec_recv_agent_port in .tec_config) for connection and adapter input. Set ServerPort to the value of the tec_recv_agent_port entry in the .tec_config file in the $BINDIR/TME/TEC directory. The default is 5529. The Tivoli Availability Intermediate Manager never uses the portmapper; the Tivoli Availability Intermediate Manager server listens on a fixed port set in the Tivoli Availability Intermediate Manager graphical user interface.

 

TestMode

Specifies whether test mode is turned on or off. When TestMode=YES, the ServerLocation keyword specifies the file to which events are logged, instead of being sent to the event server. Valid values are YES and NO, without regard to case. The default is NO.

The TestMode keyword is optional.

Event Filtering

Normally, an adapter sends all events to the event server. You can optionally specify events that can or cannot be sent to the event server. You can do this by specifying the event class and such information as the origin, severity, or any other attribute=value pair that is defined for the event class. The class name specified for an event filter entry must match a defined class name; an adapter does not necessarily have knowledge of the class hierarchy.

Depending on how you specify the Filter and FilterMode keywords, filtered events are either sent to the event server or discarded.

• To send specific events to the event server:
  1. Set FilterMode to IN.
  2. Create Filter statements to match the specific events that you want sent.
• To discard specific events:
  1. Set FilterMode to OUT (the default value).
  2. Create Filter statements to match the specific events that you want discarded.
• To send all events to the event server (the default behavior):
  1. Set FilterMode to OUT.
  2. Do not specify any Filter statements.

Note:

All events are discarded when the configuration is as follows:

1. FilterMode is set to IN.
2. No Filter statements are specified.

To use non-English characters in a Filter statement, you must enter the non-English characters in the local encodings.

Regular Expressions in Filters

You can also use Tcl regular expressions in filtering statements. The format of a regular expression is re:'value_fragment'.

Note:

Tivoli Event Integration Facility uses an exception to the Tcl regular expression syntax. The backslash character (\) in Tivoli Event Integration Facility indicates that the following literal character is the character to filter for, not some special character such as a tab. For example, \t means the tab character in Tcl, but means t in Tivoli Event Integration Facility.

The following example shows a Filter statement with a regular expression. This filter statement matches all events with a class name that contains TEC_ somewhere in its name:

Filter:Class=re:'TEC_.*'

The following example shows a FilterCache statement with a narrower range. This filter statement matches all events with a class name that contains TEC_ somewhere in its name and has a severity of critical:

FilterCache:Class=re:'TEC_.*';severity=CRITICAL

For more information about Tcl regular expressions, see a Tcl user's guide.

Event Filter Examples

The following table shows some event filter examples for a few different adapters:
 

Filter:Class=SNA_Equipment_Malfunction;origin=1.2.3.4

Filter:Class=Su_Success;origin=126.32.2.14

Filter:Class=OV_Message;origin=126.32.2.14

Filter:Class=NT_Power_Failure;origin=126.32.2.14

Event Buffer Filtering

When an adapter is unable to connect to the event server or IBM Tivoli Enterprise Console gateway, it sends the events to a file if the BufferEvents keyword is set to YES. You can filter events sent to a cache file, similar to filtering events for the event server by using the FilterCache keyword.

There are no default event cache filters in the configuration files shipped with adapters.

The following procedures describe how to filter events with the FilterCache and FilterMode keywords, when the event server is unavailable:

• To cache specific events:
  1. Set FilterMode to IN.
  2. Set BufferEvents to YES (the default value).
  3. Create Filter and FilterCache statements to match the specific events that you want cached.
• To discard specific events:
  1. Set FilterMode to OUT.
  2. Create Filter and FilterCache statements to match the specific events that you want discarded.
• To cache all events (the default behavior):
  1. Set FilterMode to OUT.
  2. Set BufferEvents to YES.
  3. Do not specify any FilterCache statements.

Note:

All events are discarded when the configuration is as follows:

1. FilterMode is set to IN.
2. No FilterCache statements are specified.

Event Buffer Filter Examples

The following table shows some event buffer filter examples for a few different adapters:
 

FilterCache:Class=SNA_Equipment_Malfunction;origin=1.2.3.4

FilterCache:Class=Su_Success;origin=126.32.2.14

FilterCache:Class=OV_Message;origin=126.32.2.14

FilterCache:Class=NT_Power_Failure;origin=126.32.2.14