---
title: Syslog
slug: telemetry-pipeline/syslog
docTags: 
createdAt: 2025-04-21T00:48:04.292Z
---

## Syslog Source

Collect log events sent using the **Syslog protocol** over TCP, UDP, or Unix Domain Sockets (UDS).
 This source is commonly used to ingest logs from network devices, operating systems, appliances, and legacy applications that emit Syslog-formatted messages.

It can operate both as a **central aggregator** and as a **sidecar** component.

## Collection Model

- Listens for incoming Syslog messages on a socket 
- Supports **TCP**, **UDP**, and **Unix Domain Sockets** 
- Parses incoming messages and forwards them immediately downstream 
- Designed for low-latency ingestion rather than guaranteed delivery 

This source does not provide backpressure or retry guarantees.

## Transport Modes

### TCP

- Connection-oriented 
- Supports TLS encryption 
- Allows connection limits and origin filtering 
- Suitable for reliable network-based log shipping 

### UDP

- Connectionless and lightweight 
- No delivery guarantees 
- Best suited for high-throughput or lossy environments where performance is prioritized 

### Unix Domain Socket (UDS)

- Local-only communication 
- Lowest latency and overhead 
- Suitable for sidecar or same-host integrations 

Only Unix **stream** sockets are supported.
 For Unix datagram sockets, a generic socket source should be used instead.

## Network Binding

### address (required for TCP and UDP)

Defines the socket address to listen on.

Operational notes:

- Must include a port number 
- Can also reference a socket passed via **systemd socket activation** 
- Determines where external systems send Syslog messages 

### path (required for Unix mode)

Defines the absolute filesystem path of the Unix socket.

Operational notes:

- The path must be writable by the running process 
- File permissions can be controlled separately 

## Connection Management

### connection\_limit (optional)

Limits the number of concurrent TCP connections.

Useful for:

- Protecting the process from resource exhaustion 
- Preventing unbounded client connections in aggregator deployments 

Only applies when using TCP.

### keepalive (optional)

Controls TCP keepalive behavior.

Helps detect:

- Broken connections 
- Idle clients that are no longer reachable 

Only applies to TCP-based listeners.

## Message Size Handling

### max\_length (optional)

Defines the maximum buffer size for incoming messages.

Messages exceeding this size are truncated.

This protects the system from:

- Malformed messages 
- Unexpectedly large payloads 
- Memory pressure from oversized logs 

## Source Identification

### host\_key (optional)

Defines the event field used to store the sender’s identity.

Behavior depends on transport mode:

- **TCP / UDP:** peer IP address and port 
- **Unix socket:** socket path 

If not set, the global schema’s host field is used.

## Origin Filtering

### permit\_origin (optional)

Restricts incoming TCP connections to a set of allowed IP networks.

Operational notes:

- IPs must be specified in CIDR notation 
- Only applies to TCP 
- Useful for securing aggregator endpoints exposed on a network 

## Socket Buffering

### receive\_buffer\_bytes (optional)

Controls the size of the socket receive buffer.

In most cases, the default value is sufficient and should not be modified.

Applies to both TCP and UDP.

## Unix Socket Permissions

### socket\_file\_mode (optional)

Defines filesystem permissions for the Unix socket file.

This controls which users or processes are allowed to write logs to the socket.

Only relevant when using Unix Domain Sockets.

## TLS Support

TLS can be enabled to secure Syslog traffic, primarily for TCP-based deployments.

### TLS Enablement

When TLS is enabled:

- Incoming connections are encrypted 
- The server presents an identity certificate 
- Client certificates can optionally be required and verified 

### Certificate Configuration

TLS configuration supports:

- Server certificate and private key 
- Optional passphrase for encrypted keys 
- Custom Certificate Authority bundles 
- Inline or file-based certificate material 

### Client Identity Metadata

### tls.client\_metadata\_key (optional)

Defines the event field where client certificate metadata is stored.

This enables:

- Attribution of logs to authenticated clients 
- Auditing and trust-based routing decisions downstream 

### Verification Controls

- **verify\_certificate:** Enforces certificate chain validation 
- **verify\_hostname:** Validates hostname against the certificate (outgoing only) 

Disabling verification weakens security and should only be done with full understanding of the risks.

## ALPN Support

### tls.alpn\_protocols (optional)

Defines supported ALPN protocols during TLS negotiation.

Protocols are prioritized in the order they are declared.

## Reliability Semantics

- Messages are processed on a **best-effort basis** 
- No acknowledgements or retries 
- Data loss is possible during: 
  - Network interruptions 
  - Process restarts 
  - Buffer overflows 

This design favors throughput and simplicity over guaranteed delivery.

## Common Use Cases

- Central Syslog collector for network devices 
- Log ingestion from firewalls, routers, and appliances 
- Sidecar-based local Syslog receivers 
- Migration from traditional Syslog servers to modern telemetry pipelines 
- Feeding SIEM, log analytics, or long-term storage system