Introduction to librelp
Relevant source files
The following files were used as context for generating this wiki page:
librelp is a core protocol library implementing the Reliable Event Logging Protocol (RELP). It provides a reliable alternative to traditional syslog transmission by using an application-level acknowledgement model to ensure no message loss during transfer. The library is designed to have no static data, with all states stored within engine objects, enabling multi-threaded environments and multiple plugins to use the engine simultaneously.
Sources: src/relp.h:43-52, doc/relp.html:10-15
The protocol utilizes a client-server architecture where the client initiates connections and issues commands, while the server listens for connections and provides responses. librelp supports modern security features including TLS encryption and authentication via GnuTLS or OpenSSL.
Sources: doc/relp.html:15-20, src/relp.c:134-140
Architecture and Core Components
The librelp architecture is built around several key object types that manage the lifecycle of a RELP connection, from the global engine state to individual frames of data.
The RELP Engine (relpEngine_t)
The Engine is the central object that manages global configuration, lists of active servers (listeners), and active sessions. It handles the main event loop and dispatches incoming frames to appropriate handlers.
Sources: src/relp.h:120-131, src/relp.c:500-510
Client and Server Objects
relpSrv_t: Represents a listening service bound to a specific port and address.relpClt_t: Manages the client-side state, including target host information and window sizes for unacknowledged frames.
Sources: src/relpclt.h:35-50, src/librelp.h:58-65
Sessions and Frames
relpSess_t: Encapsulates a single established connection between a client and server. It tracks session-specific states such as protocol version, window state, and TLS settings.relpFrame_t: The basic unit of data transfer, consisting of a transaction number (TXNR), a command, data length, and the actual payload.
Sources: src/relpsess.h:60-80, doc/relp.html:81-90
Object Relationship
The following diagram illustrates the relationship between the primary components of librelp:
The diagram shows how the Engine acts as a container for both Server listeners and active Sessions.
Sources: src/relp.h:120-170, src/relpsess.h:60-100, src/relpclt.h:35-55
Protocol Mechanics
RELP employs a command-response model. Each command is assigned a unique, monotonically increasing Transaction Number (TXNR).
Frame Structure
A RELP frame is composed of a header, data, and a trailer.
- Header:
TXNR SP COMMAND SP DATALEN - Data: Command-defined payload.
- Trailer: A Line Feed (LF) character to detect framing errors.
Sources: doc/relp.html:81-100
Transaction Flow
- Open: The client sends an
opencommand with "offers" (supported features like protocol version). - Syslog: The standard command for transmitting log messages.
- Response (rsp): The server must respond to every command with a
rspframe containing a status code (e.g., 200 for OK, 500 for Error). - Close: Gracefully terminates the session.
Sources: doc/relp.html:117-150
Sequence of a RELP Transaction
The sequence diagram details the handshake, message transmission with acknowledgement, and teardown.
Sources: doc/relp.html:192-210
Session and Error Management
librelp handles connection failures by aborting the current session. Because every message is acknowledged at the application level, the client can detect which messages were not confirmed before the session broke and re-send them upon reconnection.
Sources: doc/relp.html:56-65, doc/relp.html:245-255
Session States
Sessions transition through various states during their lifecycle:
Sources: src/relpsess.h:45-55
| State | Description |
|---|---|
eRelpSessState_PRE_INIT | Session object created but handshake not started. |
eRelpSessState_READY_TO_SEND | Handshake complete; session active. |
eRelpSessState_WINDOW_FULL | Maximum unacknowledged frames reached. |
eRelpSessState_CLOSE_CMD_SENT | Client initiated shutdown. |
eRelpSessState_BROKEN | Error occurred; session must be dropped. |
Error Codes
The library uses specific return values (relpRetVal) to indicate status:
Sources: src/librelp.h:105-135
| Constant | Value | Description |
|---|---|---|
RELP_RET_OK | 0 | Success. |
RELP_RET_INVALID_FRAME | 10002 | Received frame does not follow specification. |
RELP_RET_SESSION_BROKEN | 10007 | Connection lost or protocol error occurred. |
RELP_RET_DATA_TOO_LONG | 10010 | Payload exceeds negotiated maxDataSize. |
TLS and Security
librelp supports secure communications using TLS. It provides an abstraction layer allowing users to choose between GnuTLS and OpenSSL.
Sources: src/relp.h:176, src/librelp.h:145-150
Authentication Modes
Users can configure how peers are authenticated:
- None: No certificate validation.
- Fingerprint: Validates the certificate's SHA1 fingerprint.
- Name: Validates the peer's subject name against a permitted list.
- CertValid: Standard CA-based certificate validation.
Sources: src/librelp.h:79-85, src/relpsess.h:112-115
Event Loop and I/O
The engine's relpEngineRun function implements the event loop. On systems where available, it uses epoll for high-performance I/O multiplexing; otherwise, it falls back to select.
Sources: src/relp.c:510-530, src/relp.c:640-660
This flowchart illustrates the internal execution logic of the librelp engine.
Sources: src/relp.c:700-750
Summary
librelp provides a robust framework for reliable log delivery. By implementing the RELP protocol's application-level acknowledgements and transaction-based framing, it ensures data integrity even over unstable network connections. Its object-oriented design and pluggable TLS support make it a flexible component for logging systems like rsyslog.
Sources: doc/relp.html:1-10, src/relp.h:43-52