syslog.md

# Syslog Support

## Syslog Support

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

You need to include this dependency into your project:

Maven

```
<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-syslog</artifactId>
    <version>5.5.9</version>
</dependency>
```

Gradle

```
compile "org.springframework.integration:spring-integration-syslog:5.5.9"
```

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

### 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 [RFC 3164](https://tools.ietf.org/html/rfc3164) (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.

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

#### Example Configuration

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

```
<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`):

```
<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`):

```
<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`:

```
<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 [.UDP Inbound Channel Adapter Attributes](./ip.html#ip-udp-ib-atts).

|   |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`:

```
<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 [TCP Connection Factories](./ip.html#tcp-connection-factories).

|   |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`:

```
<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).