Chapter 23   Managing CMS Logs


Each instance of iPlanet Certificate Management Server (CMS) maintains its own system, error, and audit log files. These files record events related to various CMS activities. By configuring logs, you can customize the contents in the log files.

This chapter explains how to use the CMS window to configure the system, error, and audit logs maintained by Certificate Management System, and how to monitor its activities by viewing log contents.

The chapter has the following sections:

• Introduction to Logs

• Configuring CMS Logs

• Monitoring CMS Logs

• Archiving of Rotated Log Files

• Managing Log Modules

Introduction to Logs

---

iPlanet Certificate Management Server (CMS) creates log files that 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 the server manages.

This section identifies various logs maintained by Certificate Management System and describes them in detail.

• Logs Maintained by the Server

• Services That Are Logged

• Log Levels (Message Categories)

• Log File Locations

• Log File Naming Conventions

• Buffered Versus Unbuffered Logging

• Rotation of Log Files

• Deletion of Log Files

Logs Maintained by the Server

While Certificate Management System is running, it keeps a log of information and error messages on all the components it manages. These messages are broadly categorized into three separate groups and are maintained in three separate log files, as listed in Table 23-1.

During installation, Certificate Management System automatically creates the required log files in your local file system. The server creates common system, error, and audit files for all components that were installed together, and it logs messages to these files. For example, if you installed a Certificate Manager and a Data Recovery Manager together, you will find log messages for both the subsystems in the same log file.

Table 23-1    Types of logs maintained by Certificate Management System  

Log type	Description
System	This log records information about requests to the server (all HTTP and HTTPS requests) and the responses from the server. Information recorded in this log includes the IP address of the client machine that accessed the server, operations performed (for example, search, add, edit), and the result of the access (for example, the number of entries returned). This log is on by default. For more information, see Configuring CMS Logs and Monitoring System Logs.
Error	This log contains the error messages the server has encountered (HTTP errors and errors with the certificate service). This log is on by default. For more information, see Configuring CMS Logs and Monitoring Error Logs.
Audit	This log records messages specific to the certificate service—messages such as certificate requests, certificate renewal and revocation requests, and CRL publication—and enables you to detect any unauthorized access or activity. This log is on by default. For more information, see Configuring CMS Logs and Monitoring Audit Logs.

Services That Are Logged

All major components and protocols (or services) of Certificate Management System log messages to log files. Table 23-2 lists services that are logged by default. If you want to view messages logged by a specific service, you can customize log settings accordingly. For details, see Monitoring CMS Logs.

Table 23-2    Services logged by Certificate Management System  

Service	Description
ACLs	Specifies logged events related to access control lists.
Administration	Specifies logged events related to this server's administration activities---that is, HTTPS communication between the CMS window and Certificate Management System.
All	Specifies logged events related to all the services.
Authentication	Specifies logged events related to this server's activity with the authentication module.
Certificate Authority	Specifies logged events related to the Certificate Manager.
Database	Specifies logged events related to this server's activity with the internal database.
HTTP	Specifies logged events related to the HTTP activity of the server.
Key Recovery Authority	Specifies logged events related to the Data Recovery Manager.
LDAP	Specifies logged events related to this server's activity with the LDAP directory (used for publishing certificates and CRLs).
OCSP	Specifies logged events related to OCSP.
Others	Specifies logged events related to other activities of this server, such as command-line utilities and other processes.
Registration Authority	Specifies logged events related to the Registration Manager.
Request Queue	Specifies logged events related to the request queue activity of this server.
User and Group	Specifies logged events related to users and groups managed by this server.

Log Levels (Message Categories)

For identification and filtering purposes, events logged by all CMS-supported services are classified into various categories. These are listed in Table 23-3. Each category represents messages that are of the same or a similar nature or that belong to a specific functional area. A particular log, for example the error log, can record entries that fall under one or more of these categories.

In the CMS configuration, each message category corresponds to a specific log level. Log levels are represented by numbers (digits) 1 to 6, each digit indicating the level of logging to be performed by the server—that is, how detailed the logging should be.

• A higher priority level (a larger digit) means less detail because only events of high priority are logged.

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

  
  

  Table 23-3    Classification of log entries or messages  
  
  

  Log level	Message category	Description
  0	Debugging	These messages contain debugging information.
  1	Informational (default selection for audit log)	These messages provide general information about the state of Certificate Management System. For example, status messages such as "Certificate Management System initialization complete" and "Request for operation succeeded" fall into this category.
  2	Warning	These messages are warnings only and do not indicate any failure in the normal operation of the server.
  3	Failure (default selection for system and error logs)	These messages indicate errors and failures that prevent the server from operating normally. Examples of messages that fall into this category include failures to perform a certificate service operation ("User authentication failed" or "Certificate revoked") and unexpected situations that can cause irrevocable errors ("The server cannot send back the request it processed for a client through the same channel the request came from the client").
  4	Misconfiguration	These messages indicate that a misconfiguration in the server is causing an error.
  5	Catastrophic failure	These messages indicate that because of an error, the service cannot continue running.
  6	Security-related events	These messages identify occurrences that affect the security of the server (for example, "Privileged access attempted by user with revoked or unlisted certificate").

You can use log levels to filter log entries based on the severity of an event. By default, a level 3 (Failure) is set for all services.

---

Note

The log level is additive—that is, specifying a value of 3 causes levels 4, 5, and 6 to 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. It is also important to define your logging level, log rotation, log expiration, and server-backup policies appropriately so that all the log files are backed up and the host system doesn't get overloaded; otherwise, you may lose information.

---

Log File Locations

For quick access, all the log files—system, error, and audit—are maintained in your local file system. Make sure that your storage capacity is sufficient for all your log files. A log file has the following default location: <server_root>/cert-<instance_id>/logs

You can change the default location for logs by modifying it in the configuration.

Log File Naming Conventions

All log files created by Certificate Management System use one or the other of two naming conventions. There is one naming convention for active log files and one for rotated log files.

Active Log File Naming Convention

All active log files created by Certificate Management System use an identical naming convention. The name of an active log file is in the form <log_type>.log, where <log_type> specifies the log file type—whether it is system, error, or audit.

For example, an active error log file would be named error.log.

Rotated Log File Naming Convention

All rotated log files created by Certificate Management System use an identical naming convention. When Certificate Management System rotates an active log file, it renames the current log file and then creates a new log file with the original name. The rotated log file is saved with the original file type and an appended timestamp.

The name of a rotated log file is in the form <log_type>.timestamp, where the components of the filename indicate the following:

• <log_type> specifies the log file type—system, error, or audit—that has been rotated.

• timestamp is a large integer that indicates the date and time the corresponding active log file was rotated. The date and time have the forms YYYYMMDD (Year, Month, Day) and HHmmSS (Hour, Minute, Second), in that order.

For example, an error log file rotated on July 28, 1998 at 12:36:24 would be named error.19980728123624. Note that the timestamp is expressed in standard Unix time: the number of seconds since midnight January 1, 1970.

Buffered Versus Unbuffered Logging

Certificate Management System supports buffered logging for all three types of logs—system, error, and audit. You can choose to configure the server for either buffered or unbuffered logging (see Configuring CMS Logs).

If you configure Certificate Management System for buffered logging, the server creates buffers for the corresponding logs, and it holds the messages in these buffers for as long as possible. The server flushes out the messages to the log files—which are maintained in your local file system—only when either of the following conditions occurs:

• The buffer gets full—the buffer gets full when the buffer size is equal to or greater than the value specified by the bufferSize configuration parameter. The default value for this parameter is 512 KB.

• The flush interval for the buffer is reached—the flush interval is reached when the time interval since the last buffer flush is equal to or greater than the value specified by the flushInterval configuration parameter. The default value for this parameter is 5 seconds.

• When current logs are read from CMS window—the server retrieves the latest log when it is queried for current logs.

If you configure the server for unbuffered logging, the server flushes out messages as they are generated to the log files. Because the server performs an I/O operation (writing to the log file) each time a message is generated, configuring the server for unbuffered logging decreases performance.

Rotation of Log Files

Certificate Management System supports automatic rotation of log files, which simplifies administration and facilitates backups. You are not required to manually retire the current log file and create a new one to hold subsequent logged events. You can back up all but the current log file in a directory at any time, without stopping the server or manually notifying the server to start a new log file. The parameters that control log rotation are specified in the configuration. To change the log file rotation parameters, see Configuring CMS Logs.

You should periodically archive or back up the rotated log files. For details, see Archiving of Rotated Log Files.

Timing of Log File Rotation

Log files are rotated when either of the following conditions occur:

• The size limit for the corresponding file is reached—the size of the corresponding log file is equal to or greater than the value specified by the maxFileSize configuration parameter. The default value for this parameter is 100 KB.

• The age limit for the corresponding file is reached—the corresponding log file is equal to or older than the interval specified by the rolloverInterval configuration parameter. The default value for this parameter is 2592000 seconds (every hour).

Both these parameters can be specified from the CMS window; see Configuring CMS Logs.

Location of Rotated Log Files

Rotated log files are stored at the same location where the current or active log files are maintained. To find out the default location of an active log file, see Log File Locations.

Deletion of Log Files

Certificate Management System supports automatic deletion of rotated (or old) log files.

How to Conserve Disk Space

By default, Certificate Management System does not delete rotated log files automatically. Because the rotated log files are also saved in your local file system, these files eventually take up a considerable amount of disk space. You can avoid this problem by doing one of the following:

• Configure the server to automatically delete the rotated log files.

• Manually delete the log files from the local file system.

In either case, if you want to keep specific log files for future use, be sure to archive or back them up before they are deleted. For details, see Archiving of Rotated Log Files.

Timing of Log File Deletion

If you configure Certificate Management System to delete rotated log files automatically, the server deletes these files when the life of the corresponding log file is equal to or older than the interval specified by the expirationTime configuration parameter; the interval must be specified in seconds. By default, the rotated log files are not deleted. If you want the files to be deleted, you must change the default value as appropriate. For example, if you want the files to be deleted every 30 days, you would change the value to 2592000 (60x60x24x30).

Configuring CMS Logs

---

This section explains how to configure Certificate Management System to log messages so that you can monitor the server:

• Step 1. Before You Begin

• Step 2. Modify the Existing Listeners

• Step 3. Delete Unwanted Listeners

• Step 4. Create New Listeners

Step 1. Before You Begin

Before configuring a CMS instance:

• Read section Introduction to Logs.

• Read Chapter 8, "Log Plug-in Modules" of CMS Plug-Ins Guide.

Step 2. Modify the Existing Listeners

When you create a CMS instance, a set of log-event listeners (that you would most likely want to use) are automatically created using the log modules registered by default.

• Audit

• Error

• System

• NTAudit (only on a Windows NT system)

• NTSystem (only on a Windows NT system)

Note that Audit, Error, and System listeners are created using the file module and NTAudit and NTSystem listeners are created using the NTEventLog module.

Figure 23-1 shows the log-event listeners created for a CMS instance installed on a Windows NT system.

Figure 23-1    Default log-event listeners of a Certificate Manager

After installation, you must verify whether you want to use these listeners, check how these listeners are configured, and make the appropriate configuration changes.

You can modify a log-event listener by editing its configuration parameter values; you cannot edit the name of a listener. To change the name of a listener, you need to create a new listener exactly like the listener you want to rename, except with a new name, and delete the old listener.

As a part of editing a listener, you can change its status from enabled to disabled or vice versa by checking or unchecking the enabled parameter. Listeners that are in a disabled state do not record any events.

If you don't want to use a listener, delete it from the configuration as explained in Step 3. Delete Unwanted Listeners; alternatively, you may keep it in the disabled state. If you want to create a new listener, you can do so as explained Step 4. Create New Listeners.

To configure audit, error, and system logs for a CMS instance:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. In the navigation tree, select Logs.

   On the right pane, the Log Event Listener Management tab appears. It lists the currently configured listeners.

3. In the Log Event Listener list, select a listener that you want to modify.

   For the purposes of this instruction, assume that you selected the listener named Audit.

4. Click Edit/View.

   The Log Event Listener Editor window appears, showing how this listener is configured. An example is shown below.
   
   

5. Make the necessary changes and click OK.

   You are returned to the Log Event Listener Management tab.

6. Repeat steps 3 through 5 for the remaining rules.

7. Click Refresh.

Step 3. Delete Unwanted Listeners

You can delete any unwanted log-event listeners from the CMS configuration. If you think you might need a listener in the future, instead of deleting it from the configuration you should disable it by unchecking the enabled parameter. In this way, you can avoid re-creating the listener in the future.

To delete a listener from the CMS configuration:

1. In the Log Event Listener Management tab, select the listener you want to delete and click Delete.

2. When prompted, confirm the delete action.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. Don't restart the server yet; you can do so after you've made all the required changes.

Step 4. Create New Listeners

This generally not required. However, if you want to create a new listener, follow the procedure in this section.

Adding a log-event listener to the CMS configuration involves creating a new instance of an already registered log plug-in module, assigning a unique name for the instance, and entering appropriate values for the parameters that define the module you want to create an instance of.

When you add a listener, the CMS configuration gets updated with the relevant information. Keep the following points in mind:

• When naming a listener, be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type Audit_Log_Listener or AuditLogListener as the instance name, but not Audit Log Listener.

• The status of the listener, enabled or disabled, depends on whether you check or uncheck the enabled parameter; only an enabled listener records events.

Figure 23-2 shows the log modules registered with a Certificate Manager. If you have registered any custom policy modules (see Registering a Log Module), they too will be available for selection.

Figure 23-2    Default log modules registered with a Certificate Manager

To add a new listener to the CMS configuration:

1. In the Log Event Listener Management tab, click Add.

   The Select Log Event Listener Plugin Implementation window appears. It lists registered log modules.
   
   

2. Select a plug-in module.

   For the purposes of this instruction, assume that you selected the file module.

3. Click Next.

   The Log Event Listener Editor window appears. It lists the configuration information required for this listener.
   
   

4. Enter the appropriate information:

   Log Event Listener ID. Type a unique name that will help you identify the listener; be sure to use an alphanumeric string without spaces.

   type. Select audit to create a listener that records audit logs. For error and system logs, select system. For more information, see Logs Maintained by the Server.

   enabled. Select this box.

   level. From the drop-down list, select a log level. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. The default selection is Failure. For more information, see Log Levels (Message Categories).

   fileName. Type the full path, including the filename, to the file to write messages. (Make sure that the server has read/write permission to the file.)

   bufferSize. Type the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Buffered Versus Unbuffered Logging.

   flushInterval. Type the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds.

   maxFileSize. Type the file size in kilobytes (KB) for the error log. The default size is 100 KB. For more information, see Timing of Log File Rotation.

   rolloverInterval. From the drop-down list, select the frequency at which the server should rotate the active error log file. The available choices are Hourly, Daily, Weekly, Monthly, and Yearly. The default selection is Monthly. For more information, see Rotation of Log Files.

   expirationTime. Type, in seconds, the age limit for deleting the rotated log files. The default value is 0 seconds, which indicates that the rotated log files should not be deleted. For more information, see Deletion of Log Files.

5. Click OK.

   You are returned to the Log Event Listener Management tab.

6. Repeat steps 1 through 5 and create additional rules, if required.

Monitoring CMS Logs

---

When you have problems with Certificate Management System 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 the server's operation.

To facilitate this, the CMS window provides a simple mechanism for viewing the contents of both currently active and rotated audit, system, and error log files. The contents of the log file you choose to view are displayed in the form of a table. Each row is allocated to a specific log entry, with columns containing 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 also do the following tasks:

• Read log file contents partially (by specifying the number of entries to be displayed)

• Filter log entries for specific services (by specifying the source)

This section covers the following topics on monitoring Certificate Management System by viewing log contents:

• Monitoring System Logs

• Monitoring Error Logs

• Monitoring Audit Logs

• Using System Tools for Monitoring the Server (Windows NT Only)

Monitoring System Logs

Certificate Management System maintains extensive system logs. These logs record various events and system errors for system monitoring and debugging. A system log records details such as the following:

• Each HTTP access invoked on the server.

• Errors encountered, such as authentication failures, malformed universal resource indicators (URIs), invalid database password indications, and server start-up and shut-down messages.

• Messages related to the status of certificate issuance or revocation, authentication failures for issuing-agent connections, and any errors related to the formatting of requests.

You can view the contents of currently active as well as rotated system log files from the CMS window (see Figure 23-3).

If you have installed Certificate Management System on a Windows NT system, you can configure the server to log messages to Windows NT event log. For details, see Logging to Windows NT Event Log.

Figure 23-3    A sample active system log displayed in the CMS window

To view the contents of an active or rotated system log file:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Status tab.

3. In the navigation tree, under Logs, select System.

4. In the Display Options section, specify your viewing preferences:

   Entries. Type the maximum number of entries to be displayed. When this limit is reached, Certificate Management System returns any entries it has located that match the search request. If you enter zero (0), no messages are returned. If you leave the field blank, the server returns every matching entry (no limit) regardless of the number found.

   Source. Select the CMS component (or service) for which log messages are to be displayed. Depending on the components that write to this log file, the drop-down list shows one or more of the following: All, Registration Authority, Certificate Authority, Key Recovery Authority, HTTP, Internal Database, Authentication, Administration, LDAP, Request Queue, ACLs, User and Group, OCSP, and Others. If you choose All, messages logged by all components that log to this file are displayed. For more information, see Services That Are Logged.

   Level. Select a message category that represents the log level for filtering messages. For more information on log levels, see Log Levels (Message Categories).

   Filename. Select the log file you want to view. Choose Current to view the currently active system log file. For more information, see Log File Naming Conventions.

5. Click Refresh.

   The table displays the system log entries. The entries are in reverse chronological order, with the most current entry placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.

   For each entry you see the following details:

   Source. Indicates the CMS component or resource that logged the message.

   Level. Indicates the severity of the corresponding entry (explained Table 23-3).

   Date. Indicates the date on which the entry was logged.

   Time. Indicates the time at which the entry was logged.

   Details. Provides a brief description of the log.

6. To view an entry in its entirety, either double-click it or select the entry and click View.

Monitoring Error Logs

The error log file contains errors the server has encountered since the log file was created; it also contains informational messages about the server, such as when the server was started. Incorrect user authentication is also recorded in the error log. Use the error log to find broken URL paths or missing files.

You can view the contents of currently active as well as rotated error log files from the CMS window (see Figure 23-4).

Figure 23-4    A sample active error log displayed in the CMS window

To view the contents of an active or rotated error log file:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Status tab.

3. In the navigation tree, under Logs, click Error.

4. In the Display Options section, specify your viewing preferences:

   Entries. Type the maximum number of entries to be displayed. When this limit is reached, Certificate Management System returns any entries it has located that match the search request. If you enter zero (0), no messages are returned. If you leave the field blank, the server returns every matching entry (no limit) to the client regardless of the number found.

   Source. Select the CMS component (or services) for which log messages are to be displayed. Depending on the components that write to this log file, the drop-down list shows one or more of the following: All, Registration Authority, Certificate Authority, Key Recovery Authority, HTTP, Internal Database, Authentication, Administration, LDAP, Request Queue, ACLs, User and Group, OCSP, and Others. If you choose All, messages logged by all components that log to this file are displayed. For more information, see Services That Are Logged.

   Level. Select a message category that represents the level of logging to filter messages. For more information, see Log Levels (Message Categories).

   Filename. Select the log file you want to view. Choose Current to view the currently active error log file. For more information, see Log File Naming Conventions.

5. Click Refresh.

   The table displays the error log entries. The entries are in reverse chronological order, with the most current log placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.

   For each entry you see the following details:

   Source. Indicates CMS component or resource that logged the message.

   Level. Indicates the severity of the corresponding entry (explained in Table 23-3).

   Date. Indicates the date on which the entry was logged.

   Time. Indicates the time at which the entry was logged.

   Details. Provides a brief description of the log.

6. To view an entry in its entirety, either double-click it or select the entry and click View.

Monitoring Audit Logs

Certificate Management System maintains audit trails for all events—certificate requests, certificate renewal and revocation requests, CRL publication, and so on. These trails enable you to detect any unauthorized access or activity. The audit trails are logged and maintained in a file in your local file system.

If you have installed Certificate Management System on a Windows NT system, you can also configure the server to log audit messages to Windows NT event log. For details, see Logging to Windows NT Event Log.

---

Note	You should periodically examine and audit the CMS audit log for unusual activity. When examining the log, note in particular the log entries that fall under the Security-Related Events category (these are labeled Security).

---

You can view the contents of currently active as well as rotated audit log files from the CMS window (see Figure 23-5).

Figure 23-5    A sample active audit log displayed in the CMS window

To view the contents of an active or rotated audit log file:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Status tab.

3. In the navigation tree, under Logs, select Audit.

4. In the Display Options section, specify your viewing preferences:

   Entries. Type the maximum number of entries to be displayed. When this limit is reached, Certificate Management System returns any entries it has located that match the search request. If you enter zero (0), no messages are returned. If you leave the field blank, the server returns every matching entry (no limit) regardless of the number it finds.

   Source. Select the CMS component (or resource) for which log messages are to be displayed. Depending on the components that write to this log file, the drop-down list shows one or more of the following: All, Registration Authority, Certificate Authority, Key Recovery Authority, HTTP, Internal Database, Authentication, Administration, LDAP, Request Queue, ACLs, User and Group, OCSP, and Others. If you choose All, messages logged by all components that log to this file are displayed. For more information, see Services That Are Logged.

   Level. Select a message category that represents the level of logging to filter messages. For more information, see Log Levels (Message Categories).

   Filename. Select the log file you want to view. Choose Current to view the currently active audit log file. For more information, see Log File Naming Conventions.

5. Click Refresh.

   The table displays the audit log entries. The entries are in reverse chronological order, with the most current log placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.

   For each entry you see the following details:

   Source. Indicates the CMS component or resource that wrote to the log file.

   Level. Indicates the severity of the corresponding entry (explained in Table 23-3).

   Date. Indicates the date on which this entry was logged.

   Time. Indicates the time at which this entry was logged.

   Details. Provides a brief description of the log.

6. To view an entry in its entirety, either double-click it or select the entry and then click View.

Using System Tools for Monitoring the Server (Windows NT Only)

If you have installed Certificate Management System on a Windows NT system, you can monitor the server with the system tools provided by Windows NT. This section explains how you can use the system tools.

• Logging to Windows NT Event Log

• Using Event Viewer

• Avoiding Event Log From Getting Filled

Logging to Windows NT Event Log

In addition to logging messages to the log files maintained in your local file system, Certificate Management System can also log audit messages and system errors to the Windows NT Event log. The CMS window allows you to turn this feature on or off and to specify the levels for logging. To configure the server to log messages to the Event log, see Configuring CMS Logs.

Note that by default Certificate Management System is configured to write both audit and system logs to the Windows NT Event log.

Using Event Viewer

Once you configure Certificate Management System to write audit and system logs to the Event log of a Windows NT system, you can use the system's tool called Event Viewer to monitor events related to your server. For more information about the Event Viewer, check your system documentation.

To monitor Certificate Management System by using Event Viewer:

1. In the Administrative Tools program group, double-click the Event Viewer icon.

2. From the Log menu, select Application.

   The Application log appears in Event Viewer. In this log, the source of any messages from iPlanet Certificate Management Server is the server's instance ID (if you didn't change the default value assigned to the NTEventSourceName parameter).

3. From the View menu, choose Find to search for one of the iPlanet labels in the log; use Refresh to see updated log entries.

4. Double-click a log entry to see additional information.

   The mapping between the CMS log levels and the Windows NT event type is shown in Table 23-4.

   
   

   Table 23-4    Mapping between Windows NT log event type and CMS logs  
   
   

   Windows NT log event type	CMS log level
   Information	Debugging (0)
   Information	Informational (1)
   Warning	Warning (2)
   Error	Failure (3)
   Error	Misconfiguration (4)
   Error	Catastrophic failure (5)
   Error	Security-related events (6)

Avoiding Event Log From Getting Filled

When running Certificate Management System on a Windows NT system, if you don't configure the NT Event Log properly, the event log will get full. When this happens, you'll see an error message (see Figure 23-6) stating that the application log file is full.

Figure 23-6    Error message indicating event log is full

If you see this dialog box, you must clean up the application log immediately. Here's what you should do:

1. From the Start menu on your desktop, select Programs, Administrative Tools (Common), and Event Viewer, in that order.

   This opens the Event Viewer window for the system.

2. From the Log menu, select Application.

   A checkmark to the left indicates it is selected.

3. From the Log menu, select Log Settings.

   This opens the Event Log Settings window.
   
   

4. Enter the appropriate values:

   Change Settings for. Make sure that the Application log is selected in this box.

   Maximum Log Size. Select a reasonable size so that the event log doesn't get full in a short period of time.

   Event Log Wrapping. Select the "Overwrite Events as Needed" option.

5. Click OK.

6. Close the Event Viewer window.

Archiving of Rotated Log Files

---

Log files, especially the audit log file, contain critical information. So it is good practice to periodically archive rotated log files to some archive media. Consider doing this whether you are manually deleting rotated log files or have configured the server to delete files automatically. You can archive log files by copying the entire log directory to your archive media.

Certificate Management System does not provide any tool or utility for archiving log files. Use the tools or utilities that your operating system provides for archiving.

Certificate Management System does, however, provide a command-line utility, called signtool, that allows you to sign log files before archiving them. This gives you a means of tamper detection. For details, see Signing Log Files.

Signing Log Files

Certificate Management System allows you to digitally sign log files before you archive them or distribute them for audit purposes. This feature enables you to check whether the log files have been tampered with since being signed.

For signing log files, you use a command-line utility called Signing Tool; for details about this utility, check Chapter 13, "Signing Tool" of CMS Command-Line Tools Guide. The utility uses information in the certificate (cert7.db), key (key3.db), and security module (secmod.db) databases of Certificate Management System.

Before you begin signing the log files, follow these guidelines:

• Determine the key pair you want to use for signing the log directory. Typically, you should use the Certificate Manager's (the CA's) signing key pair. Also find out the nickname of the certificate that corresponds to this key pair.

• If you have deployed many CAs, locate the CMS instance in which the CA you want to use is installed.

• Find out whether the key pair is in an internal or external token. If it is in an external token, make sure the token is currently installed. You will also need to know the password for the token.

• Determine which log files need to be signed. Put all the files that need to be signed in one or more directories. (The utility can sign a directory containing files; it cannot sign individual files.) Make sure these directories are in the host machine in which the CA is installed.

• Determine names for the output files; the output you receive will be a JAR file (which is a signed zip file). You may want to give names that will help you identify these JAR files easily in the future.

When you are ready with all this information, follow the procedure below to sign the log directories:

1. Go to the CMS instance in which the CA whose key pair you want to use for signing is installed.

2. Copy the security module database (secmod.db file) from the Administration Server configuration directory to the CMS configuration directory.

   The security module database is in this directory:

   <server_root>/admin-serv/config

   Copy it to this directory:

   <server_root>/cert-<instance_id>/config

3. Open a terminal window.

4. At the command prompt, run the following command with the appropriate information:

   signtool -d <secdb_dir> -k <cert_nickname> -Z <output> <input>

   <secdb_dir> specifies the path to the directory that contains the certificate, key, and security module databases for the CA. This must be the same path you used to copy the security module database in step 2.

   <cert_nickname> specifies the nickname of the certificate you want the utility to use for signing.

   <output> specifies the name of the JAR file (a signed zip file).

   <input> specifies the path to the directory that contains the log files.

   For example, in a Windows NT system, your command might look like this:

   signtool -d c:\iplanet\servers\cert-testCA\config -k
   testCAsigningcertificate -Z log_err_02_99.jar
   c:\archive\logs

   where c:\iplanet\servers\cert-testCA\config is the path to the certificate, key, and security module databases (secdb_dir).

   testCAsigningcertificate is the certificate nickname (cert_nickname).

   log_err_02_99.jar is the name of the JAR file (output).

   (input) is c:\archive\logs is the directory to be signed.

Managing Log Modules

---

This section explains how to use the CMS window to perform the following operations:

• Registering a Log Module

• Deleting a Log Module

For information on adding or changing policy-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.

Registering a Log Module

You can register new log plug-in modules using the CMS window. Registering a new module involves specifying the name of the module and the full name of the Java class that implements the log interface.

Before registering a plug-in module, be sure to put the Java class for the module in the classes directory (the implementation must be on the class path).

To register a log plug-in module with a CMS instance:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select Logs, and then in the right pane, select the Log Event Listener Plugin Registration tab.
   
   

4. Click Register.

   The Register Log Event Listener Plugin Implementation window appears.

5. Specify information as appropriate:

   Plugin name. Type a name for the plug-in module.

   Class name. Type the full name of the class for this module—that is, the path to the implementing Java class. If this class is part of a package, be sure to include the package name. For example, if you are registering a class named customLog and if this class is in a package named com.myCompany, type com.myCompany.customLog.

6. Click OK.

   You are returned to the Log Event Listener Plugin Registration tab.

7. To view the updated configuration, click Refresh.

Deleting a Log Module

You can delete unwanted log plug-in modules using the CMS window. Before deleting a module, be sure to delete all the listeners that are based on this module; see Step 3. Delete Unwanted Listeners.

To delete a module:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select Logs, and then in the right pane, select the Log Event Listener Plugin Registration tab.

4. In the Plugin Name list, select the module you want to delete and click Delete.

5. When prompted, confirm the delete action.