Netscape logo Administrator's Guide
Netscape Certificate Management System
Previous      Contents      Index      DocHome      Next     

Chapter 8   Administrative Basics


This chapter discusses the Netscape Certificate Management System (CMS) user interface, the configuration file, and other basic administrative tasks like starting and stopping the server, managing logs, changing port assignments, and changing the internal database.

This chapter contains the following sections:

The Administrative Interface

CMS provides a GUI-based administration tool called the CMS console that is accessible from Netscape Console. Netscape Console is a GUI-based front-end for Netscape Administration Server and allows you to manager servers as well as users.

This section provides an overview of Netscape Administration Server and the CMS console.

Netscape Administration Server

Netscape Administration Server is a web-based (HTTP) server installed along with CMS that enables you to configure CMS through Netscape Console. You access Administration Server by entering its URL in the Netscape Console login screen and providing the user ID and password of the administrative user.

Administration Server must be running before you can access Netscape Console.

For complete details about Netscape Administration Server, see Managing Servers with Netscape Console.

Starting Administration Server

The CMS installation program automatically starts Administration Server. If you stopped Administration Server after installation, you must start it before you can administer CMS from the CMS console.

To start Administration Server:

  1. Go to the following directory:
    2. <server_root>
     
    where:

    <server_root>

    Specifies the directory in which you installed CMS.


     
  2. Type the following command:
    3. ./start-admin
     

Netscape Console

Netscape Console is a stand-alone Java application that provides a GUI-based front end to all network resources registered in an organization's configuration directory. This unified administration interface simplifies network administration by supplying access points to all Netscape server instances installed across a network. Similarly, it simplifies basic user and group management by providing a unified administration interface to the user directory.

You can accomplish various CMS-specific tasks from the Console tab:

For complete details about Netscape Console, see Managing Servers with Netscape Console.

Logging Into Netscape Console

You can launch and use Netscape Console only when the configuration directory and Administration Server are running.

To login to Netscape Console:

  1. Go to the following directory:
    2. <server_root>
     
    where:

    <server_root>

    Specifies the directory in which you installed CMS.


     
  2. Type the following command:
    3. ./startconsole
     
    The login dialog opens.
     
  3. Log into Netscape Console by filling in the following field:
    4. User ID. Type the administrator user ID. You should login using the administrator user ID, using the cn=Directory Manager user ID allows you full privileges with Directory Server, but does not allow you to create CMS server instances.
     
    Password. Type the password for this user ID.
     
    Administration URL. Specify the URL for the Administration Server you want to log into. This URL has the following format:
     
    http://<machine_name>.<your_domain>.<domain>:<port_number>
     
    For example, if your domain name is example.com and you installed Administration Server on a host machine called myHost and specified port number 12345, the URL is:
    http://myHost.example.com:12345
     
  4. Click OK.
    5. Netscape Console opens.
     




The CMS Console

The CMS console is a GUI-based administration interface that allows you to perform day-to-day operational and managerial duties for CMS and configure the server. You launch the CMS console from within Netscape Console.

You can use the CMS console to access the server locally or remotely. The console has the following tabs:

Logging Into the CMS Console

To log into the CMS console:

  1. Log into Netscape Console, see "Logging Into Netscape Console".
  2. Double-click the CMS instance you want to open from the Netscape Console navigation tab, or select the instance and click Open.
    3. The CMS Authenticate User dialog opens.
     
    If this instance has not yet been setup, the Installation Wizard launches allowing you to set up this instance.
     
    If the server is not running, you are asked to start the server first. For information on starting the server, see Starting, Stopping, and Restarting CMS Instances.
     
  3. You must login into CMS as an administrator user of CMS. Provide the administrator user ID and password in the following fields:
    4. User ID. Provide a user ID that has CMS administrator privileges.
     
    Password. Type the password for this user ID.
     
    Note: If SSL client authentication is set up for this server, you will be presented with a list of your certificates to choose from in order to login. You will not be presented with the userID/Password entry dialog.
     
  4. The CMS console opens.




Viewing Information About a CMS instance

You can view some of the basic information about a CMS instance.

To view information pertaining to a CMS instance:

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. In the Console tab, select the CMS instance you want to view.
    3. The right pane shows information about the selected CMS instance.
     
    The information displayed includes the following:
     
    Server Name. A descriptive name of the CMS instance.
     
    Description. Additional information that helps you identify the CMS instance. You can change this description.
     
    Installation Date. The date the server was installed.
     
    Server Root. The directory in which all servers are installed.
     
    Product Name. The complete product name.
     
    Vendor. The name of the vendor.
     
    Version. The version number.
     
    Build Number. The number that identifies the build that was used for this installation.
     
    Security Level. The server's security level—whether the server is meant for use in the United States and Canada (domestic) or any other part of the world (export). See Configuring the Server's Security Preferences.
     
    Server Status. The server's status—whether it is started, stopped, or unknown; normally, unknown indicates that the server hasn't been configured properly.
     
  3. To change the name of the instance, or its description:
    4. Select the instance and click Edit.
     
    Details about the selected CMS instance appear in the right pane. Specify the appropriate information:
     
    Server Name. Type a name for the server.
     
    Description. Type any additional description for the server. For example, you may want to type information that will help you identify this instance of CMS.
     

Setting up Certificate Authentication for the CMS Console

Certificate Authentication of Netscape Console, and the CMS window can now be enabled so that administrators must authenticate using a client certificate that is good for SSL authentication before logging into Netscape Console, or the CMS window. You first need to store the certificates of the administrators and then enable this feature.

Storing an Administrator's Client Certificates

You must store the certificates for any of administrator using this system. The certificate should be either from the CA itself, or from whichever CA signed the certificate for the subsystem.

Make sure the client certificate is good for SSL client authentication, otherwise, the server will not accept the client certificate and will post the following error message in the error log located in the directory <server_root>/cert-<instanceID>/logs/errors:

failure (14290): Error receiving connection (SEC_ERROR_INADEQUATE_CERT_TYPE - Certificate type not approved for application.)

Enabling SSL Client Authentication

To enable SSL client authentication in Netscape Console:

  1. Since you need to use certutil to initialize cert8.db and key3.db and to create certificate request, make sure to set the LD_LIBRARY_PATH correctly. To do this, issue the following command:
    2. setenv LD_LIBRARY_PATH <server_root>/lib:$LD_LIBRARY_PATH
     
  2. Use certutil in /bin/cert/tools to initialize the cert8.db and key3.db files in <home_directory>/.mcc. To do this:
    1. Go to the following directory:
      2. <server_root>/bin/cert/tools
       
    2. Issue the command:
      3. ./certutil -N -d <home_directory>/.mcc
       
  3. Request the client certificate. Go to the end-entity interface for the CA that will issue the certificate and click on the Enrollment tab.
  4. Select the "Manual User Dual-Use Certificate Enrollment" link.
  5. Fill in all necessary information required for the form and click Submit.
  6. Once you get the certificate, make sure to import it to the browser.
  7. Export the certificate as p12 file.
  8. Import the client certificate in p12 format to the cert8.db.
    9. ./pk12util -i <pk12file> -d "<home directory>/.mcc"
     
  9. Log in to the CMS console (see Logging Into the CMS Console).
  10. Go to the Configuration tab, and then select the Users tab in the left hand panel.
  11. Click Certificates to add the client certificate.
    12. The Manager User Certificates window appears.
     
  12. Paste the certificate into the window.
  13. Click Import.
  14. Repeat from step 6 for each administrator until the certificates for all administrators have been imported.
  15. Click Done.
  16. Stop the CMS server.
  17. Go to the directory <serverRoot>/cert-<instanceID>/config
  18. Open the file CMS.cfg.
  19. Change the value of the authType parameter from pwd to sslclientauth:
    20. authType=sslclientauth
     
  20. Save the file.
  21. Open the file server.xml.
  22. Change the clientauth="off" attribute to clientauth="on" in the SSLPARAMS section of the LS id="admin":
    23. <LS id="admin" ip="0.0.0.0" port="8206" security="on" acceptorthreads="1" blocking="no">
     
    <CONNECTIONGROUP id="admin_default" matchingip="default" servername="buster.mcom.com" defaultvs="admin-vs">
     
    <SSLPARAMS servercertnickname="Server-Cert cert-buster" ssl2="off" ssl2ciphers="-rc4,-rc4export,-rc2,-rc2export,-des,-desede3" ssl3="on" ssl3tlsciphers="-fortezza,-fortezza_rc4_128_sha,+rsa_rc4_128_md5,-rsa_rc4_40_md5,+rsa_3des_sha,+rsa_des_sha,-rsa_rc2_40_md5,-fortezza_null,-fips_des_sha,+fips_3des_sha,-rsa_null_md5,-rsa_des_56_sha,-rsa_rc4_56_sha" tls="on" tlsrollback="off" clientauth="off"/>
     
  23. Start CMS.
  24. Start Netscape Console. You will be prompted for your certificate.

System Passwords

CMS has a password-quality checker for internal passwords that you can configure to your needs. It stores token passwords in a plain text file, and stores all other passwords in an encrypted password cache file.

Password-Quality Checker

CMS comes with a plug-in, called password-quality checker, to monitor the quality of passwords set within the CMS system. All passwords used in CMS are checked by the password-quality checker, which by default checks that the length of a password is at least 8 characters long; there are no checks regarding which characters are valid or invalid. If you use a password that doesn't meet the quality rules, you will get an error message.

Note that CMS enforces password quality on only those passwords that it creates and manages. Passwords you enter for LDAP directory access are not subjected to quality checks. The reason for this is, the password quality is handled by the system that creates and manages the password. In an LDAP directory access, the remote directory that you authenticate to enforces the quality of the password you used because it is created and managed by the directory.

To enable you to customize the quality of passwords, the plug-in for the password-quality checker is included as a sample in the CMS SDK.

Passwords Stored by the Server

CMS stores passwords in two separate files. These passwords are used to bind to servers, or to unlock tokens when you start up the server.

Token Password Storage

The passwords for any tokens holding the private keys for the subsystem installed in this instance of CMS are stored in the file password.conf located in the <server_root>/cert-<instance_id>/config directory. This file has read/write permission for the installer only.

This file contains the token passwords needed to open the private keys of the subsystem as follows:

Deleting the password.conf File

You can choose to delete the password.conf file during CMS installation, the default choice is to keep the file. You might choose to delete this file for added security of your token passwords because this file stores the passwords in a plain text file.

If you do delete the password.conf file, you must start the server instance using the command line. You will be prompted for the token passwords after entering the start-cert command. You cannot start the CMS instance from the CMS console. CMS console does not provide the ability to enter this password when the password.conf file is absent.

Password Cache

Passwords for the internal database and other database related passwords for optional features are stored in the file pwcache.db located in the <server_root>/cert-<instance_id>/config directory. The password cache is triple-DES encrypted with a symmetric key, which is generated and stored in the cryptographic module. This file is opened using the single sign-on password, and the passwords stored are used to bind to the various services.

In order to make changes to the password cache, CMS ships with a command-line named PasswordCache located in the <server_root>/bin/cert/tools directory. For complete details about this utility, see the Netscape Certificate Management System Command-Line Tools Guide.

The list of passwords stored in this file includes the following:

Starting, Stopping, and Restarting CMS Instances

Each instance of CMS is started, stopped, and restarted separately. This section describes how to start, stop, and restart CMS instances and how to check its current status.

Starting a Server Instance

You can start the server from either Netscape Console or from the command line.

Starting From Netscape Console

To start a CMS instance from Netscape Console:

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. Select the CMS instance you want to open from the Netscape Console navigation tab and then right-click your mouse selecting the Start Server option from the pop-up menu.

Alternatively

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. Double-click the CMS instance you want to open from the Netscape Console navigation tab, or select the instance and click Open.
  3. Go to the Tasks Tab and select Start Server.

    4. Note  

    If you chose to delete the password.conf file during installation, you must start the server instance on the command line; you cannot start the server instance from the CMS console.

    For more information, see "Passwords Stored by the Server".



Starting From the Command Line

To start a CMS instance from the command line:

  1. Log in either as the root user ID or with the server's user ID.
  2. Go to the following directory:
    3. <server_root>/cert-<instance_id>
     
  3. Type the following command:
    4. ./start-cert
     

    Note  

    If CMS is already running, the start-up command fails. Stop the server first using the stop-cert command, then use the start-cert command.



Stopping a Server Instance

You can stop the server from either Netscape Console or from the command line.

With this version of CMS, CMS is enabled for a clean shutdown. During the shutdown process, the subsystem will process any already posted requests to any of its interfaces to completion, but will accept no new requests. There is a setting in the CMS.cfg file that allows you to set the absolute time out, the amount of time before the between issuing the shutdown command and actual shutdown. If this time is reached before all processes are complete, the server will shutdown without completing the processes. The default time out setting is 1 minute.

Stopping From Netscape Console

To stop a CMS instance from Netscape Console:

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. Select the CMS instance you want to stop from the Netscape Console navigation tab and then right-click your mouse selecting the Stop Server option from the pop-up menu.

Alternatively

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. Double-click the CMS instance you want to open from the Netscape Console navigation tab, or select the instance and click Open.
  3. Go to the Tasks Tab and select Stop Server.

Stopping From the Command Line

To stop a CMS instance from the command line:

  1. Log in either as root or with the server's user account.
  2. Go to the following directory:
    3. <server_root>/cert-<instance_id>
     
  3. Type the following command:
    4. ./stop-cert
     

Restarting a Server Instance

You can restart the server from either Netscape Console or from the command line.

Restarting From the CMS Console

To restart a CMS instance from the CMS console:

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. Double-click the CMS instance you want to open from the Netscape Console navigation tab, or select the instance and click Open.
  3. Go to the Tasks Tab and select Restart Server.

Restarting From the Command Line

To restart a CMS instance from the command line:

  1. Log in either as root or with the server's user account.
  2. Go to the following directory:
    3. <server_root>/cert-<instance_id>
     
  3. Type the following command:
    4. ./restart-cert
     

Subsystem Configuration Overview

Once you install CMS on a host, you are ready to configure any subsystems that will run on that host. You can configure multiple subsystems on a host, or multiple instances of a single subsystem. As part of your deployment planning, you should decide which subsystems will be needed and on which hosts those subsystems will be deployed.

You can configure subsystems in any order, but you may want to plan the order to provide the smoothest setup of your deployment. For example, if you are going to be setting up a hierarchy of Certificate Managers, you should install the root CA first. You might also want to install a Certificate Manager that will develop a trusted relationship with other subsystems first.

Configuring Multiple CMS Instances

When CMS is installed on a host, a single instance of CMS is also created and ready to be configured. You can created more instances of the server on the same machine and then set them up. For instance, you might want to add a Data Recovery Manager on the same host as a CA.

To create another instance of CMS:

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. In the navigation tree, select the server group in which you want to create a CMS instance.
  3. From the Object menu, choose Create Instance Of, then choose CMS from the pop-up list.
    4. Alternatively, you can select the server group and then right-click your mouse choosing Create Instance Of->Certificate Management System.
     
    The Create Server Instance dialog opens.
     
  4. Type a unique name or identifier for the new instance.
    5. You can use 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 Pilot_root-CA as the instance name, but not Pilot root CA.
     
  5. Click OK.
    6. The instance you created appears in the navigation tree.
     
  6. To configure the instance, start the installation wizard by double-clicking the new instance in the navigation tree. See the section in this chapter on configuring the subsystem you want to setup in this instance for complete details.

Removing an Instance From a System

You can remove a CMS instance from your host. Removing a CMS instance is not the same as uninstalling CMS. For instructions on uninstalling CMS, see Uninstalling CMS.

To remove a CMS instance:

  1. Log in to Netscape Console (see Logging Into Netscape Console).
  2. Stop the CMS instance.
  3. Select the CMS instance you want to remove and choose Remove Server from the Object menu.
    4. Alternatively, you can select the CMS instance you want to remove and then right-click your mouse choosing Remove Server from the pop-up menu.
     
  4. When prompted, confirm that you want to remove the instance.
    5. The selected CMS instance is removed. The corresponding internal database is not removed. If you want to remove it, select the internal database, and repeat steps 2 through 4.
     
    The Directory Server (configuration directory) and Administration Server binaries are also not removed; you need these to administer the remaining servers installed in the same server group.
     

Mail Server

The notifications and jobs features use the mail server set up in the CMS instance to send its notification messages. You set up a mail server using the following procedure:

  1. In the CMS window, select the Configuration tab, and then in the right pane, select the SMTP tab.
  2. Identify the mail server by providing the following details:
    3. Server name. Type the fully qualified DNS host name of the machine on which your mail server is installed. The format for the host name is as follows:
     
    <machine_name>.<your_domain>.<domain>
     
    By default, the host name of the mail server is shown as localhost instead of the actual host name (for example, mail.example.com).
     
    Port number. Type the port number on which the mail server is listening for requests.
     
  3. Click Save.

Configuration Files

The runtime properties of CMS are governed by a set of configuration parameters. These parameters are stored in a file that is read by the server during startup.

When you install CMS, the installer creates an ASCII file, named CMS.cfg, and populates it with the appropriate configuration parameters. You can control the way CMS functions by making the appropriate changes in the CMS console, which is the recommended method for making configuration changes. The changes you make in the CMS console are reflected in the configuration file. You can also make changes directly to the configuration file, but unless specifically instructed to do so in this documentation, this is not recommended.

Locating the Configuration File

Each instance of CMS has its own configuration file, CMS.cfg. The file for the subsystem is different depending on your installation choices, and on which subsystem is installed in that instance.

The CMS.cfg file is located in the following directory:

<server_root>/cert-<instance_id>/config

where:

<server_root>

Specifies the directory in which CMS is installed

<instance_id>

Specifies the name of the CMS instance

Editing the Configuration File

Caution  

Do not edit the configuration file directly if you are not familiar with the configuration parameters or if you are not sure that the changes you intend to make are acceptable by the server. CMS will fail to start up if you make incorrect modifications to the configuration file. Incorrect configuration can also result in data loss.



To modify the configuration file:

  1. Stop the CMS instance whose configuration file you want to edit (see Starting, Stopping, and Restarting CMS Instances).
    2. The configuration file is stored in the cache when you start CMS. Any changes you make to CMS through the CMS console are changed in the cached version of the file. When you stop or restart the server, the configuration file stored in the cache is written to disk.
     
    You must stop the server before editing the configuration file because your changes will be overwritten by the cached version when the server is stopped or restarted.
     
  2. Go to the following directory:
    3. <server_root>/cert-<instance_id>/config
     
  3. Open the file CMS.cfg in a text editor.
  4. Edit the parameters in the file and save your changes.
  5. Start CMS (see Starting, Stopping, and Restarting CMS Instances).

Guidelines for Editing the Configuration File

The following are guidelines for editing the configuration file:

Duplicating Configuration From One Instance to Another

If you have deployed a large number of CMS instances that are identical—for example, multiple Registration Managers—and you want all these instances to have the same configuration, you can accomplish this by configuring one of the instances and then replacing the configuration files of the other instances with the one that contains the required configuration.

Note  

Be careful when replacing configuration of one instance with another. The configuration file for an instance contains instance-specific parameters. If you replace these parameters, the instance will fail to start or function properly.



Logs

This section explains how to use the CMS console to configure logs maintained by CMS, and how to monitor the server's activities by viewing log contents.

This section contains the following sub-sections:

About Logs

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 the subsystems the server manages. While CMS is running, it keeps a log of information and error messages on all the components it manages.

Log plug-in modules are listeners, which are implemented as Java classes and are registered in the CMS policy framework.

Each instance of Netscape Certificate Management System (CMS) maintains its own log files.

All the log files and rotated log files, except for audit logs (signed or not), are located in the following directory:

<server_root>/cert-<instance_id>/logs

Audit logs, signed or not, are located in the following directory:

<server_root>/cert-<instance_id>/logs/signedAudit

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

Error and Access Logs

The error and access logs are created by Netscape Enterprise Server, which is installed with CMS providing HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface. These logs are not available or configurable from within CMS; they are only configurable from within Enterprise Server. See the Netscape Enterprise Server documentation for information about configuring these logs.

Self-Tests Log

The self-tests log records information obtained during the self-tests run when the server starts up, or when the self-tests are manually run (on demand). The tests can be viewed by opening this log. This log is not configurable through the CMS Console, you must configure it by changing settings in the CMS.cfg file. The information about logs in this section does not pertain to this log. See "Self Tests" for more information about self-tests.

Installation and Setup Logs

The following logs are created when the CMS instance is installed, the information about logs in this section does not pertain to these logs:

config_cgi.log. Created by config_cgi cgi that forwards configuration daemon client (Java UI) requests to the configuration daemon.

daemon.err. Created by the start_daemon cgi, captures the standard error of the start_daemon cgi

daemon.out. Created by the start_daemon cgi, captures the standard output of the start_daemon cgi

start_daemon.log. Created by the start_daemon cgi that starts the configuration daemon, logs errors of the daemon startup

service.log. created by ntservice.exe that registers CMS as a NT service (Windows specific file).

wizard.log. Created by the Installation wizard that installs and configures the subsystems. Logs errors during this installation and configuration.

System Log

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.

Transactions Log

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.

Signed Audit Log

This log contains audit records for events that have been set up as recordable events. If the logSigning attribute is set to true, the audit log is signed with a log signing certificate belonging to the server. This certificate can be used by auditors to verify that the log has not been tampered with. See "Signed Audit Log".

Services That Are Logged

All major components and protocols (or services) of CMS log messages to log files. Table 8-1 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 Logs.


Table 8-1    Services Logged  


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 console and CMS.

 

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. (Note, HTTP events are actually logged to the errors log belonging to the Netscape Enterprise Server that is incorporated into CMS to provide HTTP services.)

 

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 8-2. Each category represents messages that are of the same or a similar nature or that belong to a specific functional area.

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.

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.

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

Buffered Versus Unbuffered Logging

CMS supports buffered logging for all types of logs. You can choose to configure the server for either buffered or unbuffered logging.

If you configure 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 only when either of the following conditions occurs:

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.

Log File Rotation

Log files are rotated when either of the following occur:

When a log file is rotated, the old file is named using the name of the file with an appended time stamp. The appended time stamp is an 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.

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. You can archive log files by copying the entire log directory to your archive media.

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

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

Note that signing log files is an alternative to the signed audit logs feature. Signed audit logs allows you to create audit logs that are automatically signed, whereas this process describes how to manually sign archived logs. See "Signed Audit Log" for details about signed audit logs.

By default, rotated log files are not deleted.

Configuring Logs in the CMS Console

This procedure describes how to configure system, transaction, and audit logs.

To configure logs for a CMS instance:

  1. Log in to the CMS console (see Logging Into the CMS Console).
  2. In the navigation tree, select Logs.
    3. On the right pane, the Log Event Listener Management tab appears. It lists the currently configured listeners.
     
  3. Either create a new log instance, delete an existing instance, or modify an existing instance:
    4. To create a new log instance:
     
    1. Click Add in the Log Event Listener Management tab.
      2. The Select Log Event Listener Plug-in Implementation window appears. It lists registered log modules.
       
    2. Select a plug-in module.
    3. Click Next.
      4. The Log Event Listener Editor window opens.
       
    4. Continue to step 4.
    To delete a log instance:
     
    1. Select a listener that you want to delete in the Log Event Listener list.
    2. Click Delete
    3. Skip to step 5.
    To modify an existing log instance:
     
    1. Select a listener that you want to modify in the Log Event Listener list.
    2. Click Edit/View.
      3. The Log Event Listener Editor window opens.
       
    3. Continue to step 4.
  4. Make changes to the following fields in the Log Event Listener Editor window:
    5. Log Event Listener ID. Type a unique name that will help you identify the listener; be sure to note the following:
     
    type. Select transaction to create a listener that records audit logs. For error and system logs, select system.
     
    enabled. Select to enable; deselect to disable. Only enabled logs actually record events.
     
    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. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
     
    flushInterval. Type the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
     
    maxFileSize. Type the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see 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 Log File Rotation.
     
    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. If you provide a value, the rotated log will be deleted from your system after that time has elapsed. This is no longer supported. Logs will not be deleted, you cannot set a time for the automatic deletion of logs.
     
    The signed audit log has these additional settings:
     
    logSigning. Set to true to enable signed logging; set to false to disable signed logging. When you enable this parameter, you must also provide a value for the signedAuditCertNickname parameter. When this feature is enabled, this log can only be viewed by an auditor. See "Signed Audit Log" for more information about signed audit logs.
     
    signedAuditCertNickname. The nickname of the certificate used to sign audit logs. The private key for this certificate must be accessible to the subsystem in order for it to sign the log.
     
    events. Specifies which events will be logged to the audit log. Lists each event separated by a comma with no spaces. You can remove events from the list. See Table 8-3 for a complete list of auditable logging events.
     
  5. Click OK.
    6. You are returned to the Log Event Listener Management tab.
     
  6. Click Refresh.

Configuring Logs in the CMS.cfg File

To modify the configuration settings for logs:

  1. Stop the CMS instance.
  2. Open the CMS.cfg file located in the directory <server_root>/cert-<instance>/config
  3. To create a new log, you copy all of the entries for either the system or transactions log. These are the parameters that begin with log.instance.Transactions or log.instance.System. Paste all entries at the bottom of the logging section and change the name of this instance by changing the word "Transactions" or "System" in each parameter to the new name.
  4. To configure a log instance, modify the parameters associated with that log. These parameters begin with log.instance and include the following parameters:
    5. bufferSize. Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Buffered Versus Unbuffered Logging. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
     
    enable. Specify true to enable; false to disable. Only enabled logs actually record events.
     
    expirationTime. Specify, 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. If you provide a value, the rotated log will be deleted from your system after that time has elapsed. This is no longer supported. Logs will not be deleted, you cannot set a time for the automatic deletion of logs.
     
    fileName. Specify the full path, including the filename, to the file to write messages. (Make sure that the server has read/write permission to the file.)
     
    flushInterval. Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
     
    level. Specify a log level. The choices are 0 for Debug, 1 for Information, 2 for Warning, 3 for Failure, 4 for Misconfiguration, 5 for Catastrophe, and 6 for Security. The default selection is 1. For more information, see Log Levels (Message Categories).
     
    maxFileSize. Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see Log File Rotation.
     
    register. If this variable is set to false (the default value), the self tests messages will only be logged to the log file specified by selftests.container.logger.fileName. If this variable is set to true, then the self tests messages will be written to BOTH the log file specified by selftests.container.logger.fileName as well as to the log file specified by log.instance.Transactions.fileName.
     
    rolloverInterval. Specify 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 Log File Rotation.
     
    type. Set to transaction or system.
     
  5. Save the file.
  6. Start the CMS instance.

Monitoring Logs

When you have problems with CMS 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. You can view certain log files in the CMS console. You can also view log files by opening them in the file system. See "About Logs" for information on the location of logs and the log files available.

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

  1. Log in to the CMS console (see Logging Into the CMS Console).
  2. Select the Status tab.
  3. In the navigation tree, under Logs, select the log you want to view.
  4. In the Display Options section, specify your viewing preferences:
    5. Entries. Type the maximum number of entries to be displayed. When this limit is reached, CMS 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 from the drop-down list.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.
     
  5. Click Refresh.
    6. 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, see Table 8-2 on page 277 for more information.
     
    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.

Signing Log Files

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

Note that this is an alternative to the signed audit logs feature. Signed audit logs allows you to create audit logs that are automatically signed, whereas this process describes how to manually sign archived logs. See "Signed Audit Log" for details about signed audit logs.

For signing log files, you use a command-line utility called Netscape Signing Tool (signtool). For details about this utility, check this site: http://www.mozilla.org/projects/security/pki/nss/tools/

The utility uses information in the certificate, key, and security module databases of CMS.

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. Type the following command with the appropriate information:
    3. signtool -d <secdb_dir> -k <cert_nickname> -Z <output> <input>
     
    where:

    <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. If you are using the default CMS location, the value would be <server_root>/alias.

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


     

Registering a Log Module

You can create new log modules using the CMS SDK. If you do create a log module, you need to register it before it is available for use.

You can register new log plug-in modules using the CMS console. 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 console (see Logging Into the CMS Console).
  2. Select the Configuration tab.
  3. In the navigation tree, select Logs, and then in the right pane, select the Log Event Listener Plug-in Registration tab.
  4. Click Register.
    5. The Register Log Event Listener Plug-in Implementation window appears.
     
  5. Specify information as appropriate:
    6. 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.customplugins, type com.customplugins.customLog.
     
  6. Click OK.
    7. You are returned to the Log Event Listener Plug-in 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 console. Before deleting a module, be sure to delete all the listeners that are based on this module; see Log File Rotation.

To delete a module:

  1. Log in to the CMS console (see Logging Into the CMS Console).
  2. Select the Configuration tab.
  3. In the navigation tree, select Logs, and then in the right pane, select the Log Event Listener Plug-in Registration tab.
  4. In the Plug-in Name list, select the module you want to delete and click Delete.
  5. When prompted, confirm the delete action.

Signed Audit Log

The signed audit log is a feature that creates a log recording system events; the events that are recorded are selectable from a list of events. This feature, when enabled, records all system events and produces a verbose set of messages about this activity; be careful when using this feature to provide enough space in your file system for this log. The signed audit log feature is disabled by default.

You can also set this audit log up as a signed audit log. You enable this by setting the logSigning parameter to enable and providing the nickname of the certificate that will be used to sign this log.

When this log is setup as a signed audit log, only a user with auditor privileges can access and view the log. Auditors can use the AuditVerify tool to verify that signed audit logs have not been tampered with.

When you first set the server up, if you have not created a dedicated certificate for log signing, but you want to turn on the auditing feature anyway, you can use the singing certificate for that subsystem to sign the logs. To do this, specify caSigningCert cert-<cms instance name> as the value in the signedAuditCertNickname parameter for a Certificate Manager, specify the appropriate signing certificate for other subsystems.

You can also configure which events are recorded in the log by adding or deleting the event type form the value of the events parameter. Table 8-3 lists the events that are loggable events. To add an event, add the logging event to the list; to delete an event, remove it from the list. Log events are separated by commas with no spaces.


Table 8-3    Signed-Audit Log Events


Logging Event

Type of Log Messages are Generated

AUDIT_LOG_STARTUP

 

The startup of the subsystem, and thus the start of the startup of the audit function.

 

AUDIT_LOG_SHUTDOWN

 

The shutdown of the subsystem, and thus the start of the startup of the audit function.

 

ROLE_ASSUME

 

A user assuming a role. A user assumes a role once they have passed through authentication and authorization systems. Note that only the default roles of administrator, auditor, and agent will be tracked. Custom roles are not tracked.

 

CONFIG_CERT_POLICY

 

A change is made to the configuration settings for the policy framework.

 

CONFIG_CERT_PROFILE

 

A change is made to the configuration settings for the certificate profile framework.

 

CONFIG_CRL_PROFILE

 

A change is made to the configuration settings for the CRL framework, in other words, any of the settings for CRLs including extensions, frequency, and CRL format.

 

CONFIG_OCSP_PROFILE

 

A change is made to the configuration settings for the Online Certificate Status Manager.

 

CONFIG_AUTH

 

A change is made to the configuration settings for the authentication framework.

 

CONFIG_ROLE

 

A change is made to the configuration settings for roles including changes made to users or groups.

 

CONFIG_ACL

 

A change is made to the configuration settings for the ACL framework.

 

CONFIG_SIGNED_AUDIT

 

A change is made to the configuration settings for the signed audit feature.

 

CONFIG_ENCRYPTION

 

A change is made to the encryption settings including certificate settings and SSL cipher preferences.

 

CONFIG_TRUSTED_PUBLIC_KEY

 

The certificate setup wizard is used to import certificates into the certificate database, or any activity in "Manage Certificates."

 

CONFIG_DRM

 

The configuration associated with a DRM changes.

 

SELFTESTS_EXECUTION

 

The self-tests are executed.

 

AUDIT_LOG_DELETE

 

The signed audit log expires or is deleted. Note: The authorization system should not allow such a deletion.

 

LOG_PATH_CHANGE

 

The path or name for the signed audit, system, transaction or any customized log is changed. Note: The authorization system should not allow such a change.

 

LOG_EXPIRATION_CHANGE

 

When an attempt is made to change log expiration time. Note: The authorization system should not allow such a change.

 

PRIVATE_KEY_ARCHIVE

 

When an encryption private key is requested during enrollment.

 

PRIVATE_KEY_ARCHIVE_PROCESSED

 

A private encryption key is archived in the Data Recovery Manager (the private key request is processed).

 

KEY_RECOVERY_REQUEST

 

A request is made to recover a private encryption key that is stored in the Data Recovery Manager.

 

KEY_RECOVERY_AGENT_LOGIN

 

DRM agents log in as recovery agents to approve key recovery requests.

 

KEY_RECOVERY_PROCESSED

 

A key recovery has been processed.

 

KEY_GEN_ASYMMETRIC

 

Asymmetric keys are generated

 

NON_PROFILE_CERT_REQUEST

 

A certificate request is made that is not through the certificate profile framework.

 

PROFILE_CERT_REQUEST

 

A certificate request is made through the certificate profile framework.

 

CERT_REQUEST_PROCESSED

 

A certificate request is being processed.

 

CERT_STATUS_CHANGE_REQUEST

 

The request is made to change the status of a certificate.

 

CERT_STATUS_CHANGE_REQUEST_PROCESSED

 

A certificate status change is processed.

 

AUTHZ_SUCCESS

 

A CMS user is successfully processed by the authorization servlets.

 

AUTHZ_FAIL

 

A CMS user is not successfully processed by the authorization servlets.

 

INTER_BOUNDARY

 

Records stat transfer between different subsystems.

 

AUTH_FAIL

 

A CMS user does not successfully authenticate.

 

AUTH_SUCCESS

 

A CMS user does successfully authenticate.

 

CERT_PROFILE_APPROVAL

 

A certificate profile sent by an administrator is approved by an agent.

 

PROOF_OF_POSSESSION

 

When proof of possession is checked during certificate enrollment.

 

CRL_RETRIEVAL

 

When a CRL is retrieved by the OCSP Responder

 

CRL_VALIDATION

 

When a CRL is retrieved and validation process occurs.

 

CMC_SIGNED_REQUEST_SIG_VERIFY

 

Used when CMC (agent-pre-signed) cert requests or revocation requests are submitted and signature is verified.

 

AUDIT_LOG_SIGNING

 

The audit buffer is signed and flushed to disk.

 


Setting Up Signed Audit Logs

To set up signed audit logs:

  1. Set up the certificate profiles caAuditCert and raAuditCert. See "Setting Up Certificate Profiles" for information about setting up certificate profiles. See Chapter 11 "Certificate Profiles" for general information about certificate profiles.
  2. Approve the caAuditCert and raAuditCert certificate profiles by approving them in the agent services interface, thus enabling them.
    3. If the request for this certificate is received in the end-entity interface of a Certificate Manager, enable the caAuditCert profile in that Certificate Manager.
     
    If the request for this certificate is received in the end-entity interface of a Registration Manager, enable the raAuditCert profile in that Registration Manager and enable the raAuditCert profile in that Certified Manager that processes the requests of that Registration Manager.
     
  3. Use the Certificate Setup Wizard to obtain a certificate request for the private keys and certificates that will be used to sign the log files. When running the certificate wizard, specify that the request is of type Other, and request that the output be a certificate request in PKCS#10 format. See "Certificate Setup Wizard" for information about using the Certificate Setup Wizard to generate requests.
  4. Submit the PKCS#10 request generated in the previous step to the profile enrollment for auditor certificates in the end-entity interface of the Certificate Manager that will issue the certificate.
  5. Set up the signed audit log—it is disabled by default—by setting it up in Netscape Console. Follow the procedure in the section "Configuring Logs in the CMS Console". Specify the nickname of the log you received in the previous step as the value of the signedAuditCertNickname parameter and specify the events that will be logged in the events parameter.
  6. Assign auditor users, if you have not done so, by creating the user and assigning them to the auditor group. Members of the auditor group are the only users who can view and verify the signed audit log. See "Setting up Administrators, Agents, and Auditors" for details about setting up auditors.
  7. Auditors can view signed audit logs by viewing them from the IT environment.
  8. Auditors can verify logs by using the AuditVerify tool. See the CMS Command-Line Tools Guide for details about using this tool.

Audit Logging Failures

There are events that could cause the audit logging function to fail. In other words, events cannot be written to the log. For example, when the file system containing the audit log file is full or when the file permissions for the log file is accidentally changed. If audit logging fails, CMS will shut down in the following manner:

When this happens, CMS administrator(s) and CMS auditor(s) should work together with the Operating System administrator to resolve the disk space or file permission issue(s). When the IT problem is resolved,