Building a Server

Relevant source files

The following files were used as context for generating this wiki page:

• src/librelp.h
• src/relpsrv.c
• src/relp.h
• src/copen.c
• tests/receive.c
• doc/relp.html
• src/scsyslog.c

Introduction

Building a server in librelp involves utilizing the Reliable Event Logging Protocol (RELP) to create a listening entity capable of receiving and acknowledging event messages. The protocol uses a command-response model where the server acts as the listening part of the connection, responding to client commands such as open, syslog, and close.

The server architecture is centered around a relpEngine which manages the overall lifecycle, and relpSrv objects which handle specific listener instances. The library is designed to be thread-safe and devoid of static data, allowing multiple plugins or modules to instantiate their own RELP engines independently.
Sources: doc/relp.html:15-20, src/relp.h:116-124

Core Server Components

The RELP Engine

The relpEngine is the root object required for any RELP operation. It stores callback functions for event handling, protocol versions, and manages linked lists of active servers and sessions.

The RELP Server Object

The relpSrv object represents a specific listener instance. It maintains configuration state including the listening port, IP address, TLS settings, and permitted peers.
Sources: src/relp.h:125-167, src/relpsrv.c:48-73

The following diagram illustrates the relationship between the Engine and its child Server objects:

Server Lifecycle and Initialization

The process of building and starting a server follows a specific sequence of API calls to ensure all protocol and transport parameters are correctly configured before binding the listener.

Initialization Sequence

1. Construct Engine: Initialize the global engine context.
2. Configure Callbacks: Register functions for data reception (onSyslogRcv) and error reporting (onErr).
3. Construct Listener: Create the relpSrv_t object.
4. Set Properties: Configure port, IP, and security parameters (TLS).
5. Finalize Listener: Complete the construction and prepare for execution.
6. Run Engine: Start the event loop.
   Sources: tests/receive.c:380-450, src/relpsrv.c:285-320

Connection and Command Handling

The "Open" Handshake

When a client connects, it sends an open command containing "offers" (features it supports). The server processes these via the Init command handler. The server compares client offers against its own capabilities (e.g., protocol version, supported commands) and returns a response containing the accepted features.
Sources: doc/relp.html:105-125, src/copen.c:134-165

Syslog Message Reception

For the syslog command, the server executes the following logic:

1. Verifies the command is enabled for the current session.
2. Triggers the highest available version of the syslog callback (onSyslogRcv3, onSyslogRcv2, or onSyslogRcv).
3. Sends a 200 OK response back to the client to acknowledge successful processing.
   Sources: src/scsyslog.c:56-85

Data Handling Configuration

The server can be configured to handle oversized frames through various modes:

Mode	Description
RELP_OVERSIZE_ABORT	Closes the connection if a frame exceeds the maximum data size.
RELP_OVERSIZE_TRUNCATE	Truncates the frame and continues the session.
RELP_OVERSIZE_ACCEPT	Accepts the frame regardless of the size limit.
Sources: src/librelp.h:116-118, src/relpsrv.c:158-171

Security and TLS Configuration

Librelp servers support TLS encryption and various authentication modes. These must be configured on the server object before the listener is finalized.

Function	Purpose
relpSrvEnableTLS2	Enables TLS for the listener.
relpSrvSetAuthMode	Sets authentication to fingerprint, name, or certvalid.
relpSrvSetCACert	Configures the CA certificate for peer validation.
relpSrvAddPermittedPeer	Defines an ACL of authorized peer names/fingerprints.
Sources: src/relpsrv.c:198-220, src/relpsrv.c:260-280, src/librelp.h:173-180

Connection Security Flow

Conclusion

Building a server in librelp requires a structured approach to initializing the engine and configuring the listener properties. By leveraging the command-response architecture and the flexible callback system, developers can create reliable logging sinks that support modern security requirements such as TLS and strict peer authentication. The server's ability to negotiate features through the "offers" mechanism ensures compatibility across different protocol versions and software implementations.
Sources: src/relpsrv.c:285-310, doc/relp.html:10-30