28. Syslog Support

28.1 Introduction

Spring Integration 2.2 introduced the Syslog transformer SyslogToMapTransformer. This transformer, together with a UDP or TCP inbound adapter could be used to receive and analyze syslog records from other hosts. The transformer creates a message payload containing a map of the elements from the syslog message.

Spring Integration 3.0 introduced convenient namespace support for configuring a Syslog inbound adapter in a single element.

Starting with version 4.1.1, the framework now supports the extended Syslog format, as specified in RFC 5424>. In addition, when using TCP and RFC5424, both octet counting and non-transparent framing described in RFC 6587 are supported.

28.2 Syslog <inbound-channel-adapter>

This element encompasses a UDP or TCP inbound channel adapter and a MessageConverter to convert the Syslog message to a Spring Integration message. The DefaultMessageConverter delegates to the SyslogToMapTransformer, creating a message with its payload being the Map of Syslog fields. In addition, all fields except the message are also made available as headers in the message, prefixed with syslog_. In this mode, only RFC 3164 (BSD) syslogs are supported.

Since version 4.1, the DefaultMessageConverter has a property asMap (default true); when it is false, the converter will leave the message payload as the original complete syslog message, in a byte[], while still setting the headers.

Since version 4.1.1, RFC 5424 is also supported, using the RFC5424MessageConverter; in this case the fields are not copied as headers, unless asMap is set to false, in which case the original message is the payload and the decoded fields are headers.

[Important]Important
To use RFC 5424 with a TCP transport, additional configuration is required, to enable the different framing techniques described in RFC 6587. The adapter needs a TCP connection factory configured with a RFC6587SyslogDeserializer. By default, this deserializer will handle octet counting and non-transparent framing, using a linefeed (LF) to delimit syslog messages; it uses a ByteArrayLfSerializer when octet counting is not detected. To use different non-transparent framing, you can provide it with some other deserializer. While the deserializer can support both octet counting and non-transparent framing, only one form of the latter is supported. If asMap is false on the converter, you must set the retainOriginal constructor argument in the RFC6587SyslogDeserializer.

28.2.1 Example Configuration

<int-syslog:inbound-channel-adapter id="syslogIn" port="1514" />

A UDP adapter that sends messages to channel syslogIn (the adapter bean name is syslogIn.adapter). The adapter listens on port 1514.

<int-syslog:inbound-channel-adapter id="syslogIn"
	channel="fromSyslog" port="1514" />

A UDP adapter that sends message to channel fromSyslog (the adapter bean name is syslogIn). The adapter listens on port 1514.

<int-syslog:inbound-channel-adapter id="bar" protocol="tcp" port="1514" />

A TCP adapter that sends messages to channel syslogIn (the adapter bean name is syslogIn.adapter). The adapter listens on port 1514.

Note the addition of the protocol attribute. This attribute can contain udp or tcp; it defaults to udp.

<int-syslog:inbound-channel-adapter id="udpSyslog"
	channel="fromSyslog"
	auto-startup="false"
	phase="10000"
	converter="converter"
	send-timeout="1000"
	error-channel="errors">
		<int-syslog:udp-attributes port="1514" lookup-host="false" />
</int-syslog:inbound-channel-adapter>

A UDP adapter that sends messages to channel fromSyslog. It also shows the SmartLifecyle attributes auto-startup and phase. It has a reference to a custom org.springframework.integration.syslog.MessageConverter with id converter and an error-channel. Also notice the udp-attributes child element. You can set various UDP attributes here, as defined in Table 29.2, “UDP Inbound Channel Adapter Attributes”.

[Note]Note
When using the udp-attributes element, the port attribute must be provided there rather than on the inbound-channel-adapter element itself.
<int-syslog:inbound-channel-adapter id="TcpSyslog"
	protocol="tcp"
	channel="fromSyslog"
	connection-factory="cf" />

<int-ip:tcp-connection-factory id="cf" type="server" port="1514" />

A TCP adapter that sends messages to channel fromSyslog. It also shows how to reference an externally defined connection factory, which can be used for advanced configuration (socket keep alive etc). For more information, see Section 29.3, “TCP Connection Factories”.

[Note]Note
The externally configured connection-factory must be of type server and, the port is defined there rather than on the inbound-channel-adapter element itself.
<int-syslog:inbound-channel-adapter id="rfc5424Tcp"
	protocol="tcp"
	channel="fromSyslog"
	connection-factory="cf"
	converter="rfc5424" />

<int-ip:tcp-connection-factory id="cf"
	using-nio="true"
	type="server"
	port="1514"
	deserializer="rfc6587" />

<bean id="rfc5424" class="org.springframework.integration.syslog.RFC5424MessageConverter" />

<bean id="rfc6587" class="org.springframework.integration.syslog.inbound.RFC6587SyslogDeserializer" />

A TCP adapter that sends messages to channel fromSyslog. It is configured to use the RFC 5424 converter and is configured with a reference to an externally defined connection factory with the RFC 6587 deserializer (required for RFC 5424).