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>
    tenants:
      - tenant_id: <string>
        ip_blocks: <string[]>
    reuse: <boolean>
    workers: <numeric>
    buffer_size: <numeric>
    batch_size: <numeric>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      min_tls_version: <string>
      max_tls_version: <string>
      client_ca_name: <string>
      client_auth_required: <boolean>
      insecure_skip_verify: <boolean>

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`
`tags`	N	-	Optional tags
`pipelines`	N	-	Optional pre-processor pipelines
`status`	N	`true`	Enable/disable the device

Protocol

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

note

delimiter, octet, regex, and advanced are the canonical framing modes. In the GUI, the Framing dropdown labels octet-counting as RFC6587, which writes framing: rfc6587. Syslog transport labels are also accepted as aliases and normalized on load:

Alias	Canonical mode
`rfc6587`, `rfc5425`, `rfc5424`	`octet`
`rfc3195`	`delimiter`

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*	`cert.pem`	TLS certificate
`tls.key_name`	Y*	`key.pem`	TLS private key
`tls.passphrase`	N	-	Passphrase for an encrypted private key
`tls.min_tls_version`	N	`tls1.2`	Minimum accepted TLS version (`tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`)
`tls.max_tls_version`	N	-	Maximum accepted TLS version. When unset, the highest mutually supported version is negotiated.
`tls.client_ca_name`	N	-	CA bundle used to verify client certificates (mTLS)
`tls.client_auth_required`	N**	`false`	Require connecting clients to present a valid certificate. When `false`, a client certificate is verified only if one is presented.
`tls.insecure_skip_verify`	N	`false`	Skip peer certificate verification. Use only for testing.

* = Required when tls.status is true.

** = Requires tls.client_ca_name. If tls.client_auth_required is true or tls.client_ca_name is set and the named CA cannot be loaded, the configuration is rejected and the device fails to start.

note

tls.min_version is a deprecated alias for tls.min_tls_version, honored only when tls.min_tls_version is unset. Use tls.min_tls_version in new configurations.

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
Inline PEM content — used verbatim when the value contains -----BEGIN.
Environment variable — ${ENV_VAR}.
Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

Access List

The access_list property is a source-IP firewall: an ordered list of accept/drop rules over IP blocks, evaluated before the listener parses or authenticates the connection. When it is not set, the firewall is off and adds no overhead.

Field	Required	Default	Description
`access_list`	N	-	Ordered list of source-IP rules. Omit to disable the firewall.
`access_list[].action`	Y		`accept` or `drop` (synonyms: `allow`/`permit` and `deny`/`reject`/`block`). Unrecognized actions are ignored.
`access_list[].ip_blocks`	Y		One or more IP blocks the rule matches. Comma-separated string or a list. Accepts CIDR (`10.0.0.0/24`), single IP (`172.16.5.10`), dotted-netmask (`192.168.1.0/255.255.255.0`, IPv4 only), and inclusive range (`10.5.0.1-10.5.0.50`). IPv4 and IPv6.
`access_list_default`	N	auto	Verdict for a source IP that matches no rule: `accept` or `drop`. When omitted, it is derived automatically (see below).

Rules are evaluated top to bottom and the first rule whose blocks contain the source IP decides the outcome. A source IP that matches no rule follows the default policy:

If any accept rule is present, the list is treated as an allowlist and unmatched IPs are dropped.
Otherwise the list is treated as a denylist and unmatched IPs are accepted.

Set access_list_default to override this. An unparseable source IP is judged by the default policy, so an allowlist fails closed.

access_list:
  - action: accept
    ip_blocks: "10.0.0.0/8, 192.168.0.0/16, 172.16.5.10"

note

Editing or removing access_list rules applies on the next configuration reconcile with no listener restart. Enabling access_list for the first time on a device that had none takes effect on the next collector restart.

When a source IP is denied, the connection is accepted and then closed immediately, before framing and before the TLS handshake.

Tenants

The tenants property maps a source IP to a tenant: an ordered list of rules matched against the connection's (or datagram's) source address before the record enters the pipeline. Multiple IP blocks can map to the same tenant, and multiple tenants are supported. When it is not set, no tenant is attached.

Field	Required	Default	Description
`tenants`	N	-	Ordered list of source-IP-to-tenant rules. Omit to disable IP-based tenancy.
`tenants[].tenant_id`	Y		Tenant identifier attached to records arriving from the matching IP blocks.
`tenants[].ip_blocks`	Y		One or more IP blocks the rule matches. Comma-separated string or a list. Accepts CIDR (`10.0.0.0/24`), single IP (`172.16.5.10`), dotted-netmask (`192.168.1.0/255.255.255.0`, IPv4 only), and inclusive range (`10.5.0.1-10.5.0.50`). IPv4 and IPv6.

Rules are evaluated top to bottom and the first rule whose blocks contain the source IP wins. A source IP that matches no rule receives no tenant — the record is still ingested. When a tenant is resolved it is written to _vmetric.event.tenant_id; the client IP always stays at _vmetric.event.request. Use _vmetric.event.tenant_id to route or isolate each customer's data downstream (see Routes).

tenants:
  - tenant_id: acme
    ip_blocks: "10.0.0.0/24, 10.1.2.3, 192.168.10.0/255.255.255.0"
  - tenant_id: globex
    ip_blocks: "10.2.0.0/16, 172.16.5.1-172.16.5.50"

note

Editing or removing tenants rules applies on the next configuration reconcile with no listener restart. Enabling tenants for the first time on a device that had none takes effect on the next collector restart.

The source IP is matched once per TCP connection.

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	CPU count	Number of worker processes when reuse is enabled. Capped at the number of physical cores.
`buffer_size`	N	`1048576`	Network read buffer size in bytes (1MB)
`batch_size`	N	`10000`	Number of messages to batch before flushing

note

flush_interval and queue.interval are Director service-level settings configured in vmetric.yml and cannot be overridden per device.

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

Creating a minimal TCP listener using defaults for address, framing, and timeout:

Creating a simple TCP server...

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

High-Volume

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

note

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

Framing

TCP server with CRLF delimiter, a 5 MB message size limit, and a 60-second idle 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

TCP server receiving multi-line events where all connections share the same event pattern, using 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

TCP server receiving multi-line events from mixed sources, using 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

Securing the TCP server with TLS encryption, connection limits, and an extended connection timeout:

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

Multi-Tenant

One TCP port serving several customers, each identified by its source network. The matched tenant_id is attached for downstream routing:

Mapping source networks to tenants on a single TCP listener...

devices:
  - id: 7
    name: saas_tcp
    type: tcp
    properties:
      port: 514
      tenants:
        - tenant_id: acme
          ip_blocks: "10.0.0.0/24"
        - tenant_id: globex
          ip_blocks: "10.2.0.0/16, 172.16.5.1-172.16.5.50"

A connection from 10.0.0.7 tags every record with the acme tenant; the source IP is preserved...

{
  "_vmetric": {
    "device": { "id": 7, "name": "saas_tcp", "type": "tcp" },
    "event": {
      "request": "10.0.0.7",
      "tenant_id": "acme"
    }
  }
}

Synopsis​

Schema​

Configuration​

Device​

Protocol​

TCP​

TLS​

Access List​

Tenants​

Advanced Configuration​

Performance​

Framing Rules​

Examples​

Basic​

High-Volume​

Framing​

Regex Framing​

Advanced Framing​

Encryption​

Multi-Tenant​

Synopsis

Schema

Configuration

Device

Protocol

TCP

TLS

Access List

Tenants

Advanced Configuration

Performance

Framing Rules

Examples

Basic

High-Volume

Framing

Regex Framing

Advanced Framing

Encryption

Multi-Tenant