# 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

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.