syslog: T4251: Add documentation for syslog TLS configuration (backport) (#1689)

* 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)

* syslog: T4251: Fix documentation of TLS enablement logic for syslog

(cherry picked from commit a271d322e2977686dbd67f5967a9c1660f6789bd)

* syslog: T4251: Rename "permitted-peers" to "permitted-peer"

- Renamed `permitted-peers` to `permitted-peer`.
- Added support for multiple `permitted-peer` entries.

(cherry picked from commit 85a097b4a19b52179b45966cbcc8c7f30030a884)

1 files changed, 95 insertions, 0 deletions

diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst
index 8755d905..d6c422a0 100644
--- a/docs/configuration/system/syslog.rst
+++ b/docs/configuration/system/syslog.rst
@@ -78,6 +78,101 @@ 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 <address> 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 <address> tls
+
+   Enable TLS for this remote syslog destination.
+
+.. cfgcmd:: set system syslog host <address> tls ca-certificate <ca_name>
+
+   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 <address> tls certificate <cert_name>
+
+   Reference to a client certificate stored in the PKI subsystem.
+   Required when the server enforces client certificate authentication.
+
+.. cfgcmd:: set system syslog host <address> tls auth-mode <anon|fingerprint|certvalid|name>
+
+   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-peer``).
+   * **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-peer``. This is the recommended secure mode for production.
+
+   .. note:: The default value for the authentication mode is ``anon``.
+
+.. cfgcmd:: set system syslog host <address> tls permitted-peer <peer>
+
+   Allowed peer certificate fingerprint or subject name (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 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 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 ca-certificate my-ca
+   set system syslog host syslog.example.com tls auth-mode fingerprint
+   set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...'
+
+   # 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 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-peer '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 </configuration/pki/index>`.
 
 Local User Account
 ------------------