Introduction

• It is common practice to send log output to a syslog server, for example, to integrate with IBM QRadar® SIEM:
  • this can happen in addition to writing individual log files and
  • can happen instead of using individual log files.
• The syslog server can be located on the host where JS7 products are operated and it can be located on an arbitrary host in the user's network.
• It is assumed that readers are familiar with the JS7 - Log Files and Locations and JS7 - Log Rotation article.

Syslog Configuration

JS7 uses Log4j2 which uses a Syslog Appender to forward log output. The required configuration can be applied to a log4j2.xml file which can be created from an example that is available in the JETTY_BASE/resources/joc directory. The syslog configuration could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    ...
	<Appenders>
        ...
        <Syslog name="AuditSyslogAppender" format="RFC5424" host="localhost" port="514"
            protocol="UDP" appName="JS7" includeMDC="true"
            facility="LOCAL0" enterpriseNumber="24723" newLine="true"
            messageId="Audit" id="JobScheduler"/>
        ...
    </Appenders>
    ...
    <Loggers>
        ...
		<!-- Logger for audit log -->
		<Logger name="JOCAuditLog" additivity="false" level="INFO">
			<AppenderRef ref="AuditLogAppender"/>
            <!-- Logger for syslog -->
            <AppenderRef ref="AuditSyslogAppender"/>
		</Logger>
        ....
    </Loggers>
    ...
</Configuration>

Explanation:

• Line 6-9: Appender
  • To the <Appenders> node add a <Syslog> element with the following attributes:
    • name: you can choose an arbitrary name that identifies the syslog appender and which is used later on when referencing the appender.
    • format: you can use BSD or RFC5424. The log format is defined by RFC5424.
    • host, port: the host and port that the syslog server is available for.
    • protocol: you can choose UDP or TCP depending on the capabilities of your log server. We strongly discourage use of TCP as this would result in blocking behavior if the syslog server is not acccessible.
    • appName: the application name can freely be chosen.
    • includeMDC: this is required to forward the content of log output.
    • facility: the value can be LOCAL0 to LOCAL7 (reserved for application logging).
    • enterpriseNumber: the above example includes the IANA private enterprise number of SOS. This value should not be changed.
    • newLine: specifies if entries to the syslog should be separated by a new line character.
    • messageId: the value can freely be chosen and works as a default to identify the structure of log output sent to the syslog server.
    • id: is an identifier for the structure of log output which works as a fallback if not specified with the messageId.
• Line 16-20: Logger
  •  In this example an existing JOCAuditLog Logger is extended:
    • the <AppenderRef ref="AuditSyslogAppender"/> element creates a reference to the syslog appender.
    • as a result, whatever output is written to the JOC Cockpit Audit Log, technically to the file audit.log. In addition it is forwarded to the syslog server.
    • the JOC Cockpit Audit Log is triggered for any changes to run-time objects such as adding or starting orders, suspending/killing orders and for any changes to the configuration such as storing, deleting or deploying objects.
  • You could add the appender reference to any other Logger such as the Root Logger.

Syslog Log Output Examples

The output found with the syslog server, e.g. in /var/log/messages, can look like this:

Nov  4 10:33:58 joc-2-0-primary JS7[49] REQUEST: ./login - USER: root - PARAMS: - - COMMENT: all - TIMESPENT: - - TICKET: -
Nov  4 10:34:20 joc-2-0-primary JS7[49] REQUEST: ./inventory/deployment/deploy - USER: root - PARAMS: {"controllerIds":["testsuite"],"auditLog":{},"store":{"draftConfigurations":[{"configuration":{"path":"/ap/apLog","objectType":"WORKFLOW"}}]}} - COMMENT: - - TIMESPENT: - - TICKET: -

Explanation:

• Line 1: Login
  • A login operation is performed by the the user account "root"
• Line 2: Deployment
  • A deploy operation is performed by the user account "root" for the given Controller and workflow.

Use with Controller and Agents

A Syslog Appender can similarly be added to Controller and Agents.

Note the JS7 - Log Rotation article that explains the Log4j2 configuration with the log4j2.xml file.