17.3. Configuring Logs in the CS.cfg File
During the installation configuration, logging can be configured by directly editing the
CS.cfg for the instance.
- Stop the subsystem instance.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
CS.cfgfile in the/var/lib/pki/instance_name/subsystem_type/confdirectory. - To create a new log, copy all of the entries for either the system or transactions log. These are the parameters that begin with
log.instance.Transactionsorlog.instance.System. Paste all entries at the bottom of the logging section and change the name of this instance by changing the wordTransactionsorSystemin each parameter to the new name. - To configure a log instance, modify the parameters associated with that log. These parameters begin with
log.instance.Table 17.3. Log Entry Parameters Parameter Description type The type of log file. system creates error and system logs; transaction records audit logs. enable Sets whether the log is active. Only enabled logs actually record events. level Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The log level setting is a numeric value, as listed in Section 17.1.2, “Log Levels (Message Categories)”. fileName The full path, including the file name, to the log file. The subsystem user should have read/write permission to the file. bufferSize 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 17.1.3, “Buffered and Unbuffered Logging”. flushInterval The amount of time, in seconds, before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds. maxFileSize The size, 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 17.1.4, “Log File Rotation”. The default size is 2000 KB. rolloverInterval The frequency which the server rotates the active log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 17.1.4, “Log File Rotation”. register[a] If this variable is set to false(the default value), the self-test messages are only logged to the log file specified byselftests.container.logger.fileName. If this variable is set totrue, then the self-test messages are written to both the log file specified byselftests.container.logger.fileNameas well as to the log file specified bylog.instance.Transactions.fileName.logSigning[b] Enables signed logging. When this parameter is enabled, provide a value for the signedAuditCertNickname parameter. This option means the log can only be viewed by an auditor. The value is either trueorfalse.signedAuditCertNickname[b] 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[b] Specifies which events are logged to the audit log. Log events are separated by commas with no spaces. [a] This is for self-test logs only.[b] This is for audit logs only. - Save the file.
- Start the subsystem instance.
# systemctl start pki-tomcatd@instance_name.service
OR (if usingnuxwdog watchdog)# systemctl start pki-tomcatd-nuxwdog@instance_name.service
17.3.1. Enabling and Configuring Signed Audit Log
17.3.1.1. Enabling Signed Audit Logging
By default, audit logging is enabled upon installation. However, log signing needs to be enabled manually after installation.
To display the current audit logging configuration:
# pki-server subsystem-audit-config-show Enabled: True Log File: audit_signing_log_file Buffer Size (bytes): 512 Flush Interval (seconds): 5 Max File Size (bytes): 2000 Rollover Interval (seconds): 2592000 Expiration Time (seconds): 0 Log Signing: False Signing Certificate: audit_signing_certificate
To enable signed audit logging:
- Use the
pki-serverutility to set the--logSigningoption totrue:# pki-server subsystem-audit-config-mod --logSigning True ... Log Signing: True ...
- Restart the instance:
# systemctl restart pki-tomcatd@instance_name.service
OR (if usingnuxwdog watchdog)# systemctl start pki-tomcatd-nuxwdog@instance_name.service
17.3.1.2. Configuring Audit Events
17.3.1.2.1. Enabling and Disabling Audit Events
For details about enabling and disabling audit events, see the Configuring a Signed Audit Log in the Console section in the Red Hat Certificate System Administration Guide.
In addition, audit event filters can be set to finer grained selection. See Section 17.3.1.2.2, “Filtering Audit Events”.
For a complete list of auditable events in Certificate System, see the Audit events appendix in the Red Hat Certificate System Administration Guide.
17.3.1.2.2. Filtering Audit Events
In Certificate System administrators can set filters to configure which audit events will be logged in the audit file based on the event attributes.
The format of the filters is the same as for LDAP filters. However, Certificate System only supports the following 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)) |
For further details on LDAP filters, see the Using Compound Search Filters section in the Red Hat Directory Server Administration Guide.
Example 17.2. Filtering Audit Events
To display the current settings for profile certificate requests and processed certificates:
$ pki-server ca-audit-event-show PROFILE_CERT_REQUEST Event Name: PROFILE_CERT_REQUEST Enabled: True Filter: None $ pki-server ca-audit-event-show CERT_REQUEST_PROCESSED Event Name: CERT_REQUEST_PROCESSED Enabled: True Filter: None
To log only failed events for profile certificate requests and events for processed certificate requests that have the
InfoName field set to rejectReason or cancelReason:
- Execute the following commands:
$ pki-server ca-audit-event-update PROFILE_CERT_REQUEST --filter "(Outcome=Failure)" ... Filter: (Outcome=Failure) $ pki-server ca-audit-event-update CERT_REQUEST_PROCESSED --filter "(|(InfoName=rejectReason)(InfoName=cancelReason))" ... Filter: (|(InfoName=rejectReason)(InfoName=cancelReason))
- Restart Certificate System:
# systemctl restart pki-tomcatd@instance_name.service
OR (if usingnuxwdog watchdog)# systemctl start pki-tomcatd-nuxwdog@instance_name.service
17.3.2. Configuring Self-Tests
The self-tests feature and individual self-tests are registered and configured in the
CS.cfg file. If a self-test is enabled, that self-test is listed for either on-demand or start up and is either empty or set as critical.
Critical self-tests have a colon and the word
critical after the name of the self-test. Otherwise, nothing is in this place. The server shuts down when a critical self-test fails during on demand self-tests; the server will not start when a critical self-test fails during start up.
The implemented self-tests are automatically registered and configured when the instance was installed. The self-tests that are registered and configured are those associated with the subsystem type.
A self-test's criticality is changed by changing the respective settings in the
CS.cfg file.
17.3.2.1. Default Self-Tests at Startup
The following self-tests are enabled by default at startup.
For the CA subsystem, the following self-tests are enabled by default at startup:
CAPresence- used to verify the presence of the CA subsystem.CAValidity- used to determine that the CA subsystem is currently valid and has not expired. This involves checking the expiration of the CA certificate.SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked. For the CA subsystem, only validity tests for each certificate are done, leaving out certificate verification tests which could result in an OCSP request. This behavior can be overridden with the following config parameter:selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=true
By default, this config parameter is consideredfalseif not present at all.
For the KRA subsystem, the following-self-tests are enabled:
KRAPresence- used to verify the presence of the KRA subsystem.KRAValidity- used to determine that the KRA subsystem is currently valid and has not expired. This involves checking the expiration of the KRA certificate.SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked.
For the OCSP subsystem, the following self-tests are enabled:
OCSPPresence- used to verify the presence of the OCSP subsystem.OCSPValidity- used to determine that the OCSP subsystem is currently valid and has not expired. This involves checking the expiration of the OCSP certificate.SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked. For the OCSP subsystem, only validity tests for each certificate are done, leaving out certificate verification tests which could result in an OCSP request. This behavior can be overridden with the following config parameter:selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=true
By default, this config parameter is consideredfalseif not present at all.
For the TKS subsystem, the following-self-tests are enabled:
TKSKnownSessionKey- used to verify the known session key of a TKS subsystem. This verifies the TKS is able to properly assist in creating keys on behalf of the TPS and supported smart cards.SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked.
For the TPS subsystem, the following-self-tests are enabled:
TPSPresence- used to verify the presence of the TPS subsystem.TPSValidity- used to determine that the TPS subsystem is currently valid and has not expired. This involves checking the expiration of the TPS certificate.SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked.
17.3.2.2. Modifying Self-Test Configuration
By default, the self-test configuration is compliant. However, some settings can change the visibility of self-test logging or improve performance. To modify the configuration settings for self-tests:
- Stop the subsystem instance.
- Open the
CS.cfgfile located in the instance'sconf/directory. - To edit the settings for the self-test log, edit the entries that begin with
selftests.container.logger. Unless otherwise specified, these parameters do not affect compliance. These include the following parameters:- bufferSize — Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
- enable — Specify
trueto enable. Only enabled logs actually record events. This value must be enabled for compliance. - fileName — Specify the full path, including the filename, to the file to write messages. The server must have read/write permission to the file. By default, the self-test log file is
/var/log/pki-name/logs/selftest.log - flushInterval — Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The
flushIntervalis the amount of time before the contents of the buffer are flushed out and added to the log file. - level — The default selection is 1; this log is not set up for any level beside 1.
- maxFileSize — Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The
maxFileSizedetermines 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 a new log file is started. - register — If this variable is set to
false(the default value), the self-test messages are only logged to the log file specified byselftests.container.logger.fileName. If this variable is set totrue, then the self-test messages are written to both the log file specified byselftests.container.logger.fileNameand the log file specified bylog.instance.Transactions.fileName. - rolloverInterval — Specify the frequency at which the server rotates the active error log file. The choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly.
- type — Set to
transaction; do not change this.
- To edit the order in which the self-test are run, specify the order by listing any of the self-test as the value of the following parameters separated by a comma and a space.To mark a self-test critical, add a colon and the word critical to the name of the self-test in the list.To disable a self-test, remove it as the value of either the
selftests.container.order.onDemandorselftests.container.order.startupparameters. - Save the file.
- Start the subsystem.
17.3.3. Additional Configuration for Debug Log
17.3.3.1. Enabling and Disabling Debug Logging
By default, debug logging is enabled in Certificate System. However, in certain situations, Administrators want to disable or re-enable this feature:
- Edit the
/var/lib/pki/instance_name/subsystem_type/conf/CS.cfgfile and set thedebug.enabledparameter:- To disable debug logging, set:
debug.enabled=false
Note
Debug logs are not part of audit logging. Debug logs are helpful when trying to debug specific failures in Certificate System or a failing installation.By default, debug logs are enabled. If it is not desired, the administrator can safely disable debug logging to turn down verbosity. - To enable debug logging, set:
debug.enabled=true
- Restart the Certificate System instance:
# systemctl restart pki-tomcatd@instance-name.service
OR (if usingnuxwdog watchdog)# systemctl restart pki-tomcatd-nuxwdog@instance-name.service
17.3.3.2. Setting up Rotation of Debug Log Files
Certificate System is not able to rotate debug logs. Debug logging is enabled by default and these logs grow until the file system is full. Use an external utility, such as
logrotate, to rotate the logs.
Example 17.3. Using logrotate to Rotate Debug Logs
Create a configuration file, such as
/etc/logrotate.d/rhcs_debug with the following content:
/var/log/pki/instance_name/subsystem/debug {
copytruncate
weekly
rotate 5
notifempty
missingok
}
To rotate debug logs for multiple subsystems in one configuration file, list the paths to the logs, each separated by white space, before the opening curly bracket. For example:
/var/log/pki/instance_name/ca/debug /var/log/pki/instance_name/kra/debug {
...
}
For further details about
logrotate and the parameters used in the example, see the logrotate(8) man page.
