Logging configuration

Automatic reloading of logging configuration

nevisAuth supports runtime reconfiguration of the logging subsystem with log4j2.

monitorInterval: 60

Logging layout patterns

The pattern of each individual line logged by log4j can be customized in the layout element of an appender. See the following example:

RollingFile:
  - name: SERVER
    fileName: "log/esauth4sv.log"
    filePattern: "log/esauth4sv.log.%i"
    PatternLayout:
      pattern: "%d{ISO8601} %-15.15t %12X{conversationId}-%X{trace_id} %X{span_id} %-20.20c %-5.5p %X{indent}%m%n"
    Policies:
      SizeBasedTriggeringPolicy:
        size: 10MB
    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 list shows the most important general trace groups, in combination with relevant debugging use cases:

• Full trace analysis (debugging in test environment only)

  Root:
    level: DEBUG
    AppenderRef:
      ref: SERVER

• Performance report, one per request

  - name: AuthPerf
    level: INFO

• Database Performance report, one per DB operation of Remote session store and Out of context data store

  - name: DbPerformance
    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 handling

  - 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

• Outgoing HTTP traffic analysis

  - name: HttpClient
    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

info

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 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 here.

• 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}>

Example

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{trace_id} %X{span_id} %-20.20c %-5.5p %X{indent}%m%n"

...

    - name: ch.nevis.esauth.util.audit
      level: TRACE
      additivity: false
      AppenderRef:
        - ref: AUDIT
        - ref: SYSLOG_AUDIT