Syslog Source Connector for Confluent Platform

You can use the Kafka Connect Syslog Source connector to consume data from network devices. Supported formats are rfc 3164, rfc 5424, and Common Event Format (CEF).

Important

The Syslog Source connector listens on a network port. Running more than one task or running in distributed mode can cause some undesired effects if another task already has the port open. Confluent recommends you run only one task and deploy the connector into a Connect cluster with a single, fixed node and hostname. This cluster can be standalone or distributed.

Features

The Syslog Source connector includes the following features:

• At least once delivery
• Supports one task

At least once delivery

This connector guarantees that records are delivered at least once to the Kafka topic. If the connector restarts, there may be some duplicate records in the Kafka topic.

Supports one task

The Syslog Source connector supports running one task.

Install the Syslog Source Connector

You can install this connector by using the confluent connect plugin install command, or by manually downloading the ZIP file.

Prerequisites

• You must install the connector on every machine where Connect will run.

• An install of the latest (latest) connector version.

  To install the latest connector version, navigate to your Confluent Platform installation directory and run the following command:

  confluent connect plugin install confluentinc/kafka-connect-syslog:latest
  

  You can install a specific version by replacing latest with a version number as shown in the following example:

  confluent connect plugin install confluentinc/kafka-connect-syslog:1.5.0
  

Install the connector manually

Download and extract the ZIP file for your connector and then follow the manual connector installation instructions.

License

You can use this connector for a 30-day trial period without a license key.

After 30 days, you must purchase a connector subscription which includes Confluent enterprise license keys to subscribers, along with enterprise-level support for Confluent Platform and your connectors. If you are a subscriber, you can contact Confluent Support at support@confluent.io for more information.

See Confluent Platform license for license properties and License topic configuration for information about the license topic.

Configuration Properties

For a complete list of configuration properties for this connector, see Configuration Reference for Syslog Source Connector for Confluent Platform.

For an example of how to get Kafka Connect connected to Confluent Cloud, see Connect Self-Managed Kafka Connect to Confluent Cloud.

Quick Start

Prerequisites

• Confluent Platform
• Confluent CLI (requires separate installation)

1. Install the connector:

   confluent connect plugin install confluentinc/kafka-connect-syslog:latest
   

2. Start Confluent Platform using the Confluent CLI confluent local commands.

   Tip

   The command syntax for the Confluent CLI development commands changed in 5.3.0. These commands have been moved to confluent local. For example, the syntax for confluent start is now confluent local services start. For more information, see confluent local.

   confluent local services connect start
   

3. Create a config file with the following contents:

   name=syslog-tcp
   tasks.max=1
   connector.class=io.confluent.connect.syslog.SyslogSourceConnector
   syslog.port=5454
   syslog.listener=TCP
   confluent.license=
   confluent.topic.bootstrap.servers=localhost:9092
   confluent.topic.replication.factor=1
   

4. Load the Syslog Connector.

   Caution

   You must include a double dash (--) between the topic name and your flag. For more information, see this post.

   confluent local services connect connector load syslog-tcp --config path/to/config.properties
   

   Important

   Don’t use the confluent local commands in production environments. Always run the Syslog connector in standalone mode, for example, with bin/connect-standalone.

5. Test with the sample syslog-formatted message sent using netcat:

   echo "<34>1 2003-10-11T22:14:15.003Z mymachine.example.com su - ID47 - Your refrigerator is running" | nc -v -w 0 localhost 5454
   

6. Confirm that the message is logged to Apache Kafka®:

   kafka-avro-console-consumer \
       --bootstrap-server localhost:9092 \
       --property schema.registry.url=http://localhost:8081 \
       --topic syslog --from-beginning | jq '.'
   

Output Schema

The Syslog Source connector accepts Syslog messages as strings, and produces structured messages as output to the configured Kafka topic.

Important

When operating in UDP mode, the Syslog Source connector will truncate messages at 2048 characters.

Record Key Schema

host

Host of the Syslog message, as specified in the message body. If no host is specified, the remote address of the message will be used.

• Type: string

Record Value Schema

Some fields are relevant for only some message types, and will be null for others.

name

String representing a human-readable and understandable description of the event. The event name should not contain information that is specifically mentioned in other fields. Used in CEF.

• Type: string

type

Type of message received (either “RFC5424”, “RFC3164”, “CEF”, or “UNKNOWN”).

• Type: string

message

The freeform message extracted from full message. “MSG” field of the Syslog spec.

• Type: string

host

Extracted host from the syslog message.

• Type: string

version

“VERSION” field of the Syslog spec.

• Type: int

level

Level as determined by “PRIORITY” field of Syslog spec.

• Type: int

tag

“TAG” field of Syslog spec

• Type: string

facility

“FACILITY” as determined by the “PRIORITY” of the Syslog spec.

• Type: int

severity

Severity of CEF messages.

• Type: string

appName

“APP-NAME” field of the Syslog spec.

• Type: string

remoteAddress

Remote address of the request received by the connector.

• Type: string

rawMessage

The full, unmodified, unparsed message as received by the connector.

• Type: string

processId

“PROCID” field of the Syslog spec.

• Type: string

messageId

“MSGID” field of the Syslog spec.

• Type: string

deviceVendor

Vendor identifier that is used to group products.

• Type: string

deviceProduct

Product identifier that is used for message logging.

• Type: string

deviceVersion

The version of the logging device product.

• Type: string

deviceEventClassId

The device event class ID. This is a unique per event-type identifier. The device event class ID identifies the type of event reported. In the intrusion detection system (IDS) world, each signature or rule that detects certain activity has a unique device event class ID assigned. This is a requirement for other types of devices as well, and helps correlation engines process the events. Also known as Signature ID.

• Type: string

extension

“Extension” mapping for the CEF message format.

• Type: map<string, string>

structuredData

“STRUCTURED-DATA” field of the Syslog spec.

• Type: Array of StructuredDatum structs:

  id: String StructuredDataElements: map<string, string>