Skip to content

docs pipeline: outputs: syslog: document DTLS transport mode #2643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
patrick-stephens merged 2 commits into from
Aug 7, 2026
Merged

docs pipeline: outputs: syslog: document DTLS transport mode #2643

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3e9e4a6
docs: pipeline: outputs: syslog: document DTLS transport mode
eschabell Aug 1, 2026
5724de0
docs: docs: pipeline: outputs: syslog: correct TLS mode behavior
eschabell Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 65 additions & 2 deletions pipeline/outputs/syslog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Syslog

The _Syslog_ output plugin lets you deliver messages to Syslog servers. It supports RFC3164 and RFC5424 formats through different transports such as UDP, TCP, or TLS.
The _Syslog_ output plugin lets you deliver messages to Syslog servers. It supports RFC3164 and RFC5424 formats over UDP, TCP, TLS, and Datagram Transport Layer Security (DTLS) transports.

## Configuration parameters

| Key | Description | Default |
| --- | ----------- | ------- |
| `allow_longer_sd_id` | If `true`, Fluent Bit allows SD-ID values longer than 32 characters. SD-ID values that exceed 32 characters violate RFC5424 standards. | `false` |
| `host` | Domain or IP address of the remote Syslog server. | `127.0.0.1` |
| `mode` | Desired transport type. Available options are `tcp` and `udp`. To use a TLS secure channel, set this to `tcp` and enable the `tls` option separately. Datagram Transport Layer Security (DTLS) over UDP isn't supported. | `udp` |
| `mode` | Desired transport type. Available options are `udp`, `tcp`, `tls`, and `dtls`. See [Transport modes](#transport-modes). | `udp` |
| `port` | TCP or UDP port of the remote Syslog server. | `514` |
| `syslog_appname_key` | Optional. The key name from the original record that contains the application name that generated the message. | _none_ |
| `syslog_appname_preset` | Optional. The preset application name. It will be overwritten if `syslog_appname_key` is set and a key of a record is matched. | _none_ |
Expand All @@ -28,10 +28,32 @@ The _Syslog_ output plugin lets you deliver messages to Syslog servers. It suppo
| `syslog_severity_preset` | Optional. The preset severity number. It will be overwritten if `syslog_severity_key` is set and a key of a record is matched. | `6` |
| `workers` | The number of [workers](../../administration/multithreading.md#outputs) to perform flush operations for this output. | `0` |

### Transport modes

The `mode` parameter selects the transport used to reach the Syslog server:

| Mode | Transport | `tls` setting |
| --- | --- | --- |
| `udp` | Datagrams. | Must remain `off`. |
| `tcp` | Stream. Set `tls` to `on` to secure the connection. | Optional. |
| `tls` | Stream secured with TLS. | Optional. Enabled automatically. |
| `dtls` | Datagrams secured with DTLS. | Optional. Enabled automatically. |

Setting `mode` to `tls` or `dtls` enables TLS automatically, so you don't need to set `tls` to `on` for those modes. Setting it explicitly is harmless. To secure a `tcp` connection, you must set `tls` to `on`.

Fluent Bit validates the configuration at startup and refuses to start in these cases:

- `mode` set to `udp` with `tls` set to `on` fails with `mode=udp with tls=on is unsupported`. Use `dtls` instead, which is the supported way to secure datagram transport.
- `mode` set to `tls` or `dtls` in a build compiled without TLS support fails with `TLS support is unavailable`.

DTLS support is available in Fluent Bit version 5.1 and greater. Earlier versions support only `udp`, `tcp`, and `tls`.

### TLS / SSL

The Syslog output plugin supports TLS/SSL. For more details about the properties available and general configuration, see [TLS/SSL](../../administration/transport-security.md).

The same TLS properties apply to `dtls` mode, including `tls.verify`, `tls.ca_file`, `tls.crt_file`, and `tls.key_file`.

## Examples

### Configuration file
Expand Down Expand Up @@ -87,6 +109,47 @@ pipeline:
{% endtab %}
{% endtabs %}

### Secure datagram transport with DTLS

To send messages over DTLS, set `mode` to `dtls`. The Syslog server must listen for DTLS on the configured port:

{% tabs %}
{% tab title="fluent-bit.yaml" %}

```yaml
pipeline:

outputs:
- name: syslog
match: "*"
host: syslog.yourserver.com
port: 6514
mode: dtls
tls.verify: on
tls.ca_file: /path/to/ca.crt
syslog_format: rfc5424
syslog_message_key: message
```

{% endtab %}
{% tab title="fluent-bit.conf" %}

```text
[OUTPUT]
Name syslog
Match *
Host syslog.yourserver.com
Port 6514
Mode dtls
Tls.verify on
Tls.ca_file /path/to/ca.crt
Syslog_Format rfc5424
Syslog_Message_Key message
```

{% endtab %}
{% endtabs %}

### Structured data

The following is an example of how to configure the `syslog_sd_key` to send Structured Data to the remote Syslog server.
Expand Down