From b1e35d29b9aae651c39240fa4fab56fe1936939f Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Wed, 5 Aug 2026 18:12:42 -0400 Subject: [PATCH 1/2] Document syslog_output protocol, TLS options, and size limits. Describe TCP/TLS config for ossec-csyslogd and note that TCP/TLS avoid UDP MTU truncation while remaining capped by the assemble buffer. --- docs/manual/output/syslog-output.rst | 33 +++++++++++++++++ docs/syntax/ossec_config.syslog_output.trst | 40 ++++++++++++++++++++- 2 files changed, 72 insertions(+), 1 deletion(-) diff --git a/docs/manual/output/syslog-output.rst b/docs/manual/output/syslog-output.rst index ca488d7d..ca5eef48 100644 --- a/docs/manual/output/syslog-output.rst +++ b/docs/manual/output/syslog-output.rst @@ -80,4 +80,37 @@ rule, location and the actual event that generated it): srcip: 192.168.2.190; user: root; Jul 25 13:26:24 slacker sshd[20440]: Accepted password for root from 192.168.2.190 port 49737 ssh2 +TCP and TLS +----------- + +By default ``ossec-csyslogd`` still uses UDP. Set ``protocol`` to ``tcp`` for a +persistent stream with newline framing (RFC 6587 non-transparent). Enable TLS with +``tls`` (implies TCP; requires an OpenSSL-enabled build). Optional ``tls_ca`` and +``tls_verify`` control certificate validation (same idea as SMTP TLS in maild). + +.. code-block:: xml + + + siem.example.com + 6514 + tcp + yes + yes + json + + + +Message size limits +------------------- + +``ossec-csyslogd`` builds each forwarded alert (default, CEF, JSON, or Splunk format) +into a fixed buffer of ``OS_MAXSTR`` bytes (6144). Longer alert bodies are truncated +with a trailing ``...``. Earlier releases used a 2048-byte buffer, which commonly +cut off CEF ``msg=`` fields around 2–3 KB (#1762). + +**UDP** (default) may still fragment or drop large datagrams on the network path +even when OSSEC emits the full buffer. **TCP** and **TLS** avoid UDP MTU truncation +for those payloads (still capped at the 6K assemble buffer). + + .. include:: ../../examples/output/syslog_output_examples.trst diff --git a/docs/syntax/ossec_config.syslog_output.trst b/docs/syntax/ossec_config.syslog_output.trst index 8eb21c98..0856e73f 100644 --- a/docs/syntax/ossec_config.syslog_output.trst +++ b/docs/syntax/ossec_config.syslog_output.trst @@ -22,7 +22,45 @@ - Minimum alert level of the alerts to be forwarded. - - **Allowed:** 1 - 16 + - **Allowed:** 1 - 16 + + - protocol + + - Transport for this syslog destination. TCP uses newline framing + (RFC 6587 non-transparent; one alert per line). Prefer TCP or TLS when + CEF/JSON alerts approach the 6K assemble limit and UDP would truncate + on the wire. + + - **Default** udp + + - **Allowed:** udp, tcp + + - tls + + - Wrap the TCP connection in TLS (RFC 5425-style stream). Implies + ``protocol`` tcp. Requires an OSSEC build with OpenSSL + (``LIBOPENSSL_ENABLED``). + + - **Default** no + + - **Allowed:** yes, no + + - tls_verify + + - Verify the peer certificate and hostname when ``tls`` is yes. Same UX + idea as ``global.smtp_tls_verify`` for maild. + + - **Default** yes + + - **Allowed:** yes, no + + - tls_ca + + - Optional path to a CA certificate file (PEM). Loaded before chroot. If + unset, OpenSSL default verify locations are used when ``tls_verify`` + is yes. + + - **Allowed:** Path to a readable CA file - group From 9a0db6999b7b790752749751128b0193d800cade Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Tue, 11 Aug 2026 14:02:00 -0400 Subject: [PATCH 2/2] Expand syslog_output TCP/TLS docs with examples and 4.3.0 markers. Document OpenSSL/chroot/reconnect behavior, add tcp and TLS CEF examples, and mark the new options with versionadded for 4.3.0. --- .../output/syslog_output_examples.trst | 33 +++++++++++++++++++ docs/manual/output/syslog-output.rst | 11 +++++-- docs/syntax/ossec_config.syslog_output.trst | 16 +++++++-- 3 files changed, 55 insertions(+), 5 deletions(-) diff --git a/docs/examples/output/syslog_output_examples.trst b/docs/examples/output/syslog_output_examples.trst index a8155f57..c58fb561 100644 --- a/docs/examples/output/syslog_output_examples.trst +++ b/docs/examples/output/syslog_output_examples.trst @@ -28,3 +28,36 @@ Send all alerts level 6 and above to 10.10.10.127 on port 515: 515 6 + + +Forward JSON alerts over TCP (no TLS): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 4.3.0 + +.. code-block:: xml + + + siem.example.com + 514 + tcp + json + + + +Forward CEF alerts over TLS to a collector on 6514: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 4.3.0 + +.. code-block:: xml + + + siem.example.com + 6514 + tcp + yes + yes + /etc/pki/tls/certs/ca-bundle.crt + cef + diff --git a/docs/manual/output/syslog-output.rst b/docs/manual/output/syslog-output.rst index ca5eef48..52a3a6d4 100644 --- a/docs/manual/output/syslog-output.rst +++ b/docs/manual/output/syslog-output.rst @@ -83,10 +83,16 @@ rule, location and the actual event that generated it): TCP and TLS ----------- +.. versionadded:: 4.3.0 + By default ``ossec-csyslogd`` still uses UDP. Set ``protocol`` to ``tcp`` for a persistent stream with newline framing (RFC 6587 non-transparent). Enable TLS with -``tls`` (implies TCP; requires an OpenSSL-enabled build). Optional ``tls_ca`` and -``tls_verify`` control certificate validation (same idea as SMTP TLS in maild). +``tls`` (implies TCP). Optional ``tls_ca`` and ``tls_verify`` control certificate +validation (same idea as SMTP TLS in maild). + +TLS destinations require an OSSEC build with OpenSSL (``LIBOPENSSL_ENABLED``). The +socket is opened before chroot so hostnames and ``tls_ca`` paths resolve on the +host filesystem. On send failure, csyslogd reconnects once. .. code-block:: xml @@ -96,6 +102,7 @@ persistent stream with newline framing (RFC 6587 non-transparent). Enable TLS wi tcp yes yes + /etc/pki/tls/certs/ca-bundle.crt json diff --git a/docs/syntax/ossec_config.syslog_output.trst b/docs/syntax/ossec_config.syslog_output.trst index 0856e73f..1bcd8094 100644 --- a/docs/syntax/ossec_config.syslog_output.trst +++ b/docs/syntax/ossec_config.syslog_output.trst @@ -26,6 +26,8 @@ - protocol + .. versionadded:: 4.3.0 + - Transport for this syslog destination. TCP uses newline framing (RFC 6587 non-transparent; one alert per line). Prefer TCP or TLS when CEF/JSON alerts approach the 6K assemble limit and UDP would truncate @@ -37,9 +39,12 @@ - tls + .. versionadded:: 4.3.0 + - Wrap the TCP connection in TLS (RFC 5425-style stream). Implies ``protocol`` tcp. Requires an OSSEC build with OpenSSL - (``LIBOPENSSL_ENABLED``). + (``LIBOPENSSL_ENABLED``). ``tls=yes`` with ``protocol`` udp is an + error. - **Default** no @@ -47,8 +52,11 @@ - tls_verify - - Verify the peer certificate and hostname when ``tls`` is yes. Same UX - idea as ``global.smtp_tls_verify`` for maild. + .. versionadded:: 4.3.0 + + - Verify the peer certificate and hostname (or IP) when ``tls`` is yes. + Same idea as ``global.smtp_tls_verify`` for maild. Setting this to + ``no`` disables peer verification (not recommended in production). - **Default** yes @@ -56,6 +64,8 @@ - tls_ca + .. versionadded:: 4.3.0 + - Optional path to a CA certificate file (PEM). Loaded before chroot. If unset, OpenSSL default verify locations are used when ``tls_verify`` is yes.