imrelp: RELP Input Module¶

Module Name:	imrelp
Author:	Rainer Gerhards <rgerhards@adiscon.com>

Purpose¶

Provides the ability to receive syslog messages via the reliable RELP protocol. This module requires librelp to be present on the system. From the user’s point of view, imrelp works much like imtcp or imgssapi, except that no message loss can occur. Please note that with the currently supported RELP protocol version, a minor message duplication may occur if a network connection between the relp client and relp server breaks after the client could successfully send some messages but the server could not acknowledge them. The window of opportunity is very slim, but in theory this is possible. Future versions of RELP will prevent this. Please also note that rsyslogd may lose a few messages if rsyslog is shutdown while a network connection to the server is broken and could not yet be recovered. Future versions of RELP support in rsyslog will prevent that issue. Please note that both scenarios also exist with plain TCP syslog. RELP, even with the small nits outlined above, is a much more reliable solution than plain TCP syslog and so it is highly suggested to use RELP instead of plain TCP. Clients send messages to the RELP server via omrelp.

Notable Features¶

Statistic Counter

Configuration Parameters¶

Note

Parameter names are case-insensitive; camelCase is recommended for readability.

Module Parameters¶

Parameter	Summary
ruleset	Assigns a ruleset to all RELP listeners created by the module instance.
tls.tlsLib	Selects the TLS backend library that librelp should use for RELP operations.

Input Parameters¶

Parameter	Summary
port	Starts a RELP server instance that listens on the specified TCP port.
address	Forces the RELP listener to bind to the specified local IP address or hostname.
name	Sets a human-readable name for the RELP listener instance.
ruleset	Overrides the module-wide ruleset binding for this specific RELP listener.
maxDataSize	Sets the max message size the RELP listener accepts before oversize handling.
tls	Enables TLS encryption for RELP connections handled by this listener.
tls.compression	Controls whether TLS sessions compress payload data before transmission.
tls.dhBits	Specifies the Diffie-Hellman key size, overriding the librelp default when set.
tls.permittedPeer	Restricts accepted clients to the listed certificate fingerprints or wildcard names.
tls.authMode	Selects the mutual authentication strategy for TLS-secured RELP sessions.
tls.caCert	Specifies the CA certificate file used to validate client certificates.
tls.myCert	Points rsyslog to the server certificate presented during TLS handshakes.
tls.myPrivKey	References the private key file that matches the configured tls.myCert.
tls.priorityString	Passes a custom GnuTLS priority string to fine-tune cryptographic parameters.
tls.tlsCfgCmd	Forwards SSL_CONF-style commands to OpenSSL when using the openssl backend.
keepAlive	Toggles TCP keep-alive probes for RELP listener sockets.
keepAlive.probes	Defines how many keep-alive retries occur before the connection is declared dead.
keepAlive.interval	Determines the delay between successive keep-alive probes when enabled.
keepAlive.time	Controls how long a connection stays idle before the first keep-alive probe is sent.
oversizeMode	Determines how messages larger than MaxDataSize are handled by the listener.
flowControl	Fine-tunes RELP input flow control behavior between no, light, or full throttling.

About Chained Certificates¶

Added in version 8.2008.0.

With librelp 1.7.0, you can use chained certificates. If using “openssl” as tls.tlslib, we recommend at least OpenSSL Version 1.1 or higher. Chained certificates will also work with OpenSSL Version 1.0.2, but they will be loaded into the main OpenSSL context object making them available to all librelp instances (omrelp/imrelp) within the same process.

If this is not desired, you will require to run rsyslog in multiple instances with different omrelp configurations and certificates.

Statistic Counter¶

This plugin maintains statistics for each listener. The statistic by default is named “imrelp” , followed by the listener port in parenthesis. For example, the counter for a listener on port 514 is called “imprelp(514)”. If the input is given a name, that input name is used instead of “imrelp”. This counter is available starting rsyslog 7.5.1

The following properties are maintained for each listener:

submitted - total number of messages submitted for processing since startup

Caveats/Known Bugs¶

see description
To obtain the remote system’s IP address, you need to have at least librelp 1.0.0 installed. Versions below it return the hostname instead of the IP address.

Examples¶

Example 1¶

This sets up a RELP server on port 2514 with a max message size of 10,000 bytes.

module(load="imrelp") # needs to be done just once
input(type="imrelp" port="2514" maxDataSize="10k")

Receive RELP traffic via TLS¶

This receives RELP traffic via TLS using the recommended “openssl” library. Except for encryption support the scenario is the same as in Example 1.

Certificate files must exist at configured locations. Note that authmode “certvalid” is not very strong - you may want to use a different one for actual deployments. For details, see parameter descriptions.

module(load="imrelp" tls.tlslib="openssl")
input(type="imrelp" port="2514" maxDataSize="10k"
             tls="on"
             tls.cacert="/tls-certs/ca.pem"
             tls.mycert="/tls-certs/cert.pem"
             tls.myprivkey="/tls-certs/key.pem"
             tls.authmode="certvalid"
             tls.permittedpeer="rsyslog")

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project