Chapter 8   Log Plug-in Modules


iPlanet Certificate Management System (CMS) can record events related to its activities, such as administration, communications using any of the protocols the server supports, and various other processes employed by all the subsystems that the server manages. To monitor these events, you need to capture them in to a repository. For this purpose, Certificate Management System provides plug-in modules. This chapter explains the log modules—it lists and briefly describes the modules and then explains each one in detail.

The chapter has the following sections:

• Overview of Log Modules

• file Plug-in Module

• NTEventLog Plug-in Module

Overview of Log Modules

---

You can configure a CMS instance to log messages related to specific activities when events relevant to those activities occur. Log messages are event-driven—that is, whenever an event occurs, Certificate Management System generates the message and writes it to the configured repository. Event-driven logging involves a listener class in the CMS instance that registers an interest in an appropriate event such as a failed enrollment request.

Log plug-in modules discussed in this chapter are listeners, which are implemented as Java classes and are registered in the CMS policy framework. The Log Event Listener Plugin Registration tab of the CMS window (Figure 8-1) lists all the modules that are registered with a CMS instance.

Figure 8-1    Default log modules

Table 8-1 lists the log modules provided for a CMS instance.

Table 8-1    Log plug-in modules  

Plug-in module name	Function
file	Logs messages to a file. For details, see "file Plug-in Module".
NTEventLog	Logs messages to Windows NT Event log (when you run a CMS instance on a Windows NT system). For details, see "NTEventLog Plug-in Module".

Note that the name of the Java class for a log plug-in is in this format:

com.netscape.certsrv.logging.<plugin_name>

where <plugin_name> is the name of a plug-in module. For example, the Java class for the NTEventLog module would be:

com.netscape.certsrv.logging.NTEventLogs

After you take a look at the default log modules, if you determine that they do not meet your requirements entirely, you can develop a custom module. Check the CMS software development kit (SDK) installed at this location: <server_root>/cms_sdk/cms_jdk

file Plug-in Module

---

The file module enables you to configure Certificate Management System to log audit, error, and system messages to a file. The module also enables you to specify the following:

• Filename

• Log level or message category

• Rollover criteria, which can be based on the size or age of the file

• Expiration time for rotated logs

During installation, Certificate Management System automatically creates three instances of the file modules for logging audit, error, and system messages.

The listeners are named as follows:

• Audit (see "Audit Log Event Listener")

• Error (see "Error Log Event Listener")

• System (see "System Log Event Listener")

You need to review these listeners and make the changes appropriate for your PKI setup. For instructions, see "Configuring CMS Logs" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide.

Configuration Parameters of file

In the CMS configuration file, the file module is identified as log.impl.file.class=com.netscape.certsrv.logging.RollingLogFile.

In the CMS window, the module is identified as file. Figure 8-2 shows how configurable parameters for the module are displayed in the CMS window.

Figure 8-2    Parameters defined in the file module

Table 8-2 gives details about each of these parameters and their values.

Table 8-2    Description of parameters defined in the file module  

Parameter	Description
type	Specifies the log (or event) type. Permissible values: audit or system. Select audit for Audit logs and system for Error and System logs. The default selection is audit. Example: audit
enabled	Specifies whether the listener is enabled to log messages. Check the box if you want the server to log messages of the type specified in the type field. Leave the box unchecked if you do not want the server to log messages of this type.
level	Specifies a message category that represents the level of logging to filter messages. Log levels are additive. Before selecting a level, be sure to read "Log Levels (Message Categories)" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide. Permissible values: Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. By default, the level is set to Information. Example: Debug
fileName	Specifies the file path for the active log file; when the file is rotated, its name will be appended with a timestamp. For details, see "Timing of Log File Rotation" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide Permissible values: Absolute path to the file, including the filename. Example: C:\cms\server4\cert-demoCA\logs\audit.log
bufferSize	Specifies the buffer size, in kilobytes (KB), for the active log file. For details, see "Buffered Versus Unbuffered Logging" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide. Permissible values: As applicable. The default value is 512. Example: 512
flushInterval	Specifies the flush interval, in seconds, for the active log file; when the file reaches the specified interval, the buffer will be flushed to the file. For details, see "Timing of Log File Rotation" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide Permissible values: As applicable. The default value is 5. Example: 5
maxFileSize	Specifies the file size, in kilobytes (KB), for the active log file; the file will be rotated when its size reaches or exceeds the specified value. For details, see "Timing of Log File Rotation" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide Permissible values: As applicable. The default value is 100. Example: 100
rolloverInterval	Specifies the frequency for rotating the active log file; the file will be rotated when its age is equal to or older than this interval. For details, see "Rotation of Log Files" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide. Permissible values: Hourly, Daily, Weekly, Monthly, and Yearly. The default selection is Hourly. Example: Weekly
expirationTime	Specifies the interval at which the server should delete the rotated log file; the file will be deleted when its age is equal to or older than this interval. By default, the rotated log files are not deleted. For details, see "Timing of Log File Deletion" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide. Permissible values: An appropriate value in seconds. For example, if you want the files to be deleted every 30 days, you would type 2592000 (60x60x24x30) seconds. Example: 2592000

Audit Log Event Listener

The event listener named Audit is an instance of the file module. Certificate Management System automatically creates this listener during installation. By default, the listener is configured as follows:

• The rule is enabled.

• The type is set to log audit messages (type=audit).

• The log level for the active log file is set to 1 (level=Information).

• Log messages are written to a file named audit.log, which is at: <server_root>/cert-<instance_id>/logs/

• The buffer size for the active log file is set to 512 KB (bufferSize=512).

• The interval for flushing the buffer to the file is set to 5 seconds (flushInterval=5).

• The size limit for the active log file is set to 100 KB (maxFileSize=100).

• The rollover interval for the active log file is set to monthly or every 30 days (rolloverInterval=Monthly).

• Expiration time for the rotated log files is set to 0 seconds (expirationTime=0).

For details on individual parameters defined in the listener, see Table 8-2.

Error Log Event Listener

The event listener named Error is an instance of the file module. Certificate Management System automatically creates this listener during installation. By default, the listener is configured as follows:

• The rule is enabled.

• The type is set to log error messages (type=system).

• The log level for the active log file is set to 3 (level=Failure).

• Log messages are written to a file named error.log, which is at: <server_root>/cert-<instance_id>/logs/

• The buffer size for the active log file is set to 512 KB (bufferSize=512).

• The interval for flushing the buffer to the file is set to 5 seconds (flushInterval=5).

• The size limit for the active log file is set to 100 KB (maxFileSize=100).

• The rollover interval for the active log file is set to monthly or every 30 days (rolloverInterval=Monthly).

• Expiration time for the rotated log files is set to 0 seconds (expirationTime=0).

For details on individual parameters defined in the listener, see Table 8-2.

System Log Event Listener

The event listener named System is an instance of the file module. Certificate Management System automatically creates this listener during installation. By default, the listener is configured as follows:

• The rule is enabled.

• The type is set to log system messages (type=system).

• The log level for the active log file is set to 3 (level=Failure).

• Log messages are written to a file named system.log, which is at: <server_root>/cert-<instance_id>/logs/

• The buffer size for the active log file is set to 512 KB (bufferSize=512).

• The interval for flushing the buffer to the file is set to 5 seconds (flushInterval=5).

• The size limit for the active log file is set to 100 KB (maxFileSize=100).

• The rollover interval for the active log file is set to monthly or every 30 days (rolloverInterval=Monthly).

• Expiration time for the rotated log files is set to 0 seconds (expirationTime=0).

For details on individual parameters defined in the listener, see Table 8-2.

NTEventLog Plug-in Module

---

The NTEventLog module enables you to configure Certificate Management System to write both audit and system logs to the Event Log of a Windows NT system. If you've installed Certificate Management System on a Windows NT system, the CMS window allows you to turn this feature on or off and to specify the levels for logging.

During installation, Certificate Management System automatically creates two instances or listeners of the NTEventLog modules for logging audit and system messages.

The listeners are named as follows:

• NTAudit (see "NTAudit Event Listener")

• NTSystem (see "NTSystem Event Listener")

Note that by default both the listeners are enabled. You need to review these listeners and make the changes appropriate for your PKI setup. For instructions, see "Configuring CMS Logs" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide.

Configuration Parameters of NTEventLog

In the configuration file, the NTEventLog module is identified as log.impl.NTEventLog.class=com.netscape.certsrv.logging.NTEventLog.

In the CMS window, the module is identified as NTEventLog. Figure 8-3 shows how configurable parameters of the module are displayed in the CMS window.

Figure 8-3    Parameters defined in the NTEventLog module

Table 8-3 gives details about each of these parameters and their values.

Table 8-3    Description of parameters defined in the NTEventLog module  

Parameter	Description
type	Specifies the log (or event) type. Permissible values: audit or system. Select audit for audit logs and system for error and system logs. Example: system
enable	Specifies whether the listener is enabled to log messages. Check the box if you want the server to log messages of this type. Leave the box unchecked if you do not want the server to log messages of this type.
level	Specifies a message category that represents the level of logging to filter messages. For details, see section "Log Levels (Message Categories)" in Chapter 23, "Managing CMS Logs" of CMS Installation and Setup Guide. Permissible values: Debug, Info, Warning, Failure, Misconfiguration, Catastrophe, and Security. Example: Info
NTEventSourceName	Specifies the name of the CMS instance that's logging the messages.

NTAudit Event Listener

The event listener named NTAudit is an instance of the NTEventLog module. Certificate Management System automatically creates this listener during installation. By default, the listener is configured as follows:

• The rule is enabled.

• The type is set to log audit messages (type=audit).

• The log level is set to 1 (level=Information).

• The event source identifies the name of the CMS instance that's logging the events.

For details on individual parameters defined in the listener, see Table 8-3.

NTSystem Event Listener

The event listener named NTSystem is an instance of the NTEventLog module. Certificate Management System automatically creates this listener during installation. By default, the listener is configured as follows:

• The rule is enabled.

• The type is set to log system messages (type=system).

• The log level is set to 2 (level=Warning).

• The event source identifies the name of the CMS instance that's logging the events.

For details on individual parameters defined in the listener, see Table 8-3.