Logging in Protocol Gateway

This article includes updates for CM 8.11.

Protocol Gateway logs to two different types of logs: trace logs and message dump logs. Logging is mainly configured in <configroot>/conf/logging.properties.

<configroot> corresponds to the following paths:

Windows <configroot>

CODE

%ALLUSERSPROFILE%/Nexus/cm-gateway/

Linux <configroot>

CODE

/var/cm-gateway/

Log File Locations

Log files are normally stored under the <var>/logs which resolves to:

/var/cm-gateway/logs on Linux
%ALLUSERSPROFILE%/Nexus/cm-gateway/logs on Windows

Log Settings

The server logging is based on the Java logging subsystem which uses the concepts of Loggers and Handlers. Loggers are the sources of log records to which the server application append log entries. A logger forwards log entries to a handler which is responsible for outputting the message to some log target such as text file. A handler configuration also defines the log target location, output format etc. Also, every log record is logged on a specific level and log records may be dropped by a logger or handler based on configured level.

A logger is defined with a level and the handler(s) to which the logger forwards events. Parameters are optionally prefixed with the logger name, for example the logger named com.nexusgroup can be configured as follows:

CODE

com.nexusgroup.level = FINE
.handlers = 1log.org.apache.juli.FileHandler

A handler is defined with a formatter, level and optionally handler specific parameters. Parameters are prefixed with the handler class name. For example, a file handler is defined as follows:

CODE

# File that rolls over each day
1log.org.apache.juli.FileHandler.directory = ${nexus.var}/logs
1log.org.apache.juli.FileHandler.rotatable = true
1log.org.apache.juli.FileHandler.prefix = trace-
1log.org.apache.juli.FileHandler.level = FINEST
1log.org.apache.juli.FileHandler.formatter = java.util.logging.SimpleFormatter
1log.org.apache.juli.FileHandler.encoding = ISO-8859-1

The formatter specifies the log record format, for example:

CODE

# <date> <time> <level>: <message><exception>
java.util.logging.SimpleFormatter.format = %1$tF %1$tT.%1$tL %4$s: %5$s%6$s%n

By default the error log (or “trace” log) logs possible errors and operational information. The error log logs through the file handler 1log.org.apache.juli.FileHandler.

The second log is created if the system encounters an error, that must be properly diagnosed. For this purpose there is a memory handler java.util.logging.MemoryHandler, that keeps all log records, up to the specified size and above the specified level, and writes them to a file when a trigger log is logged.

Changing the Log Level

Normally the log level is changed by changing the handler level parameter. But the level can be controlled also per logger. Log levels used in the product are:

SEVERE: Entries that may cause the server to stop responding are logged on this level.
WARNING: Log entries on this level indicate to the administrator that system adjustments might be needed.
INFO: Informative entries, mainly outputted during startup and shutdown.
FINE: Debug information entries.
FINER: Finer-grade debug information.
FINEST: The finest grade of debug information.

Changing log levels is only relevant for the error log. The level is changed by changing the level parameter of the trace handler.

Example: Enabling Trace Logging

To get the most comprehensive information to be logged into trace.log, set the following property in logging.properties:

CODE

.level = FINEST

Or to get a full trace for only a specific protocol:

CODE

com.nexussafe.cm.pgwy.scep.level = FINEST

Message dump logs

Protocol Gateway is able to dump the raw requests, responses and for some use cases (EST and SCEP) some message data into files on the file system. This is enabled by configuring the parameter dumpDir in cm-gateway.properties to point at some directory on the file system where the logs shall be stored, and setting the log level of the protocol logger (for example com.nexussafe.cm.pgwy.acme.level) to CONFIG or lower in logging.properties.

Masking Personal Data In Logs

If the data that is being processed by Protocol Gateway contains personal data, such as names or otherwise sensitive information about persons, this data might be affected by the EU General Data Protection Regulation (GDPR). In standard PGW configuration, the operational logs will contain data such as "common name" of issued certificates, which could be considered sensitive in some use-cases.

In order to comply with GDPR, Protocol Gateway can be configured to not log personal data in its operational log files. This is done by enabling the following configuration option in cmgateway.properties:

CODE

hidePersonalDataInLogs = true

The effect of enabling the above configuration option is as follows:

CMC requests will not log the signer of the requests in the operational log, since this data could contain the signer's subject.
SCEP certificates will not be logged in the operational log, since the certificate details could include the certificate subject.
Certificates that are issued via certificate formats that use the TokenRequestCaller -modifier, will not be logged in the operational log, since the certificate details could include the certificate subject.

When enabling this option, also remember to update the configuration option com.nexussafe.cm.pgwy.subject in logging.properties so that it does not include personal data such as cn (Common Name).

Show CM Domain in Logs

To enable logging in CM REST API requests of the CM domain which an officer belongs to, the following configuration option can be enabled in api.properties:

CODE

default.showDomainInLogs= true

When enabled it will add a domain="<value>" parameter into the Protocol Gateway logs, which then can be used to filter out logs based on the domain value.