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.
  1. Stop the subsystem instance.
    systemctl stop pki-tomcatd-nuxwdog@instance_name.service
  2. Open the CS.cfg file in the /var/lib/pki/instance_name/subsystem_type/conf directory.
  3. 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.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.

    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 by selftests.container.logger.fileName. If this variable is set to true, then the self-test messages are 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.
    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 true or false.
    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.
  5. Save the file.
  6. Start the subsystem instance.
    systemctl start pki-tomcatd@instance_name.service
    OR
    systemctl start pki-tomcatd-nuxwdog@instance_name.service (if using nuxwdog watchdog)

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:
  1. Use the pki-server utility to set the --logSigning option to true:
    # pki-server subsystem-audit-config-mod --logSigning True
      ...
      Log Signing: True
      ...
  2. Restart the instance:
    # systemctl restart pki-tomcatd@instance_name.service
    OR
    systemctl start pki-tomcatd-nuxwdog@instance_name.service (if using nuxwdog watchdog)

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:

Table 17.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))
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:
  1. 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))
    
  2. Restart Certificate System:
    # systemctl restart pki-tomcatd@instance_name.service
    OR
    systemctl start pki-tomcatd-nuxwdog@instance_name.service (if using nuxwdog watchdog)

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 considered false if 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 considered false if 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:
  1. Stop the subsystem instance.
  2. Open the CS.cfg file located in the instance's conf/ directory.
  3. 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 true to 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 flushInterval is 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 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 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 by selftests.container.logger.fileName. If this variable is set to true, then the self-test messages are written to both the log file specified by selftests.container.logger.fileName and the log file specified by log.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.
  4. 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.onDemand or selftests.container.order.startup parameters.
  5. Save the file.
  6. 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:
  1. Edit the /var/lib/pki/instance_name/subsystem_type/conf/CS.cfg file and set the debug.enabled parameter:
    • 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
  2. Restart the Certificate System instance:
    # systemctl restart pki-tomcatd@instance-name.service
    OR
    # systemctl restart pki-tomcatd-nuxwdog@instance-name.service (if using nuxwdog watchdog)

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.