UDP

Synopsis

Creates a server that accepts network messages over UDP connections. Supports high-volume message ingestion with configurable workers and buffering options.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: udp
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    tenants:
      - tenant_id: <string>
        ip_blocks: <string[]>
    reuse: <boolean>
    workers: <numeric>
    buffer_size: <numeric>

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

Connection

Field	Required	Default	Description
address	N	"0.0.0.0"	Listen address
port	Y		Listen port

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.

Datagrams from a denied source IP are silently discarded before parsing.

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 per datagram.

Advanced Configuration

To enhance performance and achieve better event 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	9000	Network read buffer size in bytes

note

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

Examples

The following are commonly used configuration types.

Basic

Creating a minimal UDP listener using defaults for address and buffer size:

Creating a simple UDP server...

devices: - id: 1 name: basic_udp type: udp properties: port: 514

High-Volume

Optimizing for high message volumes...

devices: - id: 2 name: performant_udp type: udp properties: address: "0.0.0.0" port: 514 reuse: true workers: 4 buffer_size: 32768

note

The worker count will be automatically capped at the number of available cores.

Multiple Ports

Multiple UDP servers with different ports and independent worker pools:

Listening on multiple ports using separate configurations...

devices: - id: 3 name: udp_server_1 type: udp properties: port: 514 workers: 2 - id: 4 name: udp_server_2 type: udp properties: port: 515 workers: 2

note

When running multiple UDP servers, ensure that each configuration has a unique port number, and consider the total number of workers across all instances relative to the available system resources.

Multi-Tenant

One UDP 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 UDP listener...	devices: - id: 5 name: saas_udp type: udp 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 datagram from 10.0.0.7 is tagged with the acme tenant; the source IP is preserved...	{ "_vmetric": { "device": { "id": 5, "name": "saas_udp", "type": "udp" }, "event": { "request": "10.0.0.7", "tenant_id": "acme" } } }