Chapter 8

Administrative Basics

---

This chapter discusses the Red Hat Certificate System (CS) 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
• System Passwords
• Starting, Stopping, and Restarting CS Instances
• Subsystem Configuration Overview
• Mail Server
• Configuration Files
• Logs
• Signed Audit Log
• Self Tests
• Ports
• Changing an IP Addresses
• The Internal Database
• Managing the Certificate Database
• Tokens for Storing CS Keys and Certificates
• Hardware Cryptographic Accelerators
• Configuring the Server's Security Preferences

The Administrative Interface

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

This section provides an overview of Red Hat Administration Server and the CS console.

Red Hat Administration Server

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

Administration Server must be running before you can access Red Hat Console.

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

Starting Administration Server

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

To start Administration Server:

1. Go to the following directory:

<server_root>

where:

<server_root>

Specifies the directory in which you installed CS.

2. Type the following command:

./start-admin

Red Hat Console

Red Hat 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 Red Hat Directory and Certificate 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 CS-specific tasks from the Console tab:

• Launch the CS console.
• Install instances of CS.
• Remove an instance of CS.
• Clone an instance of CS.
• Set access permissions for CS.

For complete details about Red Hat Console, see Managing Servers with Red Hat Console.

Logging Into Red Hat Console

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

To login to Red Hat Console:

1. Go to the following directory:

<server_root>

where:

<server_root>

Specifies the directory in which you installed CS.

2. Type the following command:

./startconsole

The login dialog opens.

3. Log into Red Hat Console by filling in the following field:

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

Red Hat Console opens.

The CS Console

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

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

• Tasks Tab

The Tasks tab enables you to perform tasks such as starting, stopping, and restarting the server, and running the Certificate Setup Wizard. For more information, see "Starting, Stopping, and Restarting CS Instances," on page 246.

• Configuration Tab

The Configuration tab enables you to view and modify the configuration settings for the server instance. The choices available in this tab will change depending on which subsystem is installed in this server instance. The specifics of setting these configuration settings is contained in the appropriate section of this guide.

• Status Tab

The Status tab allows you to monitor the server by viewing the contents of various logs maintained by CS. See "Logs," on page 255 for more information.

Logging Into the CS Console

To log into the CS console:

1. Log into Red Hat Console, see "Logging Into Red Hat Console," on page 237.
2. Double-click the CS instance you want to open from the Red Hat Console navigation tab, or select the instance and click Open.

The CS 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 CS Instances" on page 246.

3. You must login into CS as an administrator user of CS. Provide the administrator user ID and password in the following fields:

User ID. Provide a user ID that has CS 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 CS console opens.

Viewing Information About a CS instance

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

To view information pertaining to a CS instance:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. In the Console tab, select the CS instance you want to view.

The right pane shows information about the selected CS instance.

The information displayed includes the following:

Server Name. A descriptive name of the CS instance.

Description. Additional information that helps you identify the CS 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" on page 309.

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:

Select the instance and click Edit.

Details about the selected CS 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 CS.

Setting up Certificate Authentication for the CS Console

Certificate Authentication of Red Hat Console, and the CS window can now be enabled so that administrators must authenticate using a client certificate that is good for SSL authentication before logging into Red Hat Console, or the CS 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 Red Hat 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:

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:

<server_root>/bin/cert/tools

1. Issue the command:

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

./pk12util -i <pk12file> -d "<home directory>/.mcc"

9. Log in to the CS console (see "Logging Into the CS Console" on page 239).
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.

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 CS server.
17. Go to the directory <serverRoot>/cert-<instanceID>/config
18. Open the file CS.cfg.
19. Change the value of the authType parameter from pwd to sslclientauth:

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":

<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 CS.
24. Start Red Hat Console. You will be prompted for your certificate.

System Passwords

CS 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

CS comes with a plug-in, called password-quality checker, to monitor the quality of passwords set within the CS system. All passwords used in CS 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 CS 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 CS SDK.

Passwords Stored by the Server

CS 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 CS 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:

• For a Certificate Manager the token password unlocks the private keys for the Certificate Manager's CA signing and SSL server certificates. If the Certificate Manager's OCSP option was enabled during installation, then the password also unlocks the private key for the Certificate Manager's OCSP signing certificate.
• For a Registration Manager the token password unlocks the private keys for the Registration Manager's signing and SSL server certificates.
• For a Data Recovery Manager the token password unlocks the private keys for the Data Recovery Manager's storage keys and transport and SSL server certificates.
• For an Online Certificate Status Manager the token password unlocks the private keys for the Online Certificate Status Manager's signing and SSL server certificates.

Deleting the password.conf File

You can choose to delete the password.conf file during CS 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 CS instance from the CS console. CS 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, CS ships with a command-line named PasswordCache located in the <server_root>/bin/cert/tools directory. For complete details about this utility, see the Red Hat Certificate System Command-Line Tools Guide.

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

• The bind password used by CS to access and update the internal database.
• The bind password used by CS to access and remove PINs from the authentication directory, if you've configured CS to remove PINs from the authentication directory.
• The bind password used by CS to access and create/modify user entries in the directory used for portal registration, if you've configured CS for portal enrollment.
• The bind password used by CS to access and update the LDAP directory; this is required only if you have configured CS for publishing certificates and CRLs to an LDAP-compliant directory.

Starting, Stopping, and Restarting CS Instances

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

Starting a Server Instance

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

Starting From Red Hat Console

To start a CS instance from Red Hat Console:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Select the CS instance you want to open from the Red Hat Console navigation tab and then right-click your mouse selecting the Start Server option from the pop-up menu.

Alternatively

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Double-click the CS instance you want to open from the Red Hat Console navigation tab, or select the instance and click Open.
3. Go to the Tasks Tab and select Start Server.

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 CS console. For more information, see "Passwords Stored by the Server," on page 244.

Starting From the Command Line

To start a CS 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:

<server_root>/cert-<instance_id>

3. Type the following command:

./start-cert

Note	If CS 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 Red Hat Console or from the command line.

With this version of CS, CS 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 CS.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 Red Hat Console

To stop a CS instance from Red Hat Console:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Select the CS instance you want to stop from the Red Hat Console navigation tab and then right-click your mouse selecting the Stop Server option from the pop-up menu.

Alternatively

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Double-click the CS instance you want to open from the Red Hat 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 CS instance from the command line:

1. Log in either as root or with the server's user account.
2. Go to the following directory:

<server_root>/cert-<instance_id>

3. Type the following command:

./stop-cert

Restarting a Server Instance

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

Restarting From the CS Console

To restart a CS instance from the CS console:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Double-click the CS instance you want to open from the Red Hat 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 CS instance from the command line:

1. Log in either as root or with the server's user account.
2. Go to the following directory:

<server_root>/cert-<instance_id>

3. Type the following command:

./restart-cert

Subsystem Configuration Overview

Once you install CS 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 CS Instances

When CS is installed on a host, a single instance of CS 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 CS:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. In the navigation tree, select the server group in which you want to create a CS instance.
3. From the Object menu, choose Create Instance Of, then choose CS from the pop-up list.

Alternatively, you can select the server group and then right-click your mouse choosing Create Instance Of->Certificate System.

The Create Server Instance dialog opens.

4. Type a unique name or identifier for the new instance.

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.

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 CS instance from your host. Removing a CS instance is not the same as uninstalling CS. For instructions on uninstalling CS, see "Uninstalling CS" on page 76.

To remove a CS instance:

1. Log in to Red Hat Console (see "Logging Into Red Hat Console" on page 237).
2. Stop the CS instance.
3. Select the CS instance you want to remove and choose Remove Server from the Object menu.

Alternatively, you can select the CS 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.

The selected CS 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 CS instance to send its notification messages. You set up a mail server using the following procedure:

1. In the CS 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:

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 CS 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 CS, the installer creates an ASCII file, named CS.cfg, and populates it with the appropriate configuration parameters. You can control the way CS functions by making the appropriate changes in the CS console, which is the recommended method for making configuration changes. The changes you make in the CS 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 CS has its own configuration file, CS.cfg. The file for the subsystem is different depending on your installation choices, and on which subsystem is installed in that instance.

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

<server_root>/cert-<instance_id>/config

where:

<server_root>	Specifies the directory in which CS is installed
<instance_id>	Specifies the name of the CS 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. CS 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 CS instance whose configuration file you want to edit (see "Starting, Stopping, and Restarting CS Instances" on page 246).

The configuration file is stored in the cache when you start CS. Any changes you make to CS through the CS 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:

<server_root>/cert-<instance_id>/config

3. Open the file CS.cfg in a text editor.
4. Edit the parameters in the file and save your changes.
5. Start CS (see "Starting, Stopping, and Restarting CS Instances" on page 246).

Guidelines for Editing the Configuration File

The following are guidelines for editing the configuration file:

• The format for parameters is as follows:

#comment

[parameter]=value
 

• Comment lines begin with the pound (#) character and are ignored.
• A line beginning with white space is considered a continuation of the previous line.
• Comment lines, blank lines, unknown parameters, or misspelled parameters are ignored by the server.
• Subsystem-specific parameters are distinguished by a prefix identifying the subsystem as follows:
  • ca for the Certificate Manager
  • ra for the Registration Manager
  • kra for the Data Recovery Manager
  • ocsp for the Online Certificate Status Manager
• The parameter names and their values are strings. The parameter names can be hierarchically structured with '.' notation with multiple levels-for example, ca.Policy.rule.RSAKeyRule.maxSize. The entries corresponding to a lower level (such as Policy in the example) can be requested from the configuration corresponding to its higher level (ca in the example).
• The values that need to be localized (such as distinguished names in multibyte format) should be entered in utf8 format.
• The values of some parameters are referenced to other parts of the configuration file. For example, assume that a parameter is defined as subsystem.id=ca; when this parameter is processed by the server, all the parameters beginning with ca will be used.
• The configuration file supports Unix-style file separator, the forward slash (/). If the backward slash (\) file separator is required, use two backward slashes (\\) instead of one.
• Authentication parameters:
  • All authentication-specific information, such as names of registered authentication plug-in modules and any configured instances, appears in the Authentication section of the configuration file.
  • Each registered authentication plug-in module is identified by its implementation name and the corresponding Java class.
  • Each configured instance of an authentication module is identified by the name or ID you specified when creating it.
  • You can create multiple instances from an implementation; each instance must have a unique name. To do this, you would copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the value of all the parameters as is appropriate for your needs.
  • The name of an authentication instance must be used in the corresponding enrollment form so that the server is able to determine the authentication method during end-user enrollment.
• Job Scheduler parameters:
  • All job-specific information, such as registered job modules and configured instances, appears in the Job Scheduler section of the configuration file.
  • Each registered job module is identified by its implementation name and the corresponding Java class.
  • Each job (or configured instance of a job module) is identified by the name specified when the job was created.
  • You can create as many instances of an implementation as you like; each instance must have a unique name. To do this, you would copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the value of all the parameters as is appropriate for your needs.
• Policy parameters:
  • All policy-specific information, such as registered policy plug-in implementations, configured rules, and ordering, appear in the Policy section of the configuration file.
  • Each registered policy plug-in module is identified by its implementation name and the corresponding Java class.
  • Each configured rule of a policy module is identified by the name specified when the rule was created.
  • You can create multiple rules out of an implementation; each rule must have a unique name. To do this, you would copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the value of all the parameters as is appropriate for your needs.

Duplicating Configuration From One Instance to Another

If you have deployed a large number of CS 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 CS console to configure logs maintained by CS, and how to monitor the server's activities by viewing log contents.

This section contains the following sub-sections:

• About Logs
• Configuring Logs in the CS Console
• Monitoring Logs
• Signing Log Files
• Registering a Log Module
• Deleting a Log Module

About Logs

CS 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 CS 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 CS policy framework.

Each instance of Red Hat Certificate System (CS) 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 Red Hat Enterprise Server, which is installed with CS 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 CS; they are only configurable from within Enterprise Server. See the Red Hat 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 CS Console, you must configure it by changing settings in the CS.cfg file. The information about logs in this section does not pertain to this log. See "Self Tests," on page 272 for more information about self-tests.

Installation and Setup Logs

The following logs are created when the CS 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 CS 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," on page 268.

Services That Are Logged

All major components and protocols (or services) of CS 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" on page 265.

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 CS console and CS.
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 Red Hat Enterprise Server that is incorporated into CS 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 CS-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 CS 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 8-2 Classification of Log Entries or Messages  

Log level	Message category	Description
0	Debugging	These messages contain debugging information. Generally, you would not want to set a log to the debugging level since it would yield far too much information for normal use.
1	Informational (default selection for audit log)	These messages provide general information about the state of CS. For example, status messages such as "Certificate 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.

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

CS 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:

• 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 CS console-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.

Log File Rotation

Log files are rotated when either of the following 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).

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.

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

CS 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" on page 266.

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," on page 257 for details about signed audit logs.

By default, rotated log files are not deleted.

Configuring Logs in the CS Console

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

To configure logs for a CS instance:

1. Log in to the CS console (see "Logging Into the CS Console" on page 239).
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. Either create a new log instance, delete an existing instance, or modify an existing instance:

To create a new log instance:

1. Click Add in the Log Event Listener Management tab.

The Select Log Event Listener Plug-in Implementation window appears. It lists registered log modules.

1. Select a plug-in module.
2. Click Next.

The Log Event Listener Editor window opens.

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

The Log Event Listener Editor window opens.

1. Continue to step 4.
4. Make changes to the following fields in the Log Event Listener Editor window:

Log Event Listener ID. Type a unique name that will help you identify the listener; be sure to note the following:

• Use any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-);
• Do not use other characters or spaces.

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)" on page 258.

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" on page 259. 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" on page 260.

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" on page 260.

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," on page 257 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 on page 269 for a complete list of auditable logging events.

5. Click OK.

You are returned to the Log Event Listener Management tab.

6. Click Refresh.

Configuring Logs in the CS.cfg File

To modify the configuration settings for logs:

1. Stop the CS instance.
2. Open the CS.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:

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" on page 259. 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