vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-12-13 09:02:02 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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)
This commit is contained in:
Alexandr K. 2025-12-04 18:10:42 +03:00 committed by GitHub
parent 41305a14f6
commit 56be17c2c8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 95 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
docs/configuration/system/syslog.rst
View File

@ -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
------------------