diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 8755d90510..d6c422a0ae 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
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 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-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
tls permitted-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 `. Local User Account ------------------