From fe9adab0f655cffb0b625c845ca4c596cba56e00 Mon Sep 17 00:00:00 2001 From: Oleksandr Kuchmystyi Date: Fri, 19 Sep 2025 16:17:24 +0300 Subject: [PATCH 1/2] syslog: T4251: Add documentation for syslog TLS configuration Documented protocol, certificate, auth-mode, and permitted-peers requirements for TLS configuration. (cherry picked from commit a3d3347ee8e05e11a23d795070803748bcf84458) --- docs/configuration/system/syslog.rst | 97 ++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 8755d90510..b77350222a 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -78,6 +78,103 @@ sending the messages via port 514/UDP. Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. +TLS Options +^^^^^^^^^^^ + +When ``set system syslog host
protocol tcp`` is selected, +an additional ``tls`` sub-node can be used to enable encryption and +configure certificate handling. TLS is not supported over UDP and +if you attempt to enable TLS while using UDP, the system will issue a warning. + +.. cfgcmd:: set system syslog host
tls enable + + Enable TLS for this remote syslog destination. + +.. cfgcmd:: set system syslog host
tls ca-certificate + + Reference to a :abbr:`CA (Certification Authority)` certificate stored + in the :abbr:`PKI (Public Key Infrastructure)` subsystem. + Used to validate the certificate chain of the remote syslog server. + Required when the authentication mode is anything other than ``anon``. + +.. cfgcmd:: set system syslog host
tls certificate + + Reference to a client certificate stored in the PKI subsystem. + Required when the server enforces client certificate authentication. + +.. cfgcmd:: set system syslog host
tls auth-mode + + Defines the peer authentication mode: + + * **anon** - allow encrypted connection without verifying peer identity + (not recommended, vulnerable to :abbr:`MITM (Man-in-the-Middle)`). + * **fingerprint** - verify the peer certificate against an explicitly + configured fingerprint list (set with ``permitted-peers``). + * **certvalid** - validate that the peer presents a certificate signed by + a trusted CA, but do not check the certificate subject name + (:abbr:`CN (Common Name)`). + * **name** - validate that the peer presents a certificate signed by a + trusted CA and that the certificate’s CN matches the value configured in + ``permitted-peers``. This is the recommended secure mode for production. + + .. note:: The default value for the authentication mode is ``anon``. + +.. cfgcmd:: set system syslog host
tls permitted-peers + + Comma-separated list of permitted peers or certificate’s subject names (CN). + + * In ``fingerprint`` authentication mode: provide one or more peer + certificate fingerprints (SHA1 or SHA256). + * In ``name`` authentication mode: explicit list of certificate’s CN to enforce. + * Ignored in ``anon`` and ``certvalid``. + +Examples: +^^^^^^^^^ + +.. code-block:: none + + # Example of 'anon' authentication mode + set system syslog host 10.10.2.3 facility all level debug + set system syslog host 10.10.2.3 port 6514 + set system syslog host 10.10.2.3 protocol tcp + set system syslog host 10.10.2.3 tls enable + + # Example of 'certvalid' authentication mode + set system syslog host elk.example.com facility all level debug + set system syslog host elk.example.com port 6514 + set system syslog host elk.example.com protocol tcp + set system syslog host elk.example.com tls enable + set system syslog host elk.example.com tls ca-certificate my-ca + set system syslog host elk.example.com tls auth-mode certvalid + + # Example of 'fingerprint' authentication mode + set system syslog host syslog.example.com facility all level debug + set system syslog host syslog.example.com port 6514 + set system syslog host syslog.example.com protocol tcp + set system syslog host syslog.example.com tls enable + set system syslog host syslog.example.com tls ca-certificate my-ca + set system syslog host syslog.example.com tls auth-mode fingerprint + set system syslog host syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...' + + # Example of 'name' authentication mode + set system syslog host graylog.example.com facility all level debug + set system syslog host graylog.example.com port 6514 + set system syslog host graylog.example.com protocol tcp + set system syslog host graylog.example.com tls enable + set system syslog host graylog.example.com tls ca-certificate my-ca + set system syslog host graylog.example.com tls certificate syslog-client + set system syslog host graylog.example.com tls auth-mode name + set system syslog host graylog.example.com tls permitted-peers 'graylog.example.com' + +Security Notes +^^^^^^^^^^^^^^ + +* Always prefer ``auth-mode name`` for secure deployments, as it ensures + both CA trust and server hostname validation. +* ``anon`` mode should only be used for testing, because it does not + authenticate the server. +* Ensure private keys are stored and managed exclusively in the + :doc:`PKI system `. Local User Account ------------------ From 29cf9050b1baf1693840dfd6256dbf6223ddfe17 Mon Sep 17 00:00:00 2001 From: Oleksandr Kuchmystyi Date: Fri, 24 Oct 2025 14:55:41 +0300 Subject: [PATCH 2/2] syslog: T4251: Fix documentation of TLS enablement logic for syslog (cherry picked from commit a271d322e2977686dbd67f5967a9c1660f6789bd) --- docs/configuration/system/syslog.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index b77350222a..1ab3c6cf65 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -86,7 +86,7 @@ an additional ``tls`` sub-node can be used to enable encryption and configure certificate handling. TLS is not supported over UDP and if you attempt to enable TLS while using UDP, the system will issue a warning. -.. cfgcmd:: set system syslog host
tls enable +.. cfgcmd:: set system syslog host
tls Enable TLS for this remote syslog destination. @@ -137,13 +137,13 @@ Examples: set system syslog host 10.10.2.3 facility all level debug set system syslog host 10.10.2.3 port 6514 set system syslog host 10.10.2.3 protocol tcp - set system syslog host 10.10.2.3 tls enable + set system syslog host 10.10.2.3 tls auth-mode anon + # or just use 'set system syslog host 10.10.2.3 tls' # Example of 'certvalid' authentication mode set system syslog host elk.example.com facility all level debug set system syslog host elk.example.com port 6514 set system syslog host elk.example.com protocol tcp - set system syslog host elk.example.com tls enable set system syslog host elk.example.com tls ca-certificate my-ca set system syslog host elk.example.com tls auth-mode certvalid @@ -151,7 +151,6 @@ Examples: set system syslog host syslog.example.com facility all level debug set system syslog host syslog.example.com port 6514 set system syslog host syslog.example.com protocol tcp - set system syslog host syslog.example.com tls enable set system syslog host syslog.example.com tls ca-certificate my-ca set system syslog host syslog.example.com tls auth-mode fingerprint set system syslog host syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...' @@ -160,7 +159,6 @@ Examples: set system syslog host graylog.example.com facility all level debug set system syslog host graylog.example.com port 6514 set system syslog host graylog.example.com protocol tcp - set system syslog host graylog.example.com tls enable set system syslog host graylog.example.com tls ca-certificate my-ca set system syslog host graylog.example.com tls certificate syslog-client set system syslog host graylog.example.com tls auth-mode name