# Chapter 8. Starting and Stopping Log Central

To use Log Central, you need to start a Central Collector on your central host and start the agents on the managed nodes.

This chapter discusses the following topics:

- Starting the Log Central Data Collection System

- Stopping the Log Central Data Collection System

- Displaying Log Central System Information

The procedures for starting Log Central described in this chapter assume that you have completed the initial configuration steps discussed in Chapter 2, "Getting Started."

## Starting the Log Central Data Collection System

The procedure for starting Log Central follows:

1. Run the `start_messaging` command on the central host to start the Central Collector.

After starting the Central Collector, the `start_messaging` process continues to run and acts as the server of the host and filter configuration to the `start_messaging` process on managed nodes. The `start_messaging` command also starts the Process Monitor (the `proc_monitor` process). The Process Monitor monitors the `start_messaging` process to ensure that it continues to run and restarts it if it dies. The `start_messaging` process in turn monitors the `proc_monitor` process and restarts it if it dies.

Because Log Central processes on the central host provide Log Central agents with their configuration information when they are started, the Central Collector must be started before any of the data collection agents are started

This is described under "Starting Log Central on a Central Host."

Note: If you are using a backup Central Collector, start it at this time also.

2. On each managed node, use the `start_messaging` command to start the Message Sender and Process Monitor.

   This is described under "Starting Log Central on the Managed Nodes."

3. On each managed node, start a Log Monitor process for each log resource that you wish to manage.

   This is described under "Starting Log Monitor."

### Starting Log Central on a Central Host

The `start_messaging` command starts Log Central components on the central host. The minimum set of components started by the `start_messaging` command on the central host are:

- Message Receiver (`msg_receiver`)

- Message Processor (`msg_processor`)

- Process Monitor (`proc_monitor`)

- Message sender (`msg_sender`)

To use the `start_messaging` command on the central host, enter the following command:

>     start_messaging [-f config_file] [-q] [-v] [-h] [central_host]
>     [backup_central_host]

where:

`-f` `config_file`
  Uses `config_file` as the Log Central configuration file in place of the default (`install_dir``/etc/messaging.conf`).

`-q`
  Makes the process "quiet"; that is, no informational messages are displayed.

`-v`
  Specifies the verbose option, which displays informational and debug messages.

`-h`
  Prints out detailed usage information.

`central_host`
  Specifies the host name of the machine acting as the primary central host. If not specified, the current host is considered to be the central host. This parameter must be specified when starting the Log Central system on the backup host or a managed node.

`backup_central_host`
  Specifies the host name of the machine where the backup Central Collector is running. Data collection agents connect to the backup Central Collector if the Central Host cannot be reached.

Note: You need to specify a backup central host with the `start_messaging` command only if you are starting a data collection agent on the central host in addition to a Central Collector.

Because Log Central processes on the central host provide Log Central agents with their configuration information when they are started, the Central Collector must be started before any of the data collection agents are started.

After being invoked, the `start_messaging` process continues to run and can be used to stop the Central Collector (and other central host Log Central processes) by invoking the `stop_messaging` command. Use of the `stop_messaging` command is described in "Stopping the Log Central Data Collection System."

The `start_messaging` process must be able to find the Log Central configuration file (`messaging.conf`). The default location of this file is:

- `install_dir``/etc/messaging.conf` on UNIX systems

- `install_dir``\etc\messaging.conf` on Windows NT systems

The `install_dir` variable is the directory under which you installed Log Central.

If you want `start_messaging` to use a configuration file that does not reside in the default location, invoke `start_messaging` with the`-f` option to provide a path to the file.

When starting a backup Central Collector, you must specify the `central_host` parameter. It is not necessary to specify the `central_host` when starting the primary Central Collector because `start_messaging` assumes that the machine it is invoked on is the central host if this parameter is not specified.

Once the `start_messaging` process is started on the central host, changes made to the Log Central configuration file will not take effect until the next time the Log Central processes are started using the `start_messaging` command.

### Starting Log Central on the Managed Nodes

A managed node is any machine remote from the Central Collector that has log resources that you want to monitor. To start the Log Central processes on a managed node, do the following:

1. Start the Message Sender and Process Monitor by invoking the `start_messaging` command. The syntax for the `start_messaging` command, when used on a managed node, follows:

    start_messaging [-q] [-v] [-h] [central_host
    [backup_central_host]]

where:

`-q`
  Makes the process "quiet"; that is, no informational messages are displayed.

`-v`
  Specifies the verbose option, which displays informational and debug messages.

`-h`
  Prints out detailed usage information.

`central_host`
  Specifies the host name of the machine where the primary Central Collector is running. If not specified, the current host is assumed to be the central host.

`backup_central_host`
  Specifies the host name of the machine where the backup Central Collector is running. Data collection agents connect to the backup Central Collector if the primary Central Collector cannot be reached.

Note: You must have already invoked the `start_messaging` command on the central host.

2. Start a Log Monitor process for each log resource that you want to monitor.

This is described under "Starting Log Monitor."

Note: You must invoke the `start_messaging` command on the managed node before starting the Log Monitor processes.

To start the Log Central subsystem on a managed node, you must supply the name of the central host to the `start_messaging` process. The `start_messaging` process on the managed node connects to the `start_messaging` process running on the central host, using the `udp` service defined by the environment variable `BEA_LC_CONF_SERVICE`. The `start_messaging` process on the managed node then downloads the local host's configuration. If `BEA_LC_CONF_SERVICE` is not defined, a service called `lc_conf` is used by default. The `start_messaging` process then starts the Log Central subsystem according to the configuration received from the central host.

### Starting Log Monitor

You must start a Log Monitor process for each log that you want to monitor on a managed node. The Log Monitor reads the logs generated by the managed resource, such as a computer system, a BEA TUXEDO application, or a relational database system. Log Monitor maps the attributes in the managed resource log messages to attributes in Log Central messages. Messages are then placed in the Message Sender's queue for forwarding to the Central Collector.

You can instruct Log Monitor to map log messages to Log Central message format for forwarding to the Central Collector in three ways:

- Using a predefined mapping, which is described under "Starting Log Monitor with Predefined Mappings."

- Using a configuration file in which you have defined a mapping, which is described in "Starting Log Monitor with Mappings in a Configuration File."

- By specifying the mapping options on the command line, which is described in "Starting Log Monitor with Mapping Specified on the Command Line."

#### Starting Log Monitor with Predefined Mappings

Predefined mappings are available for integrating the following log resources into the Log Central system:

- `TUXEDO`-Used for mapping BEA TUXEDO logs

- `NTEVENTLOG`-Windows NT event log

- `ORACLE`-Oracle alert log

- `LC`-Log Central temporary log files

  Note: For usage of LC, see "Using the LC Predefined Mapping."

To invoke Log Monitor with a predefined mapping, use the following command:

>     log_monitor -i filename -P predefined_mapping [ -t time ]
>     [ -p pattern ] [ -x pattern ] [ -e entityname ]

where:

-i filename
  This option specifies the incoming message file to use. You can also use a dash (`-i -`) to specify standard input.

`-P` `predefined_mapping`
  This option tells Log Monitor to use a built-in message format mapping. The argument can be any one of the following:

`TUXEDO
LC
NTEVENTLOG
ORACLE`

-t `time`
  This option specifies the amount of time to wait between forwards. The default is one second (that is, 1). Use 0 to forward once and then stop.

-p `pattern`
  This option instructs the program to forward only lines that match `pattern`, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

-x `pattern`
  This option instructs the program not to forward lines that match `pattern`, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

-e `entityname`
  This option specifies the entity name to be used by the `log_monitor` process to register to the `proc_monitor` process. The default value is `log_monitor`. All Log Monitors on one managed node must have unique entry names. If the log_monitor process is run as a daemon (with`-t 0`), then the entity name option is not used.

The `-p` option can be used to select only certain messages for forwarding. The `-x` option can be used to select messages to be dropped. For more information, refer to Chapter 4, "Integrating Logs into Log Central."

For details about the predefined mappings, refer to Appendix G, "Predefined Log Mapping."

##### Using the LC Predefined Mapping

Log Central processes create temporary log files, which exhibit a common log file format. Normally the contents of these files make their way into the Log Central database through normal operation of the system. There are two abnormal situations where you might need to use Log Monitor to recover the contents of these files:

- A Message Sender writes log messages to a temporary file if the central host is unavailable. When the Central Collector becomes available again, the Message Sender automatically forwards the log messages from the temporary file to the Central Collector. However, if the Message Sender dies before it can recover the file, the temporary file may not be recovered automatically. If this happens, you can recover the contents of this temporary file by starting a Log Monitor to read the temporary log file, using the LC mapping.

- The Message Receiver on the central host writes incoming messages to an intermediate file. The Message Processor reads this file to insert these messages into the database. If for some reason an intermediate file does not get processed by the Message Processor, you can recover the contents of the intermediate file by invoking Log Monitor to read the intermediate file, using the LC mapping.

These are the only situations where you would start Log Monitor with the LC mapping.

#### Starting Log Monitor with Mappings in a Configuration File

A configuration file is simply a list of Log Monitor filters, each on a separate line. A log message will be forwarded by the Log Monitor if it is selected by at least one of the filters in the configuration file.

For information on constructing mappings in a Log Monitor configuration file, refer to Chapter 4, "Integrating Logs into Log Central."

The syntax for invoking Log Monitor with a configuration file follows:

>     log_monitor -f config_filename -i filename [-t time] [-c]
>     [-e entityname]

where:

`-f` `config_filename`
  This option specifies the configuration file from which to read filters.

`-i` `filename`
  This option specifies the incoming message file to use. You can also use a dash (`-i -`) to specify standard input.

`-t` `time`
  This option specifies the amount of time to wait between forwards. The default is one second (that is, 1). Use 0 to forward once and then stop.

`-c`
  This option applies the commands in the configuration file only up to the first match in the configuration file.

For examples, see Chapter 4, "Integrating Logs into Log Central."

`-e` `entityname`
  This option specifies the entity name to be used by the `log_monitor` process to register to the `proc_monitor` process. The default value is `log_monitor`. All Log Monitors on one managed node must have unique entry names. If the `log_monitor` process is run as a daemon (with`-t 0`), then the entity name option is not used.

#### Starting Log Monitor with Mapping Specified on the Command Line

The syntax for invoking Log Monitor by specifying all options on the command line follows:

>     log_monitor -i filename [-t time] [-M log_level] [-m subsystem]
>        [-d msgid] [-n function] [-u userID] [-o hostname] [-I processID]
>        [-b body] [-D date] [-p pattern] [-x pattern] [-T transactionID]
>        [-P predefined_mapping] [-e entityname] [-S]

where:

`-i` `filename`
  This option specifies the incoming message file to use. You can also use a dash (`-i -`) to specify standard input.

`-t` `time`
  This option specifies the amount of time to wait between forwards. The default is one second (that is, 1). Use 0 to forward once and then stop.

`-M` `log_level`
  This option specifies the logging level to use in the message. Logging level is a single character that must be one of the following:

`N`-A normal message

`V`-A verbose message

`D`-A debug message

`S`-A special message

`-m` `subsystem`
  This option specifies the subsystem name to use in the message. The default is none.

`-d` `msgid`
  This option specifies the message ID to use in the message. The default is `1000`.

`-n` `function`
  This option specifies the function name to use in the message. The default is none.

`-u` `userID`
  This option specifies the user ID to use in the message. The default is the current user (that is, the owner of the `log_monitor` process).

`-o` `hostname`
  This option specifies the host name to use in the message. The default is the machine on which Log Monitor is running.

`-I` `processID`
  This option specifies the process ID to use in the message. The default is the process ID of the daemon process invoked by the Log Monitor command.

`-b` `body`
  This option specifies the body of the message.

`-D` `date``%f"``format``"`
  This option specifies the date to use in the message. For information on specifying the date format, see Chapter 4, "Integrating Logs into Log Central."

`-p` `pattern`
  This option instructs the program to forward only lines that match `pattern`, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

`-x` `pattern`
  This option instructs the program not to forward lines that match `pattern`, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

`-T` `transactionID`
  This option specifies the transaction ID to use in the message. The default is 0.

`-P` `predefined_mapping`
  This option tells Log Monitor to use a built-in message format mapping. The argument can be any one of the following:

`TUXEDO
LC
NTEVENTLOG
ORACLE`

`-e` `entityname`
  This option specifies the entity name to be used by the `log_monitor` process to register to the `proc_monitor` process. The default value is `log_monitor`. All Log Monitors on one managed node must have unique entry names. If the `log_monitor` process is run as a daemon (with`-t 0`), then the entity name option is not used.

`-S`
  This option specifies one or more separators to be used to calculate field values in the input message file for corresponding `%F` specifiers on a command line. (The `%F` format symbol is described in Chapter 4, "Integrating Logs into Log Central.")

If more than one separator is specified, all are used to count the fields. If a message starts with a separator, the text between the first and the second separator is counted as field number 1; fields are numbered starting with 1 (not 0). If a message does not start with a separator, the first field consists of the text up to the first separator.

For examples, see Chapter 4, "Integrating Logs into Log Central."

A number of these options refer to specific attributes in a Log Central log message, such as message ID or process ID. The Log Central message format is described in Appendix A, "Message Format."

For information on how to use these options to construct mappings, consult Chapter 4, "Integrating Logs into Log Central."

## Stopping the Log Central Data Collection System

To stop the Log Central data collection system, you must issue the `stop_messaging` command on each node where Log Central components are running.

The syntax of the `stop_messaging` command follows:

>     stop_messaging [-q] [-v] [-h]

where:

`-q`
  Makes the process "quiet"; that is, no informational messages are displayed.

`-v`
  Specifies the verbose option, which displays informational and debug messages.

`-h`
  Prints out detailed usage information.

When Log Monitor starts, it registers with the `proc_monitor` process. This enables the `stop_messaging` process to stop the Log Monitor processes when you issue the `stop_messaging` command to shut down the Log Central system. No separate command is required to shut down the Log Monitor processes.

## Displaying Log Central System Information

Log Central includes a command, `show_config`, that enables you to display the current state of your Log Central configuration file, compile the configuration file, or display Log Central shared memory information.

Depending upon the arguments or options you enter, the `show_config` command compiles the configuration file or dumps the Log Central shared memory information to `stdout`. You can use this command to see if all processes are up or what processes are no longer running and to check for other system maintenance indicators.

The syntax of the `show_config` command follows:

>     show_config -c [-f config_file] | -g | -p | -d | -e entity_name [-h]

where:

`-c`
  Check syntax errors in configuration file.

`-f` `config_filename`
  This option specifies the name of the Log Central configuration file to use with the `-c` option. If this option is not specified, `install_dir``/etc/messaging.conf` is taken as the default. The `install_dir` variable is the directory in which Log Central was installed.

`-g`
  Dumps the Log Central global information from shared memory to `stdout`.

`-p`
  Dumps the `proc_monitor` shared memory information about the processes being monitored to `stdout`.

`-d`
  Dumps the whole Log Central shared memory to `stdout`. This option is equivalent to using both the `-g` and `-p` options.

`-e` `entityname`
  This option specifies the entity name to be used by the `log_monitor` process to register to the `proc_monitor` process. The default value is `log_monitor`. All Log Monitors on one managed node must have unique entry names. If the `log_monitor` process is run as a daemon (with`-t 0`), then the entity name option is not used.

`-h`
  Prints out detailed usage information.

### Example

Before using your configuration file at run time, you may wish to check for syntax errors. To validate your configuration file, run the following command:

>     show_config -c -f config_file

In the preceding command, if the `-f` option is not specified, the file `install_dir``/etc/messaging.conf` is used by default.

The `show_config` command displays syntax errors to `stdout`, showing line and character position.

Note: Avoid the use of tabs in your configuration file because they can cause the character positions reported to be inaccurate.