# Chapter 6. Host and Filter Configuration

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.

## Default Configuration

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.

> Table 6-1 LC_GLOBAL Keywords

Keyword | Data Type | Description
--- | --- | ---
`CENTRAL_HOST` | `string` | The host name of the central host, which is a mandatory field.
`LOGPREFIX` | `string` | The base name of the intermediate log message files used by the `msg_receiver` process running on the central host. This is a mandatory field.
`BACKUP_HOST` | `string` | The host name of the machine where the backup Central Collector runs. This field is optional. If this field is not specified, no backup central host configuration is made.
`BACKUP_LOGPREFIX` | `string` | The base name of the intermediate log message files used by the `msg_receiver` process running on the backup central host. This field is optional unless the `BACKUP_HOST` keyword has been specified, in which case it is mandatory. There is no default for this field.
`TALK_SERVICE` | `string` | The service name used for communication between the `msg_sender` processes and the `msg_receiver` process running on the central host or on the backup host. This is an optional field. The default value of this field is `lc_talk`.
`IPCKEY` | `integer` | The IPC key for the Log Central subsystem. This is an optional field, unless you have more than one Log Central system. For details on how to handle this situation, refer to Appendix B, "Environment Variables." The default value of this field is `0xeeee0000`. `IPCKEY` can take any numeric value. Use 0x to indicate a hexadecimal value.
`INIFILE` | `string` | The initialization file used by the `msg_processor` process. This is an optional field. The default value of this field is `install_dir``/etc/msg_processor.ini`.
`ESCALATION_DIR` | `string` | The directory for storing temporary log files on managed nodes. The name of the temporary log file directory is the same for all of the Log Central hosts. (It can be a local or remote file system, but the name should be same.) This is an optional field. The default value of this field is `/tmp` on UNIX (`C:\tmp` on NT).
`FILTER` | `string` | The filter identifier, if any filtering is required. (This option can be repeated to specify multiple filters.) This is an optional field. There is no default for this field. If no `FILTER` entry is specified in the `LC_GLOBAL` entry, no global filter is present.

## 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"
>        }

#### Assigning a Filter to a Particular Node

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.

> Table 6-2 Valid Keywords for the MANAGED_NODE Entry

Keyword | Data Type | Description
--- | --- | ---
`HOSTNAME` | `string` | The host name to which this `MANAGED_NODE` entry applies. This is a mandatory field.
`FILTER` | `string` | The filter identifier, if any filtering is required. (This option can be repeated to specify multiple filters.)
`GLOBAL_FILTER` | `string` | Specifies whether to include global filters or not (if this keyword is not specified, global filters are included). Valid values are `YES` and `NO`.

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

> Table 6-3 Logical Operators for Use in Defining Conditions

Syntax | Interpretation
--- | ---
`!(``condition``)` | Evaluates to true when `condition` is false.
`(``condition1``) && (``condition2``)` | Evaluates to true if both `condition1` and `condition2` are true.
`(``condition1``) || (``condition2``)` | Evaluates to true if either `condition1` or `condition2` (or both) is true.

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.

> Table 6-4 Keywords for Use in Defining Conditions

Keyword | Data Type | Message Attribute
--- | --- | ---
PID | Number | Process ID
MSGID | Number | Message ID
SUBSYSTEM | String | Subsystem name
LOG_LEVEL | String (one of `N`, `V`, `D`, or `S`) | Logging level
HOST | String | Host name
FUNCTION | String | Name of the internal function that issued the message. This can be up to 40 characters in length.
TXKEY | String | Transaction key. This string can be up to 20 characters in length.
USER | String | User ID
MSGBODY | String | String to test for a match in the body of the message

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 >=.

> Table 6-5 Relations for Use in Defining Conditions

Symbol | Meaning
--- | ---
`==` | Numeric: Is equal to String: Is identical to
`!=` | Numeric: Is not equal to String: Does not match
`>=` | Numeric: Greater than or equal to String: Contains or is the same as
`<=` | Numeric: Less than or equal to String: Is a substring of or is the same as
`>` | Numeric: Greater than String: Contains and is not the same as
`<` | Numeric: Less than String: Is a substring of and is not the same as

### 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"

#### Executing a Command

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.

#### Sending an SNMP Trap Notification

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.

> Table 6-6 Keywords for Use in Defining an Action

Construct | Data Type | Description
--- | --- | ---
REMOTE | String | `YES` or `NO`. If you specify `NO`, the message is dropped.
LOCAL | String | `/path/filename`
COMMAND | String | `/path/command arg1 arg2`
TRAPID | Integer | Enterprise-specific SNMP trap ID.

### 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:

Host | Filter Combination
--- | ---
H1 | F1, F2, F3
H2 | F1, F2, F3, F4
H3 | F1, F2, F3, F5
H4 | F1, F2
H5 | F1, F2, F3
H6 | F1, F2, F3

- 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"
>         }

### Filter Recommendations

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.