[[syslog]]
= Syslog Support

Spring Integration 2.2 introduced the syslog transformer: `SyslogToMapTransformer`.

You need to include this dependency into your project:

[tabs]
======
Maven::
+
[source, xml, subs="normal", role="primary"]
----
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-syslog</artifactId>
    <version>{project-version}</version>
</dependency>
----

Gradle::
+
[source, groovy, subs="normal", role="secondary"]
----
compile "org.springframework.integration:spring-integration-syslog:{project-version}"
----
======

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 that contains 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 https://tools.ietf.org/html/rfc5424[RFC 5424>].
In addition, when using TCP and RFC5424, both `octet counting` and `non-transparent framing` described in https://tools.ietf.org/html/rfc6587[RFC 6587] are supported.

[[syslog-inbound-adapter]]
== 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 and are prefixed with `syslog_`.
In this mode, only https://tools.ietf.org/html/rfc3164[RFC 3164] (BSD) syslogs are supported.

Since version 4.1, the `DefaultMessageConverter` has a property called `asMap` (the default is `true`).
When it is `false`, the converter leaves 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, by 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: To use RFC 5424 with a TCP transport, you must provide additional configuration to enable the different framing techniques described in RFC 6587.
The adapter needs a TCP connection factory that is configured with a `RFC6587SyslogDeserializer`.
By default, this deserializer handles `octet counting` and `non-transparent framing` by 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`.

[[syslog-inbound-examplers]]
=== Example Configuration

The following example defines a `UDP` adapter that sends messages to the `syslogIn` channel (the adapter bean name is `syslogIn.adapter`):

[source,xml]
----
<int-syslog:inbound-channel-adapter id="syslogIn" port="1514" />
----

The adapter listens on port `1514`.

The following example defines a `UDP` adapter that sends messages to the `fromSyslog` channel (the adapter bean name is `syslogIn`):

[source,xml]
----
<int-syslog:inbound-channel-adapter id="syslogIn"
	channel="fromSyslog" port="1514" />
----

The adapter listens on port `1514`.

The following example defines a `TCP` adapter that sends messages to channel `syslogIn` (the adapter bean name is `syslogIn.adapter`):

[source,xml]
----
<int-syslog:inbound-channel-adapter id="bar" protocol="tcp" port="1514" />
----

The adapter listens on port `1514`.

Note the addition of the `protocol` attribute.
This attribute can contain `udp` or `tcp`.
It defaults to `udp`.

The following example shows a `UDP` adapter that sends messages to channel `fromSyslog`:

[source,xml]
----
<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>
----

The preceding example also shows two `SmartLifecycle` attributes: `auto-startup` and `phase`.
It has a reference to a custom `org.springframework.integration.syslog.MessageConverter` with an ID of `converter` and an `error-channel`.
Also notice the `udp-attributes` child element.
You can set various UDP attributes here, as defined in xref:ip/endpoint-reference.adoc#ip-udp-ib-atts[.UDP Inbound Channel Adapter Attributes].

NOTE: When you use the `udp-attributes` element, you must provide the `port` attribute there rather than on the `inbound-channel-adapter` element itself.

The following example shows a `TCP` adapter that sends messages to channel `fromSyslog`:

[source,xml]
----
<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" />
----

It also shows how to reference an externally defined connection factory, which can be used for advanced configuration (socket keep-alive and other uses).
For more information, see xref:ip/tcp-connection-factories.adoc[TCP Connection Factories].

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.

The following example shows a `TCP` adapter that sends messages to channel `fromSyslog`:

[source,xml]
----
<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" />
----

The preceding example 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).
