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

* 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 <eric@schabell.org>

* 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 <eric@schabell.org>

---------

Signed-off-by: Eric D. Schabell <eric@schabell.org>
Signed-off-by: Patrick Stephens <pat@telemetryforge.io>

Author: eschabell

pipeline/outputs/syslog.md

@@ -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_ |
@@ -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
@@ -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.