14.3. Managing TPS Logs
14.3.1. An Overview of TPS Log Settings
14.3.1.1. Log Levels
The different events logged by Certificate System services are determined by the log levels, which makes identifying and filtering events simpler.
Log levels are represented by numbers (
0 to 10), each number indicating the level of logging to be performed by the server. The level sets how detailed the logging should be.
A higher priority level means less detail because only events of high priority are logged. For the TPS, the higher the numeric log level, the higher the priority. The highest priority for the TPS is
10.
A lower priority level means greater detail because more kinds of events are recorded in the log file. The lowest priority log level for the TPS is
0.
Table 14.7. Log Levels and Corresponding Log Messages
| Log level | Message category | Description |
|---|---|---|
| 0 | Debugging | These messages contain debugging information. This level is not recommended for regular use because it generates too much information. |
| 1 | Informational (default selection for audit log) | 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. |
| 2 | Warning | These messages are warnings only and do not indicate any failure in the normal operation of the server. |
| 3 | Failure; the default selection for system and error logs | 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). |
| 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. |
| 7 | PDU related events (debugging) | These messages contain debugging information for PDU events. This level is not recommended for regular use because it generates too much information for normal use. |
| 8 | PDU related events | These messages relate transactions and rules processed on a PDU, such as creating MAC tokens. |
| 9 | PDU related events | This log levels gives verbose log messages for events processed on a PDU, such as creating MAC tokens. |
| 10 | All logging levels | This log level enabled all logging levels for the TPS logs. |
Log levels can be used to filter log entries based on the severity of an event. By default, log level 3 (Failure) is set for all services.
The log level is successive; specifying a value of 3 causes levels 4, 5, and 6 to be logged. Log data can be extensive, 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 the logging level, log rotation, and server-backup policies appropriately so that all the log files are backed up and the host system does not get overloaded; otherwise, information can be lost.
14.3.1.2. TPS Buffered Logging
The TPS only supports buffered logging for the audit log. As with the Java subsystem logs, if buffered logging is configured for the TPS audit logs, the server creates buffers and holds the messages in the buffers for as long as possible. The server flushes out the messages to the log files only when one of the following conditions occurs:
- The buffer gets full. The buffer is full when the buffer size is equal to or greater than the value specified by the
bufferSizeconfiguration parameter. - The flush interval for the buffer is reached.
14.3.1.3. TPS Log File Rotation
TPS logs have the option of rotating the log files. If the log type is set to
RollingLogFile, then the logs files are rotated when they hit their size limit or age limit. This is the default. Alternatively, the TPS log type can be set to LogFile, so the TPS keeps a single log file for each type of log, and the file simply grows.
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).
Log files, especially the audit log file, contain critical information. These files should be periodically archived to some backup medium by copying the entire
logs/ directory to an archive medium.
NOTE
The Certificate System does not provide any tool or utility for archiving log files.
The Certificate System provides a command-line utility,
signtool, that signs log files before archiving them as a means of tamper detection. For details, see Section 14.2.5.5, “Signing Log Files”.
Signing log files is an alternative to the signed audit logs feature. Signed audit logs create audit logs that are automatically signed with a subsystem signing certificate.
By default, rotated log files are not deleted.
14.3.2. Configuring TPS Logging in CS.cfg
TPS logs, like RA logs, are configured differently than other subsystem logs. With the exception of the TPS audit log, which can be configured in the TPS admin services page, the TPS logs are viewed and configured manually in the
CS.cfg file. This is because logging is configured through the administrative console for the other subsystems (CA, OCSP, DRM, and TKS), but the TPS does not use a Java console.
The TPS maintains three subsystem logs:
- A debug log (tps-debug.log)
- An error log (tps-error.log)
- An audit log (tps-audit.log)
These logs are stored in the
/var/lib/instance_name/logs directory by default. Other types of logs, such as transaction logs and system logs, are not generated by the TPS instance.
14.3.2.1. About TPS Log Parameters
For each log generated by a TPS instance, there are three parameters which must be configured in the
CS.cfg file:
enable, which sets whether the log is generated.filename, which sets the name and location of the log.level, which sets the log level, the amount of information, and types of events logged. The log level is a number between0and10. The log levels are described in Section 14.2.1.2, “Log Levels (Message Categories)”.
logging.[audit|error|debug].enable=[true|false] logging.[audit|error|debug]=/var/logs/[filename] logging.[audit|error|debug].level=[level number]
The different logging parameters for the TPS logs are listed in Table 14.8, “TPS Logging Parameters”.
There are additional options to configure the audit log and to enable signed audit logging that are not used with the TPS's other logs.
Example 14.7. TPS Log Configuration
logging.audit.enable=true logging.audit.filename=/var/lib/pki-tps/logs/tps-audit.log logging.audit.level=10 logging.audit.logSigning=true logging.audit.nonselectable.events=AUDIT_LOG_STARTUP,AUDIT_LOG_SHUTDOWN,LOGGING_SIGNED_AUDIT_SIGNING logging.audit.selectable.events=optional events logging.audit.selected.events=selected events logging.audit.signedAuditCertNickname=auditSigningCert cert-pki-tps logging.audit.signedAuditFilename=/var/lib/pki-tps/logs/signedAudit/tps_audit/audit logging.debug.enable=true logging.debug.filename=/var/lib/pki-tps/logs/tps-debug.log logging.debug.level=7 logging.error.enable=true logging.error.filename=/var/lib/pki-tps/logs/tps-error.log logging.error.level=10
The general log settings are listed in Table 14.8, “TPS Logging Parameters”. The signed audit log parameters are covered in Table 14.10, “TPS Signed Audit Log Parameters”.
NOTE
Certain log features that are available to the other subsystems' logs do not apply to TPS logging:
- Registering and deleting log modules
- Buffered logging
Log level 0 is least verbose; 10 is most verbose. For example:
[2009-04-29 13:47:08] b65b9828 Upgradeop='applet_upgrade' app_ver='1.2.416DA155' new_app_ver='1.3.42659461' [2009-04-29 13:47:08] b65b9828 Formatstatus='success' app_ver='1.3.42659461' key_ver='0' cuid='40900062FF02000065C5' msn='FFFFFFFF' uid='' time='45389 msec' [2009-04-29 15:56:06] b65b9828 Enrollmentstatus='success' app_ver='1.3.42659461' key_ver='0101' cuid='40900062FF020000649D' msn='FFFFFFFF' uid='Steve Parkinson' time='21058 msec'
key_ver gives the key set version ID. A key version of 0101 is mapped to the TKS key version identifier #01#01. cuid gives the card unique identifier, the unique serial number of the smart card. app_ver gives the applet version number. time gives the elapsed time of the operation.
In this example,
b65b9828 is the thread ID number. All interactions performed with a particular smart card are done on a single thread, so the operations all have the same thread ID. In the case where TPS is interacting with multiple smart cards simultaneously, log messages pertaining to the smart card operations are interleaved. The thread ID can be used to correlate messages for a single smart card.
Table 14.8. TPS Logging Parameters
| Parameter | Description |
|---|---|
| logging.log_type.enable | Enables logging for that specific log type. The valid values are true|false. |
| logging.log_type.filename | Gives the full path to the log file, including its name. For example, /tmp/tps-debug.log. |
| logging.log_type.file.type | Enables log file rotation. The LogFile means that the file is not rotated, while RollingLogFile enables log file rotation. |
| logging.log_type.rolloverInterval | Sets the frequency (in seconds) which the server rotates the active log file. For more information, see Section 14.2.1.4, “Log File Rotation”. The default value is 2592000 (30 days). Setting rolloverInterval to 0 disables file rotation. |
| logging.log_type.maxFileSize | Sets 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 14.2.1.4, “Log File Rotation”. The default size is 2000 KB. |
| logging.log_type.expirationTime | Sets the maximum age of a log (in seconds). Logs that have been rotated, and have not been modified within the expiration period are deemed to have expired and are deleted. The default is 0 (disabled). |
| logging.log_type.level |
Sets the logging level. The levels range from 0 to 10.
|
| logging.audit.buffer.size | For TPS audit logs only. Sets the size for the audit log buffer. The default value is 512 bytes. When the buffer reaches this value it will be flushed and the data written to the log. |
| logging.audit.flush.interval | 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. |
| logging.audit.nonselectable.events | For TPS audit logs only. Contains a list of events which much be recorded in the audit log (either the regular audit log or the signed audit log). These events cannot be de-selected in the admin services configuration page. |
| logging.audit.selectable.events | For TPS audit logs only. Contains a list of all possible optional events that can be recorded in the audit log (regular or signed). This list is displayed in the admin services configuration page. |
| logging.audit.selected.events | For TPS audit logs only. Shows events that are actually selected in the admin services configuration page to be recorded in the audit log (regular or signed). This parameter's value can be edited directly in the CS.cfg file to include or exclude events from the audit log. |
14.3.2.2. Configuring TPS Logs
- Stop the TPS instance.
service pki-tps stop
- Edit the logging configuration. The log file parameters are listed in Table 14.8, “TPS Logging Parameters”, and the auditable events are listed in Table 14.9, “Events Recorded to the TPS Audit Log”.
logging.audit.buffer.size=512 logging.audit.enable=true logging.audit.filename=/var/lib/pki-tps/logs/tps-audit.log logging.audit.level=10 logging.audit.logSigning=true logging.audit.nonselectable.events=AUDIT_LOG_STARTUP,AUDIT_LOG_SHUTDOWN,LOGGING_SIGNED_AUDIT_SIGNING logging.audit.selectable.events=optional events logging.audit.selected.events=selected events logging.audit.signedAuditCertNickname=auditSigningCert cert-pki-tps logging.audit.signedAuditFilename=/var/lib/pki-tps/logs/signedAudit/tps_audit/audit logging.audit.file.type=RollingLogFile logging.audit.rolloverInterval=2592000 logging.audit.maxFileSize=2000 logging.debug.enable=true logging.debug.filename=/var/lib/pki-tps/logs/tps-debug.log logging.debug.level=7 logging.error.enable=true logging.error.filename=/var/lib/pki-tps/logs/tps-error.log logging.error.level=10
- Start the TPS instance.
service pki-tps start
14.3.3. Managing Audit Logs
NOTE
If the server cannot write to the TPS audit log — which can happen if there are incorrect file permissions or the partition becomes full — the TPS shuts down and will not restart until the condition has been addressed. Rotating the audit log files can prevent the TPS from shutting down by preventing the buffer from becoming full; while not required, log rotation is recommended. The parameters for rotating log files are covered in Table 14.8, “TPS Logging Parameters”.
All of the events which are written to the audit logs are listed in Table 14.9, “Events Recorded to the TPS Audit Log”.
Table 14.9. Events Recorded to the TPS Audit Log
| Event | Description |
|---|---|
| AUDIT_LOG_STARTUP | The start of the subsystem, and thus the start of the audit function. |
| AUDIT_LOG_SHUTDOWN | The shutdown of the subsystem, and thus the shutdown of the audit function. |
| LOGGING_SIGNED_AUDIT_SIGNING | Shows changes in whether the audit log is signed. |
| AUTHZ_SUCCESS | Shows when a user is successfully processed by the authorization servlets. |
| AUTH_SUCCESS | Shows when a user successfully authenticates. |
| ENROLLMENT | Shows when a token is enrolled through the TPS. |
| APPLET_UPGRADE | Shows when the applet on the token is upgraded. |
| AUTHZ_FAIL | Shows when a user is not successfully processed by the authorization servlets. |
| ROLE_ASSUME | A user assuming a role. A user assumes a role after passing through authentication and authorization systems. Only the default roles of administrator, auditor, and agent are tracked. Custom roles are not tracked. |
| PIN_RESET | Shows when the password used to access the token is reset. |
| CONFIG | Shows general configuration changes not specifically define below. |
| CONFIG_ROLE | Shows that a change has been made to the configuration settings for roles, including changes made to users or groups. |
| CONFIG_TOKEN | Shows that a change was made to a token's configuration settings. |
| CONFIG_PROFILE | Shows that a change was made to a profile's configuration settings. |
| CONFIG_AUDIT | Shows that a change was made to the audit log configuration. |
| KEY_CHANGEOVER | Shows whether key changeover worked successfully. |
| RENEWAL | Shows if a token is renewed successfully through the TPS. |
| AUTH_FAIL | Shows when a user does not successfully authenticate. |
| FORMAT | Records when a token is formatted. |
| CIMC_CERT_VERIFICATION | Shows when a router (Cisco Integrated Management Controller) certificate verification request has been processed. |
14.3.3.1. Configuring TPS Audit Logs in the Admin Services Page
The TPS's audit log records specific system events that are related to both TPS subsystem events like startup and token management events like formatting a smart card. At the least, a note of these activities is recorded; for some activities verbose messages are recorded.
NOTE
The TPS debug and error logs cannot be configured through the admin services page; these must be configured directly in the
CS.cfg file, as described in Section 14.3.2, “Configuring TPS Logging in CS.cfg”.
IMPORTANT
While audit logs can be configured in the
CS.cfg file, it is strongly recommended that you edit the log settings only through the admin services page. All changes to the TPS performed through the web services pages are recorded to the audit log, so changes can be tracked.
There are two locations for the audit logs. Regular audit logs are in
/var/lib/instance_name/logs/tps-audit.log. If signed audit logging is enabled, then the signed audit log is written to /var/lib/instance_name/logs/signedAudit/tps-audit.log.
Enabling audit logging and signed audit logging is done via the Enable|Disable radio buttons on the Configuring Signed Audit Logging paged, linked from the Administrator Operations. Enabling signed audit logging, signs the audit log after every entry with a special signing certificate as a sign that the log has not been tampered with.
After enabling logging, then administrators can set what operations are recorded in the audit log.
Audit logging is enabled by default for the TPS, but signed audit logging is disabled. Since the TPS does not use a Java Console, TPS audit log settings are managed by clicking the Configuring Signed Audit Logging link in the Administrator Operations tab of the HTML services page.
The events that can be selected to be recorded in the audit log are listed in Table 14.9, “Events Recorded to the TPS Audit Log”.
Specifying a value in the Audit Log Signing Interval (seconds): field, controls how frequently the server flushes the buffer and writes the messages to the logs. The default value is
5 seconds.
Specifying a value in the Audit Log Signing Buffer Size (bytes, minimum 512): field, sets the maximum size of the buffer. The default value is
512 bytes.
Messages in the buffer will be flushed and written to the logs when either of the following conditions occurs:
- The buffer gets full. The buffer is full when the buffer size is equal to or greater than the value specified by the value entered into the Audit Log Signing Buffer Size (bytes, minimum 512): field.
- The flush interval for the buffer is reached. The interval is specified by the value entered into the Audit Log Signing Buffer Size (bytes, minimum 512): field.
The TPS HTML services page is
https://server.example.com:7889/tus/.
NOTE
Although audit logs for the TPS are configured in the HTML services page, they are not viewable through the HTML services page. The logs must be viewed by opening the log files directly, and the log files are only readable by members of the
pkiaudit group (or whichever group has been given auditor privileges) meaning only designated auditors.
14.3.3.2. Configuring TPS Signed Audit Logging
There are two locations for the audit logs. Regular audit logs are in
/var/lib/instance_name/logs/tps-audit.log. If signed audit logging is enabled, then the signed audit log is written to /var/lib/instance_name/logs/signedAudit/tps-audit.log.
Audit logging is enabled by default when the TPS is configured, but signed audit logging is not. Signed audit logging can be enabled in the admin services page by setting the Enable Audit Log Signing radio button to Enable.
The TPS HTML services page is
https://server.example.com:7889/tus/.
- Stop the TPS instance.
service pki-tps stop
- Edit the audit logging configuration. The log file parameters are listed in Table 14.10, “TPS Signed Audit Log Parameters”, and the auditable events are listed in Table 14.9, “Events Recorded to the TPS Audit Log”.
Example 14.8. TPS Audit Logging Config
logging.audit.buffer.size=512 logging.audit.enable=true logging.audit.filename=/var/lib/pki-tps/logs/tps-audit.log logging.audit.level=10 logging.audit.logSigning=true logging.audit.nonselectable.events=AUDIT_LOG_STARTUP,AUDIT_LOG_SHUTDOWN,LOGGING_SIGNED_AUDIT_SIGNING logging.audit.selectable.events=optional events logging.audit.selected.events=selected events logging.audit.signedAuditCertNickname=auditSigningCert cert-pki-tps logging.audit.signedAuditFilename=/var/lib/pki-tps/logs/signedAudit/tps_audit/audit
- Start the TPS instance.
service pki-tps start
Table 14.10. TPS Signed Audit Log Parameters
| Event | Description |
|---|---|
| logging.audit.logSigning | Sets whether to sign the audit log. The default value is false. |
| logging.audit.signedAuditCertNickname | Gives the nickname of the certificate in the TPS database to use to sign the audit log file. |
| logging.audit.signedAuditFilename | Gives the full path and filename of the file to use for the signed audit log file. This is set in addition to logging.audit.filename parameter for the regular audit log file location. |
| logging.audit.flush.interval | 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. |
| logging.audit.rolloverInterval | Sets 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 14.2.1.4, “Log File Rotation”. |
NOTE
If the partition the TPS audit log is being written to becomes full, the TPS subsystem is unable to write to the logs and shuts down. The TPS subsystem will not restart until the condition has been addressed. Rotating and archiving the audit log files to another partition can help prevent the TPS from shutting down due to a full partition which cannot be written to. As such, rotating and archiving the log files, while not required, is recommended. For more information about log file rotation, see Section 14.2.1.4, “Log File Rotation”. The parameters for rotating log files are covered in Table 14.8, “TPS Logging Parameters”.
Many events can be or are required to be recorded to the audit log. Some events (such as the system startup) are listed in the
logging.audit.nonselectable.events parameter as required events, and they are always recorded in the audit log. A list of other events in the logging.audit.selectable.events parameter provide additional options that can be recorded in the audit log. All loggable events, both required and optional, are listed in Table 14.9, “Events Recorded to the TPS Audit Log”.
14.3.4. Smart Card Error Codes
Smart cards can report certain error codes to the TPS; these are recorded in the TPS's
tps-debug.log or tps-error.log files, depending on the cause for the message.
Table 14.11. Smart Card Error Codes
| Return Code | Description |
|---|---|
| General Error Codes | |
| 6400 | No specific diagnosis |
| 6700 | Wrong length in Lc |
| 6982 | Security status not satisfied |
| 6985 | Conditions of use not satisfied |
| 6a86 | Incorrect P1 P2 |
| 6d00 | Invalid instruction |
| 6e00 | Invalid class |
| Install Load Errors | |
| 6581 | Memory Failure |
| 6a80 | Incorrect parameters in data field |
| 6a84 | Not enough memory space |
| 6a88 | Referenced data not found |
| Delete Errors | |
| 6200 | Application has been logically deleted |
| 6581 | Memory failure |
| 6985 | Referenced data cannot be deleted |
| 6a88 | Referenced data not found |
| 6a82 | Application not found |
| 6a80 | Incorrect values in command data |
| Get Data Errors | |
| 6a88 | Referenced data not found |
| Get Status Errors | |
| 6310 | More data available |
| 6a88 | Referenced data not found |
| 6a80 | Incorrect values in command data |
| Load Errors | |
| 6581 | Memory failure |
| 6a84 | Not enough memory space |
| 6a86 | Incorrect P1/P2 |
| 6985 | Conditions of use not satisfied |