15.2. Managing Logs
15.2.1. An Overview of Log Settings
15.2.1.1. Services That Are Logged
Table 15.1. Services Logged
Service | Description |
---|---|
ACLs | Logs events related to access control lists. |
Administration | Logs events related to administration activities, such as HTTPS communication between the Console and the instance. |
All | Logs events related to all the services. |
Authentication | Logs events related to activity with the authentication module. |
Certificate Authority | Logs events related to the Certificate Manager. |
Database | Logs events related to activity with the internal database. |
HTTP |
Logs events related to the HTTP activity of the server. Note that HTTP events are actually logged to the errors log belonging to the Apache server incorporated with the Certificate System to provide HTTP services.
|
Key Recovery Authority | Logs events related to the KRA. |
LDAP | Logs events related to activity with the LDAP directory, which is used for publishing certificates and CRLs. |
OCSP | Logs events related to OCSP, such as OCSP status GET requests. |
Others | Logs events related to other activities, such as command-line utilities and other processes. |
Request Queue | Logs events related to the request queue activity. |
User and Group | Logs events related to users and groups of the instance. |
15.2.1.2. Log Levels (Message Categories)
Table 15.2. Log Levels and Corresponding Log Messages
Log level | Message category | Description |
---|---|---|
0-1 | Tracing | These messages contain finer-grained debugging information. This level should not be used regularly because it may impact the performance. |
2-5 | Debugging | These messages contain debugging information. This level is not recommended for regular use because it generates too much information. |
6-10 | Informational | These messages provide general information about the state of the Certificate System, including status messages such as Certificate System initialization complete and Request for operation succeeded. |
11-15 | Warning | These messages are warnings only and do not indicate any failure in the normal operation of the server. |
> 15 | Failure | These messages indicate errors and failures that prevent the server from operating normally, including 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). Setting the level above 15 will minimize the logs, as only failures will be recorded. |
15.2.1.3. Buffered and Unbuffered Logging
- The buffer gets full. The buffer is 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 Console. The server retrieves the latest log when it is queried for current logs.
15.2.1.4. Log File Rotation
- 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 thirty days).
Note
log
directory to an archive medium.
Note
signtool
, that signs log files before archiving them as a means of tamper detection. For details, see Section 15.2.4.5, “Signing Log Files”.
15.2.2. Configuring Logs in the Console
CS.cfg
file. Specialized logs, such as signed audit logs and custom logs, can also be created through the Console or configuration file.
- In the navigation tree of the Configuration tab, select Log.
- The Log Event Listener Management tab lists the currently configured listeners.To create a new log instance, click Select Log Event Listener Plug-in Implementation window., and select a module plug-in from the list in the
- Set or modify the fields in the Log Event Listener Editor window. The different parameters are listed in Table 15.3, “Log Event Listener Fields”.
Table 15.3. Log Event Listener Fields
Field | Description |
---|---|
Log Event Listener ID | Gives the unique name that identifies the listener. The names can have any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-), but it cannot contain other characters or spaces. |
type | Gives the type of log file. system creates error and system logs; transaction records audit logs. |
enabled | Sets whether the log is active. Only enabled logs actually record events. The value is either true or false . |
level | Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security. For more information, see Section 15.2.1.2, “Log Levels (Message Categories)”. |
fileName | Gives the full path, including the file name, to the log file. The subsystem user should have read/write permission to the file. |
bufferSize | Sets the buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB. For more information on buffered logging, see Section 15.2.1.3, “Buffered and Unbuffered Logging”. |
flushInterval | Sets the amount of time before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds. |
maxFileSize | Sets the size, in kilobytes (KB), 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 new. For more information on log file rotation, see Section 15.2.1.4, “Log File Rotation”. The default size is 2000 KB. |
rolloverInterval | Sets the frequency for the server to rotate the active log file. The available options are hourly, daily, weekly, monthly, and yearly. The default is monthly. For more information, see Section 15.2.1.4, “Log File Rotation”. |
15.2.3. Configuring Logs in the CS.cfg File
CS.cfg
file, see the Configuring Logs in the CS.cfg File section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
15.2.4. Managing Audit Logs
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.
/var/log/pki/instance_name/subsystem_name/
directory with other types of logs, while signed audit logs are written to /var/log/pki/instance_name/subsystem_name/signedAudit/
. The default location for logs can be changed by modifying the configuration.
15.2.4.1. A List of Audit Events
15.2.4.2. Enabling Signed Audit Logging after Installation
pki_audit_group
deployment parameter with the pkispawn
command. If, however, signed audit logs were not configured when an instance was created, they can be enabled afterwards by reassigning ownership of the audit log directory to the auditor system users group, such as pkiaudit
.
- Stop the instance:
systemctl stop pki-tomcatd@instance_name.service
- Set the group ownership of the signed audit log directory to the PKI auditors operating system group, such as
pkiaudit
. This allows the users in the PKI auditors group to have the required read access to thesignedAudit
directory to verify the signatures on the log files. No user (except for the Certificate System user account,pkiuser
) should have write access to the log files in this directory.chgrp -R pkiaudit /var/log/pki/instance_name/subsystem_name/signedAudit
- Restart the instance:
systemctl start pki-tomcatd@instance_name.service
15.2.4.3. Configuring a Signed Audit Log in the Console
Note
logSigning
parameter to enable
and providing the nickname of the certificate used to sign the log. A special log signing certificate is created when the subsystems are first configured.
AuditVerify
tool to verify that signed audit logs have not been tampered with.
- Open the Console.
Note
To create or configure the audit log by editing theCS.cfg
file, see the Configuring Logs in the CS.cfg File section in the Red Hat Certificate System Planning, Installation, and Deployment Guide. - In the navigation tree of the Configuration tab, select Log.
- In the Log Event Listener Management tab, select the SignedAudit entry.
- Click.
- There are three fields which must be reset in the Log Event Listener Editor window.
- Fill in the signedAuditCertNickname. This is the nickname of the certificate used to sign audit logs. An audit signing certificate is created when the subsystem is configured; it has a nickname like
auditSigningCert cert-instance_name subsystem_name
.Note
To get the audit signing certificate nickname, list the certificates in the subsystem's certificate database usingcertutil
. For example:certutil -L -d /var/lib/pki-tomcat/alias Certificate Authority - Example Domain CT,c, subsystemCert cert-pki-tomcat u,u,u Server-Cert cert-pki-tomcat u,u,u auditSigningCert cert-pki-tomcat CA u,u,Pu
- Set the logSigning field to
true
to enable signed logging. - Set any events which are logged to the audit log. Appendix E, Audit Events lists the loggable events. Log events are separated by commas with no spaces.
- Set any other settings for the log, such as the file name, the log level, the file size, or the rotation schedule.
Note
By default, regular audit logs are located in the/var/log/pki/instance_name/subsystem_name/
directory with other types of logs, while signed audit logs are written to/var/log/pki/instance_name/subsystem_name/signedAudit/
. The default location for logs can be changed by modifying the configuration. - Save the log configuration.
AuditVerify(1)
man page for details about using this tool.
15.2.4.4. Handling Audit Logging Failures
- Servlets are disabled and will not process new requests.
- All pending and new requests are killed.
- The subsystem is shut down.
15.2.4.5. Signing Log Files
signtool
). For details about this utility, see http://www.mozilla.org/projects/security/pki/nss/tools/.
signtool
command to sign the log directories:
signtool -d secdb_dir -k cert_nickname -Z output input
- secdb_dir specifies the path to the directory that contains the certificate, key, and security module databases for the CA.
- cert_nickname specifies the nickname of the certificate 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.
15.2.4.6. Filtering Audit Events
Table 15.4. Supported Audit Event Filters
Type | Format | Example |
---|---|---|
Presence | (attribute=*) | (ReqID=*) |
Equality | (attribute=value) | (Outcome=Failure) |
Substring | (attribute=initial*any*...*any*final) | (SubjectID=*admin*) |
AND operation | (&(filter_1)(filter_2)...(filter_n)) | (&(SubjectID=admin)(Outcome=Failure)) |
OR operation | (|(filter_1)(filter_2)...(filter_n)) | (|(SubjectID=admin)(Outcome=Failure)) |
NOT operation | (!(filter)) | (!(SubjectID=admin)) |
Example 15.5. Filtering Audit Events
InfoName
field set to rejectReadon
or cancelReason
:
- Edit the
/var/lib/pki/instance_name/subsystem_type/conf/CS.cfg
file and set the following parameters:log.instance.SignedAudit.filters.PROFILE_CERT_REQUEST=(Outcome=Failure) log.instance.SignedAudit.filters.CERT_REQUEST_PROCESSED=(|(InfoName=rejectReason)(InfoName=cancelReason))
- Restart Certificate System:
# systemctl restart pki-tomcatd@instance_name.service
15.2.5. Managing Log Modules
classes
directory; the implementation must be on the class path.
- Create the custom job class. For this example, the custom log plug-in is called
MyLog.java
. - Compile the new class into the lib directory of the instance.
javac -d . /var/lib/pki/pki-tomcat/lib -classpath $CLASSPATH MyLog.java
- Create a directory in the CA's
WEB-INF
web directory to hold the custom classes, so that the CA can access them.mkdir /var/lib/pki/pki-tomcat/webapps/ca/WEB-INF/classes
- Set the owner to the Certificate System system user (
pkiuser
).chown -R pkiuser:pkiuser /var/lib/pki/pki-tomcat/lib
- Register the plug-in.
- Log into the Console.
- In the Configuration tab, select Logs from the navigation tree. Then select the Log Event Listener Plug-in Registration tab.
- Click.The Register Log Event Listener Plug-in Implementation window appears.
- Give the name for the plug-in module and the Java™ class name.The Java™ class name is the full path to the implementing Java™ class. If this class is part of a package, include the package name. For example, registering a class named
customLog
in a package namedcom.customplugins
, the class name would becom.customplugins.customLog
. - Click.