Skip to content
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletions docs/configuration/system/syslog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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

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-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 <address> tls permitted-peers <peer_list>

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 </configuration/pki/index>`.

Local User Account
------------------
Expand Down