Server API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The RELP (Reliable Event Logging Protocol) Server API provides a framework for building reliable logging sinks. The server operates on a command-response model where the client initiates connections and issues commands (such as open, syslog, and close), and the server provides synchronized acknowledgments to ensure no data loss occurs during transmission.
The API is centered around the relpEngine and relpSrv objects. The engine manages the global state and event loop (using select or epoll), while the server object defines the specific listening properties, such as ports, addresses, and security configurations.
Sources: doc/relp.html:15-30, src/relp.c:215-230
Server Lifecycle Management
Server management follows a structured lifecycle: construction, configuration, finalization, and execution. The server is not active until the construction is finalized and the engine's run loop is started.
Construction and Initialization
To create a server, a developer first constructs a RELP engine and then uses the engine to instantiate a server object. The server inherits default protocol settings from the engine.
The diagram shows the standard sequence for initializing a RELP server.
Sources: src/relp.c:452-470, src/relpsrv.c:45-75
Core Server Functions
| Function | Description |
|---|---|
relpEngineListnerConstruct | Allocates a new relpSrv object and associates it with the engine. |
relpSrvSetLstnPort | Sets the TCP port the server will bind to. Defaults to 20514. |
relpSrvSetLstnAddr | Sets the specific IP address for binding (optional). |
relpEngineListnerConstructFinalize | Finalizes configuration and prepares the underlying TCP listener. |
relpSrvDestruct | Cleans up server resources and closes the listening socket. |
Sources: src/librelp.h:176-180, src/relpsrv.c:166-180, src/relpsrv.h:40-50
Protocol Handshake and Commands
RELP uses an "offers" mechanism during the open command to negotiate capabilities between the client and server.
The Open Command
When a client sends an open command, the server parses the client's offers (e.g., protocol version, supported commands) and selects a compatible subset to return in the response. A session is only considered open once the server sends a 200 OK response containing its accepted offers.
The sequence diagram illustrates the handshake process for establishing a reliable session.
Sources: doc/relp.html:105-120, src/copen.c:108-125
Command Handlers
The server dispatches incoming frames to specific handlers based on the command string.
- syslog: Processes incoming log messages. It triggers the configured callback (
onSyslogRcv) and returns a200 OKresponse to the client. - close: Initiates a graceful shutdown of the session.
- serverclose: A hint sent from server to client (txnr 0) indicating the server is shutting down.
Sources: src/relp.c:855-885, src/scsyslog.c:53-75, src/cserverclose.c:48-55
Security and TLS Configuration
The Server API provides extensive support for Transport Layer Security (TLS) through GnuTLS or OpenSSL.
TLS Configuration API
Servers can be configured with specific certificates, private keys, and authentication modes to secure the log stream.
| Function | Parameter | Description |
|---|---|---|
relpSrvEnableTLS2 | - | Enables TLS for the server instance. |
relpSrvSetAuthMode | "fingerprint", "name", "certvalid" | Sets the requirement for peer authentication. |
relpSrvSetCACert | path to CA | Sets the Certificate Authority file for validating clients. |
relpSrvSetOwnCert | path to Cert | Sets the server's machine certificate. |
relpSrvSetPrivKey | path to Key | Sets the server's private key. |
relpSrvAddPermittedPeer | peer name/IP | Adds a peer to the ACL; restricts access to only these peers. |
Sources: src/relpsrv.c:250-320, src/librelp.h:195-205
Event Loop and Networking
The server relies on the relpEngineRun function to process I/O. Depending on the platform, librelp uses either select() or epoll() to manage multiple concurrent sessions.
Connection Handling
When a new connection request arrives on a listening socket, the engine calls handleConnectionRequest, which accepts the socket and constructs a relpSess object.
This flowchart describes how the engine manages the transition from a connection request to data processing.
Sources: src/relp.c:640-670, src/relp.c:750-780
Error Handling
The server provides several callback hooks for error reporting:
- onSyslogRcv: Primary callback for successful message reception.
- onAuthErr: Called when a client fails TLS authentication.
- onErr: Called for object-specific errors (e.g., session-level failures).
- onGenericErr: Called for errors that cannot be mapped to a specific session or listener.
Sources: src/librelp.h:185-193, src/relp.h:105-115
Response Codes
The server communicates status back to the client using standard 3-digit codes in the rsp command data.
- 200: OK (Command successful).
- 500: Error (Generic error or protocol violation).
Sources: doc/relp.html:95-100, src/scrsp.c:60-75
Summary
The Server API in librelp is designed for high reliability and security. By separating the engine's execution logic from the server's configuration, it allows developers to easily embed reliable logging sinks into applications. The use of application-level acknowledgments (via the rsp command) ensures that every syslog message is confirmed as processed before the client considers the transaction complete.