Logging configuration
The tracing facility of nevisAuth depends on the deployment "). Tracing is configured using the following command:
# nevisauth default config log
Automatic reloading of logging configuration
nevisAuth supports runtime reconfiguration of the logging subsystem(https://logging.apache.org/log4j/2.x/manual/configuration.html#ConfigurationSyntax).
monitorInterval: 60
Logging layout patterns
The pattern of each in
RollingFile:
- name: "SERVER"
fileName: "log/esauth4sv.log"
filePattern: "log/esauth4sv.log.%i"
PatternLayout:
Pattern: "%d{ISO8601} %-15.15t %12X{conversationId}-%X{transferId} %-20.20c %-5.5p %X{indent}%m%n"
Policies:
SizeBasedTriggeringPolicy:
size: "10 MB"
DefaultRollOverStrategy:
max: 9
The above example will prefix log lines with (in that order):
- a date/time timestamp (%d),
- the thread name (%t),
- the conversation ID (%X{conversationId}),
- the trace group (%c)
- the priority of the trace message (%p).
It will also indent traces (%X{indent}).
nevisAuth places several signature values in log4j's MDC context (J2EE deployment). The values can be accessed in the ConversionPattern using the %X{...} syntax:
- clientAddress: Address (IP) of the client
- clientId: ID of the client, as transmitted by nevisProxy
- conversationId: Unique identifier of the authentication conversation
- currentResource: URL of current request
- resource: URL of original request that triggered the authentication operation
- domain: Domain (Realm) of the authentication
- indent: Indentation of the log message
Important trace groups
The following table lists the most important general trace groups, in combination with relevant debugging use cases:
| Use case | Log4j Category example |
|---|---|
| Full trace analysis (debugging in test environment only) | Root: level: DEBUG AppenderRef: ref: SERVER |
| Operational analysis including overall processing duration and total memory usage (for production systems) | - name: jcan.Op level: INFO |
| Performance report, one per request | - name: AuthPerf level: INFO |
| Analyzing the state processing workflow | - name: AuthEngine level: INFO |
| Analyzing the state processing workflow in detail (verbose) | - name: AuthEngine level: DEBUG |
| Variable and expression hand-ling | - name: Vars level: INFO |
| Periodic report of session management (for productive systems) | - name: Store level: INFO |
| Analyzing session lifecycle in detail (verbose) | - name: SessCoord level: DEBUG |
| Low level debugging | - name: org.eclipse.jetty level: DEBUG |
| Auditing (should always be enabled) | - name: ch.nevis.esauth.util.audit level: TRACE additivity: false AppenderRef: - ref: AUDIT |
For all logging groups and their description, see the log4j configuration of your instance. For more examples, check the default configuration template here: /opt/nevisauth/template/conf/logging.yml
For processing details of the corresponding authentication plug-in, see the "Logging" section of the corresponding AuthState.Syslog
You may forward log messages to a local or remote syslog host by configuring a dedicated appender. This can replace the existing file appenders, or it can be configured in addition to them.
The original SyslogAppender delivered with log4j2 have the following limitations regarding formatting:
- If you use RFC 5424 formatting, the implementation does not allow the prefixing of logs. Prefixes are used in Nevis setups to decode the component, log file, or instance information.
- If you do not use RFC 5424 formatting, messages are truncated to a maximum length of 1024 bytes. This is due to the message size limit of 1024 bytes defined in RFC 5424.
To work around these limitations, you can use the(https://logging.apache.org/log4j/log4j-2.0/manual/appenders.html#SocketAppender). However, SocketAppender does not allow the configuration of the facility to be set to LOCAL3. The following points help you apply the workaround despite this limitation:
- The facility is a prefix on the message in the format of
<code>, that is decoded by syslog to a facility. You can add the facility by mapping all log levels to the same facility. - Note that each log severity needs a different code for the same facility. The mapping grid can be found(https://techdocs.broadcom.com/us/en/symantec-security-software/identity-security/privileged-access-manager/4-0/reference/messages-and-log-formats/syslog-message-formats/syslog-priority-facility-severity-grid.html).
- To send all log levels to LOCAL3, you need to define the following in the beginning of the message:
<%level{TRACE=159, DEBUG=159, INFO=158, WARN=156, ERROR=155, FATAL=153}>
Sample code:
Configuration:
monitorInterval: 60
Appenders:
Socket:
- name: "SYSLOG_AUDIT"
host: "localhost"
port: "514"
protocol: "UDP"
ThresholdFilter:
level: "INFO"
onMatch: "ACCEPT"
onMismatch: "DENY"
PatternLayout:
pattern: "<%level{TRACE=159, DEBUG=159, INFO=158, WARN=156, ERROR=155, FATAL=153}>nevisAuth/audit/default: %d{ISO8601} %15.15t %12X{conversationId}%X{transferId} %-20.20c %-5.5p %X{indent}%m%n"
...
- name: ch.nevis.esauth.util.audit
level: TRACE
additivity: false
AppenderRef:
- ref: AUDIT
- ref: SYSLOG_AUDIT