From 3e9e4a6b66bfe64f5482db050f556bbee466c4b9 Mon Sep 17 00:00:00 2001 From: "Eric D. Schabell" Date: Sat, 1 Aug 2026 11:25:47 +0200 Subject: [PATCH 1/2] docs: pipeline: outputs: syslog: document DTLS transport mode Replace the statement that DTLS isn't supported with the four available transport modes and their tls requirements, including the startup validation rules for mode=dtls and mode=udp. Note that mode=tls alone does not secure the connection, and add a DTLS configuration example. Also, clarified that TLS is not a transport. Note, covers code changes without corresponding docs PR. Signed-off-by: Eric D. Schabell --- pipeline/outputs/syslog.md | 69 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/pipeline/outputs/syslog.md b/pipeline/outputs/syslog.md index 5a5f102a8..cde0a2117 100644 --- a/pipeline/outputs/syslog.md +++ b/pipeline/outputs/syslog.md @@ -1,6 +1,6 @@ # 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, and Datagram Transport Layer Security (DTLS) transports. TLS isn't a transport of its own. Enable it to secure a TCP connection, or use `dtls` to secure datagram transport. ## Configuration parameters @@ -8,7 +8,7 @@ The _Syslog_ output plugin lets you deliver messages to Syslog servers. It suppo | --- | ----------- | ------- | | `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_ | @@ -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. Behaves the same as `tcp`. | Required to secure the connection. | +| `dtls` | Datagrams secured with DTLS. | Required. | + +Setting `mode` to `tls` doesn't secure the connection on its own. Fluent Bit selects TLS based on the `tls` parameter, so `mode: tls` without `tls: on` sends messages over a plain TCP connection. Always set `tls` to `on` when you want a secure channel. + +Fluent Bit validates these combinations at startup and refuses to start when they conflict: + +- `mode` set to `dtls` without `tls` set to `on` fails with `mode=dtls requires tls=on`. +- `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. + +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 @@ -87,6 +109,49 @@ pipeline: {% endtab %} {% endtabs %} +### Secure datagram transport with DTLS + +To send messages over DTLS, set `mode` to `dtls` and enable `tls`. 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: on + 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 on + 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. From 5724de0abdfe7128df38248c66bc0a225d6c4c25 Mon Sep 17 00:00:00 2001 From: "Eric D. Schabell" Date: Tue, 4 Aug 2026 11:10:09 +0200 Subject: [PATCH 2/2] docs: docs: pipeline: outputs: syslog: correct TLS mode behavior Upstream commit 40641ddb (out_syslog: Handle TLS mode automatically) changed how mode=tls and mode=dtls interact with the tls parameter. Both modes now enable TLS themselves, and the mode=dtls requires tls=on startup check was removed. Update the docs to match: - Intro: list UDP, TCP, TLS, and DTLS as four transports, and drop the claim that TLS isn't a transport of its own. - Transport modes table: change the tls setting for tls and dtls from required to optional and enabled automatically, and drop "behaves the same as tcp" from the tls row. - Replace the paragraph stating that mode=tls doesn't secure the connection on its own with the automatic TLS behavior. - Startup validation: remove the mode=dtls requires tls=on bullet, which no longer exists in the source, and add a bullet for builds compiled without TLS support failing with "TLS support is unavailable". - DTLS example: drop the now-redundant tls: on from both the YAML and classic configuration tabs. Signed-off-by: Eric D. Schabell --- pipeline/outputs/syslog.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/pipeline/outputs/syslog.md b/pipeline/outputs/syslog.md index cde0a2117..4b8c69224 100644 --- a/pipeline/outputs/syslog.md +++ b/pipeline/outputs/syslog.md @@ -1,6 +1,6 @@ # Syslog -The _Syslog_ output plugin lets you deliver messages to Syslog servers. It supports RFC3164 and RFC5424 formats over UDP, TCP, and Datagram Transport Layer Security (DTLS) transports. TLS isn't a transport of its own. Enable it to secure a TCP connection, or use `dtls` to secure datagram transport. +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 @@ -36,15 +36,15 @@ The `mode` parameter selects the transport used to reach the Syslog server: | --- | --- | --- | | `udp` | Datagrams. | Must remain `off`. | | `tcp` | Stream. Set `tls` to `on` to secure the connection. | Optional. | -| `tls` | Stream. Behaves the same as `tcp`. | Required to secure the connection. | -| `dtls` | Datagrams secured with DTLS. | Required. | +| `tls` | Stream secured with TLS. | Optional. Enabled automatically. | +| `dtls` | Datagrams secured with DTLS. | Optional. Enabled automatically. | -Setting `mode` to `tls` doesn't secure the connection on its own. Fluent Bit selects TLS based on the `tls` parameter, so `mode: tls` without `tls: on` sends messages over a plain TCP connection. Always set `tls` to `on` when you want a secure channel. +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 these combinations at startup and refuses to start when they conflict: +Fluent Bit validates the configuration at startup and refuses to start in these cases: -- `mode` set to `dtls` without `tls` set to `on` fails with `mode=dtls requires tls=on`. - `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`. @@ -111,7 +111,7 @@ pipeline: ### Secure datagram transport with DTLS -To send messages over DTLS, set `mode` to `dtls` and enable `tls`. The Syslog server must listen for DTLS on the configured port: +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" %} @@ -125,7 +125,6 @@ pipeline: host: syslog.yourserver.com port: 6514 mode: dtls - tls: on tls.verify: on tls.ca_file: /path/to/ca.crt syslog_format: rfc5424 @@ -142,7 +141,6 @@ pipeline: Host syslog.yourserver.com Port 6514 Mode dtls - Tls on Tls.verify on Tls.ca_file /path/to/ca.crt Syslog_Format rfc5424