Skip to content

Commit 56be17c

Browse files
alexandr-san4ezalexandr-san4ez
authored
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 a3d3347) * syslog: T4251: Fix documentation of TLS enablement logic for syslog (cherry picked from commit a271d32) * 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 85a097b)
1 parent 41305a1 commit 56be17c

File tree

1 file changed

+95
-0
lines changed

1 file changed

+95
-0
lines changed

‎docs/configuration/system/syslog.rst‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,101 @@ sending the messages via port 514/UDP.
7878

7979
Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance.
8080

81+
TLS Options
82+
^^^^^^^^^^^
83+
84+
When ``set system syslog host <address> protocol tcp`` is selected,
85+
an additional ``tls`` sub-node can be used to enable encryption and
86+
configure certificate handling. TLS is not supported over UDP and
87+
if you attempt to enable TLS while using UDP, the system will issue a warning.
88+
89+
.. cfgcmd:: set system syslog host <address> tls
90+
91+
Enable TLS for this remote syslog destination.
92+
93+
.. cfgcmd:: set system syslog host <address> tls ca-certificate <ca_name>
94+
95+
Reference to a :abbr:`CA (Certification Authority)` certificate stored
96+
in the :abbr:`PKI (Public Key Infrastructure)` subsystem.
97+
Used to validate the certificate chain of the remote syslog server.
98+
Required when the authentication mode is anything other than ``anon``.
99+
100+
.. cfgcmd:: set system syslog host <address> tls certificate <cert_name>
101+
102+
Reference to a client certificate stored in the PKI subsystem.
103+
Required when the server enforces client certificate authentication.
104+
105+
.. cfgcmd:: set system syslog host <address> tls auth-mode <anon|fingerprint|certvalid|name>
106+
107+
Defines the peer authentication mode:
108+
109+
* **anon** - allow encrypted connection without verifying peer identity
110+
(not recommended, vulnerable to :abbr:`MITM (Man-in-the-Middle)`).
111+
* **fingerprint** - verify the peer certificate against an explicitly
112+
configured fingerprint list (set with ``permitted-peer``).
113+
* **certvalid** - validate that the peer presents a certificate signed by
114+
a trusted CA, but do not check the certificate subject name
115+
(:abbr:`CN (Common Name)`).
116+
* **name** - validate that the peer presents a certificate signed by a
117+
trusted CA and that the certificate’s CN matches the value configured in
118+
``permitted-peer``. This is the recommended secure mode for production.
119+
120+
.. note:: The default value for the authentication mode is ``anon``.
121+
122+
.. cfgcmd:: set system syslog host <address> tls permitted-peer <peer>
123+
124+
Allowed peer certificate fingerprint or subject name (CN).
125+
126+
* In ``fingerprint`` authentication mode: provide one or more peer
127+
certificate fingerprints (SHA1 or SHA256).
128+
* In ``name`` authentication mode: explicit list of certificate’s CN to enforce.
129+
* Ignored in ``anon`` and ``certvalid``.
130+
131+
Examples:
132+
^^^^^^^^^
133+
134+
.. code-block:: none
135+
136+
# Example of 'anon' authentication mode
137+
set system syslog host 10.10.2.3 facility all level debug
138+
set system syslog host 10.10.2.3 port 6514
139+
set system syslog host 10.10.2.3 protocol tcp
140+
set system syslog host 10.10.2.3 tls auth-mode anon
141+
# or just use 'set system syslog host 10.10.2.3 tls'
142+
143+
# Example of 'certvalid' authentication mode
144+
set system syslog host elk.example.com facility all level debug
145+
set system syslog host elk.example.com port 6514
146+
set system syslog host elk.example.com protocol tcp
147+
set system syslog host elk.example.com tls ca-certificate my-ca
148+
set system syslog host elk.example.com tls auth-mode certvalid
149+
150+
# Example of 'fingerprint' authentication mode
151+
set system syslog host syslog.example.com facility all level debug
152+
set system syslog host syslog.example.com port 6514
153+
set system syslog host syslog.example.com protocol tcp
154+
set system syslog host syslog.example.com tls ca-certificate my-ca
155+
set system syslog host syslog.example.com tls auth-mode fingerprint
156+
set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...'
157+
158+
# Example of 'name' authentication mode
159+
set system syslog host graylog.example.com facility all level debug
160+
set system syslog host graylog.example.com port 6514
161+
set system syslog host graylog.example.com protocol tcp
162+
set system syslog host graylog.example.com tls ca-certificate my-ca
163+
set system syslog host graylog.example.com tls certificate syslog-client
164+
set system syslog host graylog.example.com tls auth-mode name
165+
set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com'
166+
167+
Security Notes
168+
^^^^^^^^^^^^^^
169+
170+
* Always prefer ``auth-mode name`` for secure deployments, as it ensures
171+
both CA trust and server hostname validation.
172+
* ``anon`` mode should only be used for testing, because it does not
173+
authenticate the server.
174+
* Ensure private keys are stored and managed exclusively in the
175+
:doc:`PKI system </configuration/pki/index>`.
81176

82177
Local User Account
83178
------------------

0 commit comments

Comments
 (0)