relp - binding for the RELP (Reliable Event Logging Protocol) protocol

© 2012 Lourens Naudé (methodmissing), Erkki Eilonen (erkki)

About the RELP protocol

The RELP protocol is a reliable (read: no message loss, but see caveats below) solution to vanilla tcp event / message transfer. It supports full-duplex communication through a command-response model. Commands and responses are bound by an increasing transaction number.

Caveats :

It was initially designed for rsyslog-to-rsyslog communication, but can be used for various other applications. You can reference the protocol specification here

About librelp

Quote from the librelp homepage :

“librelp is an easy to use library for the RELP protocol. RELP in turn provides reliable event logging over the network (and consequently RELP stands for Reliable Event Logging Protocol). RELP was initiated by Rainer Gerhards after he was finally upset by the lossy nature of plain tcp syslog and wanted a cure for all these dangling issues.”

About this binding


Here’s a few basic examples. Please refer to documentation ( and test cases ( for detailed usage information.

High level API

# client process
client = Relp::Client.connect(Socket::AF_INET, 'localhost', 518)
client.send("test message")

# server process
receive_callback ={|host,ip,msg| p "got #{msg} from #{ip}" }
# This call blocks the current thread of execution. Messages are processed via the callback Proc
server = Relp::Server.bind(518, receive_callback)

Low level API

All protocol and connection state’s kept within a single context, the Relp::Engine. An engine must be instantiated and passed as an initializer argument to Relp::Client and Relp::Server instances. Each of these roles also support a destroy method which will gracefully shutdown the engine and transfer state. This pretty much resembles the rsyslog Output / Input module design and we had to jump through some hoops in order to hide these details from the end user.

# client process
engine =
client =
client.connect(Socket::AF_INET, 'localhost', 518)

# server process
engine =
server =
callback ={|host,ip,msg| p "got #{msg} from #{ip}" }
# starts the engine loop - blocks current thread


Don’t know and in the interim, don’t care. It’s fast enough for most use cases - shipping events to an event sink in a reliable manner. There’s two things to note here :

Use rsyslog with the RELP Input Module as an event sink if you must.




Rubygems installation

gem install relp

Building from source

git clone

Running tests

rake test


Contact, feedback and bugs

This project is still work in progress. Please log bugs and suggestions at