When Log Central starts, it reads a configuration file, messaging.conf, to determine central host configuration and agent filtering. Some of the configuration attributes in this file are set up for you when you run the Host Configuration Utility (lc_config), as described in Chapter 2, "Getting Started." This chapter describes optional additional fields in the configuration file that you may want to modify. Topics discussed include:

• Default Configuration

• Specifying a Backup Central Collector

• Specifying Nondefault Global Parameters

• Assigning Filters to Agents

• Defining Agent Filters

Log Central uses a single configuration file located on the central host. The configuration file is an ASCII text file which you can modify with your favorite text editor. The default location for the configuration file is:

UNIX systems

install_dir/etc/messaging.conf

Windows NT

C:\install_dir\etc\messaging.conf

where:

install_dir

Is the directory where Log Central was installed.

When you complete the initial setup using the Host Configuration Utility (lc_config), your configuration is specified by an LC_GLOBAL entry. This entry provides the name of the central host and the directory and prefix for intermediate message files used by the Message Receiver to pass log messages to the Message Processor for inclusion in the relational database. For example:

LC_GLOBAL
    {
    CENTRAL_HOST     = "quahog"
    LOGPREFIX        = "/usr/lclog"
    }

At the minimum, the configuration file must contain an LC_GLOBAL clause, in which the keywords CENTRAL_HOST and LOGPREFIX must appear. The LC_GLOBAL clause configures parameters for all nodes. The configuration file can contain other constructs, but they are optional.

The Log Central configuration file consists of commented sections that contain all the permitted constructs you might need. After initially running the Host Configuration utility, only the CENTRAL_HOST and LOGPREFIX fields in the LC_GLOBAL entry are not commented out. (In the configuration file the pound sign (#) indicates the start of a comment.) However, you should look at the commented sections to get an idea of the constructs that you can use in the configuration file to further customize your configuration. Any modifications you make to the configuration file only take effect after the start_messaging command is used to start up the Log Central components.

Where to Put Intermediate Files

When the intermediate log files (specified by LOGPREFIX) reside on a remote file system, performance of the Log Manager is adversely affected.

We recommend using log files on the local file system if the log message traffic is high.

Specifying a Backup Central Collector

To specify a backup Central Collector, you need to add the following two lines to the LC_GLOBAL entry in the configuration file:

BACKUP_HOST = hostname
BACKUP_LOGPREFIX = log_file_dir/prefix

For example, you might have an LC_GLOBAL entry that looks like this:

LC_GLOBAL
    {
    CENTRAL_HOST       = "quahog"
    LOGPREFIX          = "/usr/lclog"
    BACKUP_HOST        = "orca"
    BACKUP_LOGPREFIX   = "/usr/backuplog"
    }

To use a backup Central Collector, the name of the backup host must be specified when starting each of the log agents. Both the primary and backup Central Collectors must be started before the agents are started.

For best performance, we recommend specifying local file systems for the LOGPREFIX, BACKUP_LOGPREFIX, and ESCALATION_DIR keywords in the LC_GLOBAL clause.

Host Name Usage

The host names used in the configuration file (CENTRAL_HOST, BACKUP_HOST, and HOSTNAME) are the same as the value returned by the hostname command on the specified systems. For example, on a particular host, hostname returns star.abc.com, then the identifier for that host is star.abc.com and not star.

Specifying Nondefault Global Parameters

The LC_GLOBAL entry in the configuration file can also be used to specify nondefault values for the following:

• IPC key

  The default IPC key value is 0xeeee0000. Use the IPCKEY keyword in the LC_GLOBAL entry to define a nondefault IPC key value.

  IPCKEY can take any numeric value. Use 0x to indicate a hexadecimal value.

• The communication service between the Message Sender and Message Receiver

  The default service name used for communication between the Message Sender (msg_sender) processes and the Message Receiver (msg_receiver) process running on the central host or on the backup host is lc_talk. Use the TALK_SERVICE keyword in the LC_GLOBAL entry to specify a nondefault service name.

• The location for the message processor initialization file (msg_processor.ini)

  msg_processor.ini is the initialization file used by the msg_processor process. The default location of this file is install_dir/etc/msg_processor.ini, where install_dir is the directory where Log Central was installed on the central host. To specify a different location for the Message Processor initialization file, use the INIFILE keyword in the LC_GLOBAL entry.

• Temporary log file directory for data collection agent on managed nodes

  When a data collection agent is unable to forward messages to a Central Collector, it writes log messages into a temporary log file. When the Central Collector becomes available, the data collection agent automatically recovers the contents of the file and forwards the messages to the Central Collector. The default directory for these files is /tmp on UNIX, and C:\tmp on Windows NT. Use the ESCALATION_DIR keyword in the LC_GLOBAL entry to specify a different directory for these log files. This directory name is global since it is the same on all nodes that connect to this Central Collector.

All of the valid keywords that you can use in the LC_GLOBAL entry are described in Table 6-1.

Assigning Filters to Agents

Agent filters can be used by the data collection agents to do the following:

• Drop specified messages (that is, fail to forward them to the Central Collector)

• Execute a program or script when a specified log message occurs

• Send an SNMP trap notification to an enterprise management system

Defining filters is described under "Defining Agent Filters."

Use of agent filters is optional. By default, no agent filters are defined.

Filters are invoked in either the LC_GLOBAL entry or the MANAGED_NODE entries in the Log Central configuration file. In either case, a filter is invoked if a statement occurs in the entry that has this form:

FILTER = "filtername"

where filtername cannot be longer than eight characters.

For each named filter that is invoked in this way in the configuration file, there must be a DEFINE_FILTER entry in the configuration file that defines the named filter.

An agent filter can be global or it can be assigned to a specific machine (managed node). An agent filter is global if it is invoked in the LC_GLOBAL entry in the configuration file. For example:

LC_GLOBAL
    {
    CENTRAL_HOST       = "quahog"
    LOGPREFIX          = "/usr/lclog"
    BACKUP_HOST        = "orca"
    BACKUP_LOGPREFIX   = "/usr/backuplog"
    FILTER             = "BankAppTrap"
    }

BankAppTrap might be a filter that generates SNMP traps when certain log messages occur, for example. Of course, if you use a FILTER statement, this presupposes that a DEFINE_FILTER entry occurs in the configuration file, defining the invoked filter-BankAppTrap in this case. DEFINE_FILTER entries are described in "Defining Agent Filters."

Using a MANAGED_NODE Entry

If an agent filter is global, then by default all agents use that filter. However, you can also:

• Turn off the global filter for a particular managed node

• Assign a particular filter to a particular managed node

To do either of these things requires a MANAGED_NODE entry in the configuration file.

The MANAGED_NODE entry is simply a list of assignments defining the filters for a managed node in your Log Central system. A MANAGED_NODE entry is required only if you wish to specify non-global filters. No more than one MANAGED_NODE entry may be specified for each managed host.

If a MANAGED_NODE entry is not specified for a managed node, that node inherits all the global filters (if any), as specified in the LC_GLOBAL entry. The simplest approach is to use global filters for situations that apply to the greatest number of hosts, and specify any exceptions within the MANAGED_NODE entry.

Turning Off Global Filters on a Particular Node

If you want to turn off the global filters for a particular managed node, use the GLOBAL_FILTER statement in a MANAGED_NODE entry for that managed node. Global filters are turned off for machine bigiron in the following example:

MANAGED_NODE
   {
   HOSTNAME = "bigiron"
   GLOBAL_FILTER = "NO"
   }

A MANAGED_NODE entry can be used to assign a particular filter to a particular machine. You might do this if you want to define a custom filter for a particular log resource being managed by a single agent. For example:

MANAGED_NODE
    {
    HOSTNAME     = "peach"
    FILTER       = "F4"
    }

In this example, filter F4 is used by the log agent on machine peach, in addition to any global filters that may be defined in the LC_GLOBAL entry. In the following example, the agent on machine marmalade does not use any global filters but applies filters F2 and F3 to incoming log messages:

MANAGED_NODE
   {
   HOSTNAME      =   "marmalade"
   FILTER        =   "F2"
   FILTER        =   "F3"
   GLOBAL_FILTER =   "NO"
   }

Valid keywords for the MANAGED_NODE entry are described in Table 6-2.

Defining Agent Filters

In order to invoke a filter in an LC_GLOBAL or MANAGED_NODE entry, the filter must of course be defined, in a DEFINE_FILTER clause. If you use filters, the DEFINE_FILTER clause must appear in the configuration file before the LC_GLOBAL clause.

A DEFINE_FILTER entry has the following syntax:

DEFINE_FILTER "filtername"
if condition 
   {
   action_statement1
   [action_statement2]
   [action_statementN]
   }

You can specify one or more actions to be taken when condition evaluates to true.

A condition can be simple or complex. The following is an example of a filter that uses a simple condition:

DEFINE_FILTER "DropInfo"
if (MSGID == 8)
   {
   REMOTE = "NO"
   }

This entry defines a filter named DropInfo. This filter specifies that a message having a message ID of 8 is dropped, that is, it is not sent to the Log Central Central Collector. You might use such a filter to drop messages that you do not wish to monitor. By default, data collection agents send all messages to the Central Collector, that is, the default value of REMOTE is YES.

Complex conditions can be built up from simple conditions using logical operators. The following logical operators can be used to build up complex conditions.

For instance, the earlier DropInfo example might not suit your need if you are monitoring two subsystems which both have messages with a message ID of 8. You might want to only drop messages with a message ID of 8 from one of the subsystems. The following filter drops only messages with a message ID of 8 from subsystem NDB:

DEFINE_FILTER "DropInfo"
if ((SUBSYSTEM == "NDB") && (MSGID == 8))
   {
   REMOTE = "NO"
   }

Only attributes in the message header, or contents of the message body, can be used to define message filtering because only these components of the message are available to the data collection agents. The attributes contained in the message definition cannot be used for filtering at the local agent because they are stored in the Log Central database and are only accessible to the Central Collector.

Defining Conditions

The following keywords can be used to define conditions.

Note: String values must be enclosed in double quotes.

Table 6-5 describes the relations that can be used in defining conditions. Note that the symbols have a somewhat different interpretation for string arguments than for numeric arguments. Perhaps the most useful relational operator for strings is >=.

Defining Actions

You can specify one or more actions to be taken by a data collection agent when a condition evaluates to true. Three types of action statement are possible:

• Dropping a Message

• Executing a Command

• Sending an SNMP Trap Notification

Dropping a Message

You can instruct the data collection agent not to send the message to the central host: To do so, use an action statement of the following form:

REMOTE = "NO"

You can instruct the data collection agent to execute a program or invoke a shell script or batch file. To do so, use an action statement of the following form:

COMMAND = "executable_path [arguments]"

executable_path

The name of the program or script, including the full path.

You can instruct the data collection agent to send an SNMP trap notification when the filter's condition evaluates to true. To do so, use an action statement of the following form:

TRAPID = specific_trap_number

The data collection agent sends the numeric value entered for specific_trap_number in the specific trap ID field of the SNMP trap notification packet.

For example:

DEFINE_FILTER "AppTrap"
if ((SUBSYSTEM == "APP") && (MSGID = 11))
   {
   TRAPID = 5001
   }

This filter causes the data collection agent to generate an enterprise-specific SNMP trap with a specific trap ID of 5001 when the agent receives a message with a message ID of 11 from subsystem APP.

The valid keywords in the action part of a filter are shown in Table 6-6.

Example

You have one central host and six managed nodes. You have five filters (which we can number F1 through F5) that you want to apply this way:

• You want filters F1, F2, and F3 to apply to all hosts, except host H4, so you specify these three in an LC_GLOBAL entry.

• You want host H2 to have access to filter F4. Since F4 is not globally specified, you need a a MANAGED_NODE entry within which you specify filter F4. Host H2 already knows about filters F1, F2, and F3.

• You use the same technique for host H3, so that it can use filter F5.

• You want host H4 to use only filters F1 and F2; that is, you specifically do not want host H4 to inherit the three global filters. To accomplish this, you need a MANAGED_NODE entry, within which you "turn off" that inheritance with the GLOBAL_FILTER keyword. Doing so requires again individually specifying filters F1 and F2.

  Note: When you are assigning filters to a specific machine, be aware of the path syntax for the machine. For example, trying to use UNIX path syntax on a Windows NT machine could generate errors.

The following configuration file accomplishes this:

DEFINE_FILTER "F1"
if ((USER == "test") || (PID == 12))
  {
  REMOTE="NO"
  }
DEFINE_FILTER "F2"
if ( LOG_LEVEL == "D" )
  {
  LOCAL="/usr/mylogs/locallog"
  REMOTE="NO"
  }
DEFINE_FILTER "F3"
if ( MSGBODY >= "network" )
  {
  COMMAND="/usr/mybin/notify_admin"
  }
node
DEFINE_FILTER "F4"
if ( SUBSYSTEM =="KERNEL" && MSGBODY >= "fatal" )
  {
  COMMAND="/usr/mybin/notify_admin"
  TRAPID=123
  }
DEFINE_FILTER "F5"
if ((SUBSYSTEM == "NDB") && (MSGID == 12))
  {
  REMOTE="NO" 
  TRAPID=343
  }
LC_GLOBAL
  {
    CENTRAL_HOST     = "quahog"
    LOGPREFIX        = "/usr/lmlog"
    FILTER        = "F1"
    FILTER        = "F2"
    FILTER        = "F3"
  }
 
MANAGED_NODE
    {
    HOSTNAME     = "H2"
 
       FILTER       ="F4"
    }
 
MANAGED_NODE
    {
    HOSTNAME     = "H3"
 
       FILTER       ="F5"
    }
 
MANAGED_NODE
    {
    HOSTNAME     = "H4"
 
    # Do not use global filters
       GLOBAL_FILTER="NO"
       FILTER       ="F1"
       FILTER       ="F2"
    }

Use enough parentheses in the "if" statement in a filter definition to preclude ambiguities in the evaluation, since precedence rules are not followed strictly during evaluation.

Enclose any string value in double quotes.

Try to use filters as little as possible. Since each log message has to go through all of the filters, throughput can be adversely affected. The COMMAND action in particular is very costly.