TCP

Synopsis

Creates a server that accepts network messages over TCP connections. Supports both plain and TLS-encrypted connections, with configurable framing modes, connection management, and buffering options.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: tcp
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    protocol: <string>
    address: <string>
    port: <numeric>
    framing: <string>
    pattern: <string>
    line_delimiter: <string>
    framing_rules:
      - name: <string>
        condition: <string>
        pattern: <string>
        max_event_bytes: <numeric>
        min_raw_length: <numeric>
    max_connections: <numeric>
    timeout: <numeric>
    max_message_size: <numeric>
    reuse: <boolean>
    workers: <numeric>
    buffer_size: <numeric>
    batch_size: <numeric>
    queue:
      interval: <numeric>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y		Unique identifier
name	Y		Device name
description	N	-	Optional description
type	Y		Must be tcp
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
protocol	N	"tcp"	Transport protocol (must be tcp)
address	N	"0.0.0.0"	Listen address
port	Y		Listen port

TCP

Field	Required	Default	Description
framing	N	"delimiter"	Framing mode (delimiter, octet, regex, or advanced)
pattern	Y*	-	Event-breaker regex pattern; required when framing is regex
line_delimiter	N	"\n"	Line separator for delimiter framing
max_connections	N	10000	Maximum concurrent connections
timeout	N	300	Connection timeout in seconds
max_message_size	N	20971520	Maximum message size in bytes (20MB)

* = Required when framing is regex

warning

When using delimiter framing, ensure that the line_delimiter matches the client's to prevent message parsing errors.

TLS

Field	Required	Default	Description
tls.status	N	false	Enable TLS encryption
tls.cert_name	Y		TLS certificate file name (required if TLS enabled)
tls.key_name	Y		TLS private key file name (required if TLS enabled)

note

The TLS certificate and key files must be placed in the service root directory.

Advanced Configuration

To enhance performance and achieve better message handling, the following settings are used.

Performance

Field	Required	Default	Description
reuse	N	true	Enable socket address reuse
workers	N	<dynamic>	Number of worker processes when reuse is enabled
buffer_size	N	1048576	Network read buffer size in bytes (1MB)

Messages

Field	Required	Default	Description
batch_size	N	1000	Number of messages to batch before processing
queue.interval	N	1	Queue processing interval in seconds

Framing Rules

Ordered event-breaking rules for TCP connections, used when framing is set to advanced.

At connection open, the first min_raw_length bytes are buffered. The first rule whose condition matches the buffered bytes is selected for the lifetime of that connection. The last rule should have an empty condition to act as the unconditional fallback. All rules use regex-based event breaking.

Field	Required	Default	Description
framing_rules[].name	N	"rule-N"	Descriptive rule name for logs
framing_rules[].condition	N	-	Regex matched against initial bytes to select this rule; empty = unconditional
framing_rules[].pattern	Y	-	Event-breaker regex marking the start of each event
framing_rules[].max_event_bytes	N	max_message_size	Per-rule event size cap in bytes; falls back to device-level max_message_size
framing_rules[].min_raw_length	N	256	Minimum bytes to buffer before evaluating condition

note

Regex framing is event-start oriented: each regex match marks the beginning of a new event. Everything between consecutive matches is one complete event. The pattern must not match the empty string.

Examples

The following are commonly used configuration types.

Basic

A basic server can be easily created using "tcp" for protocol, "0.0.0.0" for address, and the default framing and timeout settings.

Creating a simple TCP server...

devices: - id: 1 name: basic_tcp type: tcp properties: port: 514

High-Volume

Performance can be enhanced using multiple workers, a larger buffer size (e.g. 4MB), a higher connection limit, and optimized batches.

Optimizing for high message volumes...

devices: - id: 2 name: performant_tcp type: tcp properties: port: 514 reuse: true workers: 4 buffer_size: 4194304 max_connections: 20000 batch_size: 5000 queue: interval: 2

note

The worker count is automatically capped at the number of physical cores available on the system.

Framing

A custom framing can be achieved using CRLF (i.e. "\r\n") as the message delimiter, a 5MB message size limit, and 1min connection timeout.

TCP server with custom message framing...

devices: - id: 3 name: framed_tcp type: tcp properties: port: 1514 framing: delimiter line_delimiter: "\r\n" max_message_size: 5242880 timeout: 60

Regex Framing

For a TCP server receiving multi-line events where all connections share the same event pattern, use framing: regex with a top-level pattern:

TCP server with regex event breaking on ISO timestamps...

devices: - id: 5 name: regex_tcp type: tcp properties: port: 1514 framing: regex pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}"

Advanced Framing

For a TCP server receiving multi-line events from mixed sources, use framing: advanced with framing_rules to select the event-breaking pattern per connection based on the initial bytes:

TCP server with per-connection event-breaking rules...

devices: - id: 6 name: advanced_tcp type: tcp properties: port: 1514 framing: advanced framing_rules: - name: multiline-timestamp condition: "^\\d{4}-" pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}" - name: fallback pattern: "\\n"

Encryption

Security can be enhanced using TLS encryption, a custom certificate and key, connection limits, and an extended timeout the TLS handshake.

Securing TCP server with TLS encryption...

devices: - id: 4 name: secure_tcp type: tcp properties: port: 6514 tls: status: true cert_name: cert.pem key_name: key.pem max_connections: 5000 timeout: 120