4bb23e2e6e
* INT-4459: Mention dependencies in the Docs JIRA: https://jira.spring.io/browse/INT-4459 * Explicitly say what Spring Integration dependency must be included into the target project for particular protocol components * * Fix code block wrapping in the `endpoint-summary.adoc`
164 lines
6.4 KiB
Plaintext
164 lines
6.4 KiB
Plaintext
[[syslog]]
|
|
== Syslog Support
|
|
|
|
Spring Integration 2.2 introduced the syslog transformer: `SyslogToMapTransformer`.
|
|
|
|
You need to include this dependency into your project:
|
|
|
|
====
|
|
.Maven
|
|
[source, xml, subs="normal"]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.integration</groupId>
|
|
<artifactId>spring-integration-syslog</artifactId>
|
|
<version>{project-version}</version>
|
|
</dependency>
|
|
----
|
|
|
|
.Gradle
|
|
[source, groovy, subs="normal"]
|
|
----
|
|
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 <<ip-udp-ib-atts>>.
|
|
|
|
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 <<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).
|