Chapter 10   Configuring and Monitoring Logs


This chapter explains how to configure iPlanet Directory Access Router (iDAR) to log entries or messages and then monitor its activities with the help of the logged entries using the iDAR Server Console.

The chapter has the following sections:

• Overview of Logging

• Configuring Logs

• Monitoring Logs From iDAR Server Console

Overview of Logging

---

iDAR can maintain two types of logs:

• System Log

• Audit Log

The sections that follow explain both in detail.

System Log

iDAR can maintain extensive log records of various events and system errors so that you can monitor and debug the system. All log records can be maintained in text files and can be stored in your local file system for quick and easy retrieval. By default, iDAR writes log entries to this file:

<server-root>/idar-<hostname>/logs/fwd.log

Each message in the log file is time stamped. It also has the process number and a message number that is internal to iDAR.

For identification and filtering purposes, events logged by iDAR are classified into various categories. These are listed in Table 10-1. Each category represents messages that are of the same or a similar nature or that belong to a specific functional area. Based on the configuration, a log file can record entries that fall under one or more of these categories.

In the iDAR configuration, each message category corresponds to a specific log level. Log levels indicate the level of logging to be performed by the server—that is, how detailed the logging should be.

• A higher priority level means less detail because only events of high priority are logged.

• A lower priority level means greater detail because more kinds of events are recorded in the log file.

Table 10-1 lists the message categories in the descending order of priority—Critical has the highest priority level and Detailed trace has the lowest priority level.

Table 10-1    Log Levels  

Log Level or Severity	Description
Mandatory	Mandatory messages are those that are always printed to the log. These messages indicate the configuration that iDAR read, iDAR version number on startup, etc. Messages pertaining to this level is not configurable.
Critical	These messages indicate iDAR encountered some problems that needs immediate attention. For example, iDAR process 1234 has exited, attempting restart in 10 seconds.
Exception	These messages indicate unexpected error conditions, such as an incorrectly formatted LDAP message received from client/server by iDAR. For example, Could not decode search request.
Warning	These messages specify error conditions that iDAR can ignore but must be investigated by the administrator. For example, Local host name lookup failed. System default group may not function correctly.
Notice	These messages are informational. For example, Received NULL continuation reference from server. Discarding...
Trace	These are debug messages. For example, Result received from server lderr =32, matched=o=sun.com, errtxt=no such object.
Detailed trace	These messages provide more detailed debugging information such as Requested Anonymous bind for recycling connection. These messages usually have meaning for the iDAR engineering/support team.

iDAR enables you to specify the amount of logging—you can use log levels to filter log entries based on the severity of an event. By default, the level is set to Warning.

---

Note	The log level is additive; that is, if you choose Warning as the log level, Warning, Exception, and Critical level messages will be logged. Log data can be voluminous, especially at lower (more verbose) logging levels. Make sure that the host machine has sufficient disk space for all the log files.

---

Optionally, on platforms other than Windows NT, you can configure iDAR to send log messages to the syslog daemon instead of a file; you cannot send the log messages to both a file and to the syslog daemon at the same time. If you opt for this configuration, make sure that your syslogd is properly configured. For example, to have all the messages written to a particular file /var/adm/messages the following line must be added to the file /etc/syslog.conf:

daemon.crit;daemon.warning;daemon.info;daemon.debug /var/adm/messages

Note that iDAR uses the daemon facility, with the crit, warning, info, and debug priorities or log levels. Table 10-1 shows the mapping between syslog events and iDAR events.

Table 10-2    Mapping of Log Levels  

iDAR Event	syslog Event
Mandatory	info
Critical	crit
Exception	err
Warning	warning
Notice	info
Trace	info
Detailed trace	info

iDAR does not rotate logs. You need to do this manually and it will usually require a restart. If you can afford to lose a few messages, on the UNIX platforms, you can rotate logs with the following sequence of commands.

cp fwd.log /logvol/fwd.log.old
cp /dev/null fwd.log

By default, iDAR does not delete any of the log files automatically. Because the log files are saved in your local file system, these files eventually take up a considerable amount of disk space. You can avoid this problem by manually deleting the log files from the local file system. If you want to keep specific log files for future use, be sure to archive or back them up.

Audit Log

In addition to logging system and error messages, iDAR can also maintain audit trails for all events and connection statistics—for example, the DN of a client that just completed a bind/unbind with an LDAP directory can be logged.

By default, iDAR is not configured to log audit messages. You can enable this feature at any time. You can also specify whether to log audit messages to the same file to which system log entries are written or to an alternate file. Unless configured to write to a different file, the audit messages (along with the other log messages) are logged to the same file to which system log entries are written; for details, see System Log.

---

Note	Audit records enable you to detect any unauthorized access or activity. It's recommended that you enable this feature. Also, as a security measure, you should periodically examine the iDAR audit log for any unusual activity.

---

Configuring Logs

---

To configure iDAR to log entries, follow these steps:

• Step 1. Define a Logging Property

• Step 2. Specify the Logging Property to Use

Step 1. Define a Logging Property

This step is required only if you want to create or define an object for the Log Property. If you have already created objects for the log property and want to use one of them, then skip to the next step.

1. Access the iDAR Configuration Editor Console; see Accessing the iDAR Consoles.

2. In the navigation tree, expand the Properties node, and then select Logging.

   The right pane shows the list of existing objects for the logging property.

   
   
   

3. Click New to define a new object.

   The Log Property window appears.

   
   
   

4. In the Name field, type a name for the object. The name must be a unique alphanumeric string.

5. In the Statistics tab, specify the kind of information to be logged.

   Check the boxes referring to the type of logging messages desired. By default none of the options are selected. Log messages are classified into the following groups: directory modifications, all LDAP operations, network connections, number of clients connected, and client auditing information.

   Directory modifications. Statistics about operations that write to the directory, like add, modify, and delete will be logged.

   All LDAP operations. Statistics about all LDAP operations will be logged.

   Network connections. Statistics about network connections will be logged.

   Number of clients connected. General statistics such as how many clients are connected will be logged.

   Client auditing information. Audit information such as the DN of client that just completed a bind/unbind will be logged.

6. Select the Output tab and specify where log entries should be sent and whether to log audit traces.

   
   
   

   Log file. Displays options governing where iDAR will write its log entries.

   Write log entries to $(IDAR_ROOT)/logs/fwd.log. This is the default setting in which iDAR will write its log entries to the file $(IDAR_ROOT)/logs/fwd.log where $(IDAR_ROOT) is the directory under the server root where iDAR is installed, typically /usr/iplanet/servers/idar-<hostname> or \Program\Files\iPlanet\Servers\idar-<hostname>.

   Write log entries to. Specify an alternative file to which iDAR will direct its log entries. The file separator must follow UNIX conventions regardless of platform.

   Write logs to syslog daemon with facility. (UNIX only) Choose a syslog facility code that iDAR will use to log entries. This setting should only be chosen if this log property is to be used by iDAR server installed on a UNIX machine. Specifying this option for iDAR installed on a Windows NT system will make it inoperable. It is recommended that if you would like to specify values for this attribute, you should create separate log properties for Windows NT and UNIX.

   Audit File. Displays options governing where iDAR will write its audit log entries. For this feature to work, audit logging must be enabled by selecting the "Client auditing information" option in the Statistics tab.

   Write audit entries with other log entries. This is the default setting in which iDAR will write its audit log entries to the same output specified in the log file settings above.

   Write log entries to. Specify an alternative file to which iDAR will direct its audit log entries. The file separator should follow UNIX conventions regardless of platform.

   Write audits to syslog daemon with facility. (UNIX only) Choose a syslog facility code that iDAR will use to log audit entries. This setting should only be chosen if this log property is to be used by iDAR servers hosted on a UNIX machine. Specifying this option causes a Windows NT based iDAR to become inoperable. It is recommended that if you would like to specify values for this attribute, you should create separate Log Property objects for Windows NT and UNIX.

7. Select the Level tab and specify the log level—the amount of logging detail desired.

   Move the slider up to indicate more detail, or down to indicate less detail.

   
   
   

8. Click Save to save your changes.

   The name of the object now appears in the list. The iDAR configuration is modified, and you're prompted to restart the server.

9. Restart the server; see Restarting iDAR.

Step 2. Specify the Logging Property to Use

In this step, you select an existing log property to be used for logging messages.

1. Access the iDAR Server Console; see Accessing the iDAR Consoles.

2. Select the Configuration tab, and then, in the navigation tree, select Logs.

   The right pane shows information regarding the log property specified by the current system property.

   
   
   

3. In the "Log property name" drop-down list, select the property you want to use.

   To verify that you're using the correct property, click Edit and take a look at the configuration. If required, you can make any configuration changes.

4. Click Save to save your changes.

   iDAR is now configured to log messages as defined in the configuration. The iDAR configuration is modified, and you are prompted to restart the server.

5. Select the Tasks tab and restart the server; see Restarting iDAR.

Monitoring Logs From iDAR Server Console

---

Once you've configured iDAR to log messages (see Configuring Logs), you can monitor its activities by viewing the log messages. For example, when you have problems with iDAR that require troubleshooting, you may find it helpful to check the error or informational messages that the server has logged. Also, by examining the log files you can monitor many aspects of iDAR's operation.

To facilitate this, the iDAR Server Console provides a simple mechanism for viewing the contents of log files. The contents of the log file you choose to view are displayed in the form of a table. The table is split; the top pane shows log records in tabular format and the bottom pane shows the currently-selected record in detail. Each log record contains information such as the date and time the message was logged, the severity of the message, and a general description of the log.

Once you open a log file for viewing, you can read its contents partially by specifying the number of records or entries to be displayed. The instructions below explain how to view log records in a file:

1. Access the iDAR Server Console; see Accessing the iDAR Consoles.

2. Select the Configuration tab, and then, in the navigation tree, expand Logs.

3. Select Log File.

   The right pane shows viewing options for entries logged to a file. You can select any of the log files specified in the current log property; iDAR can contain separate files for logging and auditing information, if configured to do so.

   
   
   

   Description of the form elements are as follows:

   Refresh. Reads the log and displays the records in the table below.

   Continuous. Select this setting to have this view continuously refreshed with the most current log records.

   Log file. Displays the name of the file currently being viewed.

   Lines to show. Specifies the maximum number of lines to read from the log file.