RELP Protocol Design
Relevant source files
The following files were used as context for generating this wiki page:
The Reliable Event Logging Protocol (RELP) is designed to provide guaranteed delivery of event messages, such as syslog, over a network. It operates on a client-server model where the client initiates the connection and the server listens for incoming requests. RELP is specifically engineered to overcome the limitations of standard syslog over UDP or TCP, which can suffer from silent data loss during connection disruptions or buffer overflows.
Sources: doc/relp.html:11-18, src/librelp.h:1-20
At its core, RELP employs a command-response mechanism. Every command issued by a client must be acknowledged by the server using a unique transaction number (TXNR). This application-level acknowledgement ensures that the sender knows exactly which messages have been successfully processed by the receiver, allowing for session recovery and retransmission in case of network failures.
Sources: doc/relp.html:20-30, src/relpsess.h:35-45
Protocol Framing and Structure
RELP utilizes a consistent framing format for all transactions. A frame consists of a header containing a transaction number, a command, and the data length, followed by the actual data and a trailer.
Frame Format Definition
RELP-FRAME = HEADER DATA TRAILER
HEADER = TXNR SP COMMAND SP DATALEN
TXNR = 1*9DIGIT ; Monotonically increasing, starts at 1
COMMAND = 1*32ALPHA ; e.g., "open", "syslog", "close", "rsp"
DATALEN = 1*9DIGIT ; Number of octets in DATA
DATA = [SP 1*OCTET]
TRAILER = LF ; Line feed (0x0A)
Sources: doc/relp.html:84-105
Transaction Numbers (TXNR)
Transaction numbers are used to match responses to requests. They start at 1 and monotonically increase up to 999,999,999, after which they wrap back to 1. TXNR 0 is strictly reserved for "hint" commands, which are out-of-band messages that do not require an acknowledgement.
Sources: doc/relp.html:112-114, src/relp.h:185-187
Session Lifecycle
A RELP session progresses through several distinct states, from initial handshake to data transmission and eventual closure.
State Transitions
The following diagram illustrates the lifecycle of a RELP session from the perspective of the connection state.
Sources: src/relpsess.h:47-59
The "open" Handshake and Feature Negotiation
During the open command, the client and server exchange "offers." These offers define supported features, such as the protocol version and available commands.
- Client Offer: Sends
openwithrelp_version=1. - Server Response: Returns an
rspcontaining accepted offers. - Finalization: If
relp_versionis missing in the response, the client must close the connection.
Sources: doc/relp.html:132-150, src/offers.h:40-60
Command Implementation
RELP commands are processed through a dispatching interface that handles both core protocol commands and extended functionality like syslog transmission.
Standard Commands
| Command | Type | Description |
|---|---|---|
open | Regular | Initiates session and negotiates features. |
syslog | Regular | Transmits a syslog message in the data portion. |
close | Regular | Gracefully terminates the session. |
rsp | Response | Acknowledges a regular command using the same TXNR. |
serverclose | Hint | (TXNR 0) Server advises client of impending closure. |
Sources: doc/relp.html:120-175, src/cmdif.h:55-65
Response Processing
The rsp command data contains a status code and an optional human-readable message. A code of 200 indicates success (OK), while 500 and others indicate errors.
Sources: doc/relp.html:125-130, src/scrsp.c:65-90
Architectural Components
The librelp library is structured into several key objects to manage the protocol state.
Core Data Structures
- relpEngine_t: The root object managing servers and sessions. It holds global configurations like DNS settings and TLS library selection.
- relpSess_t: Represents an active session, maintaining the TXNR counter, unacked message list, and window size.
- relpSrv_t / relpClt_t: Wrappers for server-side listening and client-side connection management.
- relpFrame_t: Handles the parsing and construction of RELP frames.
Sources: src/relp.h:104-145, src/relpsess.h:66-105, src/librelp.h:47-65
Reliability through Windowing
To facilitate full-duplex communication while conserving resources, RELP uses a windowing mechanism. The client can have multiple "unacked" (outstanding) commands up to the sizeWindow limit.
Sources: doc/relp.html:25-28, src/relpsess.h:103, src/librelp.h:134
Security and TLS
RELP supports encrypted communication through TLS, allowing for mutual authentication and data integrity.
TLS Configuration Options
| Option | Description | Source File |
|---|---|---|
authmode | Supports fingerprint, name, or certvalid. | src/librelp.h:67-72 |
caCertFile | Path to the CA certificate for peer validation. | src/relpsrv.h:61 |
permittedPeers | ACL containing allowed peer names or fingerprints. | src/relp.h:73-76 |
pristring | GnuTLS priority string for cipher selection. | src/relpsess.h:85 |
Sources: src/relpsrv.c:230-260, src/relpsess.h:80-95
Summary
The RELP Protocol Design prioritizes reliability through mandatory application-level acknowledgements and a robust framing mechanism. By using transaction numbers to track every message, it allows clients and servers to maintain synchronization even across transient network failures. The modular architecture of librelp, centered around the Engine and Session objects, provides a scalable implementation that supports advanced features like TLS encryption and flexible feature negotiation via the offers system.
Sources: doc/relp.html:200-220, src/relp.h:104-110