---
id: network--udp-server-plugin
title: "UDP server"
summary: "Listens on a UDP port and emits every received datagram as a `UdpDatagram` record. Use it to receive telemetry, syslog-style messages or device notifications sent over UDP. The component keeps the flow running."
audience: user
keywords: "start, output, port, workercount, maxoutstandingrequests, receivebuffersize"
---
# UDP server

Listens on a UDP port and emits every received datagram as a `UdpDatagram` record. Use it to receive telemetry, syslog-style messages or device notifications sent over UDP. The component keeps the flow running.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Start | start | any | Starts the server. When unconnected, the server starts with the flow. |
| Output | output | `Viaducta.Plugins.UdpTypes.UdpDatagram` | One record per received datagram, with new metadata. |

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `Port` | integer (1-65535) | `7000` | Required. UDP port to listen on (all local interfaces). |
| `WorkerCount` | integer (1-255) | `1` | Intended number of parallel workers for `Output` (see Notes). |
| `MaxOutstandingRequests` | integer | `0` | Maximum number of received datagrams waiting for processing; `0` = unlimited. When the limit is reached, new datagrams are dropped. |
| `ReceiveBufferSize` | integer (KB, 8-2048) | `64` | Socket receive buffer. Increase it for bursts, otherwise the OS drops datagrams. |

## Behaviour

- The server binds `Port` on all interfaces, either when the flow starts (`Start` unconnected) or when `Start` is called.
- Received datagrams are put into an internal in-memory queue and dispatched to `Output` one by one as `UdpDatagram` with `IP` and `Port` of the sender and `Data` (the payload bytes). Each datagram gets new metadata.
- If `Output` has no connections, received datagrams are discarded.
- When the queue holds `MaxOutstandingRequests` items, further datagrams are silently dropped until it drains.
- The socket is closed and the queue cleared when the flow stops.

## Notes

- `WorkerCount` has no effect: the dispatcher calls `Output` synchronously from a single thread, so datagrams are always processed one at a time. To process in parallel, hand them to an asynchronous component (for example a queue) right after the server.
- There is no reply pin; to answer a sender, use a UDP client with its address and port.
- The `MaxOutstandingRequests` field validator has a minimum of `1`, although `0` (unlimited) is the default and is accepted by the code.
- Calling `Start` a second time tries to bind the port again and fails; trigger it only once.
- Datagrams waiting in the queue are lost when the flow stops.

## Example

```json
{ "Port": 5140, "WorkerCount": 1, "MaxOutstandingRequests": 10000, "ReceiveBufferSize": 512 }
```

**UDP server** → (decode `Data` to text) → Bulk insert