TLS Encryption & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
TLS (Transport Layer Security) in rsyslog provides a mechanism to encrypt syslog traffic and authenticate communicating peers, moving beyond the inherent insecurities of traditional clear-text protocols. By leveraging public/private key infrastructure (PKI) and X.509 certificates, rsyslog ensures that messages are protected from sniffing and man-in-the-middle attacks while traveling over the wire.
The implementation relies on a "network stream layer" (netstream) that abstracts transport details from the application logic. This layer utilizes driver plugins such as gtls (GnuTLS) or ossl (OpenSSL) to handle the cryptographic handshakes and data encryption. Mutual authentication is supported, allowing the sender to verify the receiver's identity and vice-versa, which is critical for secure logging environments.
Sources: doc/source/tutorials/tls.rst:19-25, doc/source/tutorials/tls_cert_summary.rst:20-30, runtime/AGENTS.md:14-15
Architecture and Components
The rsyslog TLS architecture is structured into multiple layers to decouple the syslog protocol from the underlying encryption technology.
Network Stream Layer (Netstream)
Network transports in rsyslog utilize the netstream layer to provide a unified view of message transfer. The upper layers (plain TCP syslog sender and receiver) interact with this abstraction, while the driver plugins perform the actual network I/O and encryption.
Sources: doc/source/tutorials/tls.rst:59-66
Driver Plugins
Two primary drivers handle encrypted transfers:
- gtls: Utilizes the GnuTLS library.
- ossl: Utilizes the OpenSSL library.
- ptcp: Standing for "plain TCP," this driver is used for unencrypted transfers and is often used internally by the TLS drivers.
Sources: doc/source/tutorials/tls.rst:64-70, doc/source/deployments/rosi_collector/troubleshooting.rst:199-200
Component Relationship Diagram
The following diagram illustrates how the application layer interacts with the encryption drivers through the netstream abstraction.
The diagram shows the modular nature of rsyslog transport drivers.
Sources: doc/source/tutorials/tls.rst:59-70, runtime/AGENTS.md:14-15
Authentication Mechanisms
rsyslog TLS supports flexible authentication policies, ranging from anonymous encryption to strict mutual authentication using certificates.
Public/Private Key Security
Mutual authentication is achieved through X.509 certificates issued by a Certificate Authority (CA). The CA acts as a root of trust. Each machine (client or server) requires a machine certificate and a corresponding private key.
Sources: doc/source/tutorials/tls_cert_summary.rst:32-44
Authentication Modes
The level of validation is controlled by the StreamDriverAuthMode (or DefaultNetstreamDriverAuthMode) parameter:
- anon: Anonymous TLS; encryption is active but the peer's certificate is not validated.
- x509/certvalid: Validates that the peer's certificate is signed by a trusted CA.
- x509/name: Validates the certificate signature AND checks that the Subject Alternative Name (SAN) or Common Name (CN) matches a permitted list of peers.
Sources: doc/source/tutorials/tls.rst:112-114, doc/source/deployments/rosi_collector/troubleshooting.rst:216-224
Connection Flow
This sequence diagram shows a typical mutual authentication handshake between a client and a server.
The sequence demonstrates the exchange of certificates required for mutual authentication (mTLS).
Sources: doc/source/tutorials/tls_cert_summary.rst:22-30, doc/source/deployments/rosi_collector/troubleshooting.rst:216-225
Configuration and Implementation
Configuring TLS involves defining the global driver settings and applying them to specific input or output actions.
Global Driver Parameters
Global parameters define the default certificates and the driver to be used by the system.
| Parameter | Purpose | Typical Value |
|---|---|---|
DefaultNetstreamDriver | Sets the global default driver | gtls or ossl |
DefaultNetstreamDriverCAFile | Path to the Root CA certificate | /path/to/ca.pem |
DefaultNetstreamDriverCertFile | Path to the machine's certificate | /path/to/cert.pem |
DefaultNetstreamDriverKeyFile | Path to the machine's private key | /path/to/key.pem |
| Sources: doc/source/tutorials/tls.rst:95-103, doc/source/deployments/rosi_collector/troubleshooting.rst:183-186 |
Server (Input) Configuration
The imtcp module must be configured to use the TLS driver and listen on the designated port (usually 6514).
# Server-side setup
module(
load="imtcp"
StreamDriver.Name="gtls"
StreamDriver.Mode="1"
StreamDriver.Authmode="anon"
)
input(type="imtcp" port="6514")
Sources: doc/source/tutorials/tls.rst:104-118
Client (Output) Configuration
The omfwd action defines the target server and the necessary TLS parameters for the connection.
# Client-side setup
action(
type="omfwd"
protocol="tcp"
target="server.example.net"
port="6514"
StreamDriver="gtls"
StreamDriverMode="1"
StreamDriverAuthMode="anon"
)
Sources: doc/source/tutorials/tls.rst:133-138
Troubleshooting and Maintenance
TLS implementations are sensitive to certificate validity and network configuration.
Common Failure Points
- Certificate Expiry: Certificates have defined expiration dates. Once reached, rsyslog will no longer accept them, resulting in a cessation of message transmission.
- Hostname Mismatch: In
x509/namemode, the peer name in the certificate must match the expected name or the connection will be rejected. - Permission Issues: The rsyslog process must have read access to the private key files, which are often restricted for security.
Sources: doc/source/tutorials/tls_cert_summary.rst:84-88, doc/source/deployments/rosi_collector/troubleshooting.rst:192-205
Diagnostic Commands
Troubleshooting often requires verifying the handshake manually or checking for specific error strings in the logs.
| Method | Command / Action |
|---|---|
| Verify Handshake | openssl s_client -connect host:6514 -CAfile ca.pem |
| Check Expiry | openssl x509 -in cert.pem -noout -dates |
| Log Inspection | grep -i tls /var/log/syslog or docker compose logs rsyslog |
| Sources: doc/source/deployments/rosi_collector/troubleshooting.rst:188-215 |
Conclusion
TLS encryption and authentication in rsyslog provide a robust framework for securing log data as it moves through a network. By isolating cryptographic logic into netstream drivers and enforcing mutual authentication through PKI, the system effectively mitigates the risks associated with clear-text syslog. Proper management of certificate lifecycles and correct driver configuration are essential for maintaining a high-availability, secure logging infrastructure.