Node.js Syslog Server

1.0.1 · active · verified Tue Apr 21

syslog-server is a lightweight Node.js library for creating a server to receive syslog messages over UDP. It provides a simple, event-driven API to start, stop, and manage the syslog listener. The library, currently at version 1.0.1, allows configuration of the listening port and address, and emits 'message' events for each incoming syslog packet. Each message event provides parsed details such as the reception date, originating host IP, IP protocol version (IPv4/IPv6), and the raw syslog message content. While it does not specify adherence to particular syslog RFCs for deep message parsing, it offers a foundational layer for applications needing to collect basic syslog data. Its primary differentiator is its minimal footprint and direct use of Node.js's built-in `dgram` module, making it suitable for simple syslog collection setups.

Common errors

```
Error: listen EACCES: permission denied 0.0.0.0:514
```
cause The application is trying to bind to a privileged port (514) without sufficient permissions.

fix Run your Node.js application with administrative privileges (e.g., `sudo node app.js`) or configure a non-privileged port (e.g., `server.start({ port: 10514 })`).
```
TypeError: SyslogServer is not a constructor
```
cause Attempting to use `import SyslogServer from 'syslog-server'` with a CommonJS-only package.

fix Change the import statement to `const SyslogServer = require('syslog-server');`.
```
Error: listen EADDRINUSE: address already in use 0.0.0.0:514
```
cause Another process is already listening on the specified IP address and port.

fix Ensure no other syslog server or application is running on the same port. Use `netstat -tulnp | grep 514` (Linux) or `lsof -i :514` (macOS) to identify the conflicting process, then terminate it or choose a different port for your `syslog-server` instance.

Warnings

gotcha The default port 514 is a privileged port on Unix-like systems. Running the server on this port often requires elevated permissions (e.g., `sudo`) or configuring system capabilities.
Fix: Run your Node.js application with `sudo` (not recommended for production) or configure your system to allow the Node.js process to bind to privileged ports without root, or choose a non-privileged port (e.g., >1024) for the syslog server.
breaking This package primarily uses Node.js CommonJS modules (`require`). Attempting to use `import` statements directly will result in a `TypeError: SyslogServer is not a constructor` or similar import errors.
Fix: Use the CommonJS `require()` syntax: `const SyslogServer = require('syslog-server');`. If you must use ESM, consider a transpilation step or a wrapper module that explicitly exports it for ESM consumption.
gotcha The library captures the raw syslog message (`value.message`) but does not explicitly mention parsing according to specific RFCs (e.g., RFC 3164, RFC 5424). Users expecting structured data beyond the raw message should implement their own parsing logic.
Fix: If advanced syslog message parsing (e.g., extracting facility, severity, timestamp from the message string) is required, integrate a dedicated syslog message parsing library or implement custom regex-based parsing on `value.message`.

Install

npm install syslog-server npm
yarn add syslog-server yarn
pnpm add syslog-server pnpm

Imports

SyslogServer
wrong:
```
import SyslogServer from 'syslog-server';
```
correct:
```
const SyslogServer = require('syslog-server');
```
This package is CommonJS-first. Direct ESM `import` statements are not supported without a transpiler or custom configuration, and will likely result in runtime errors. Stick to `require()`.
server.on('message', ...)
```
server.on('message', (value) => { /* handle message */ });
```
The core functionality relies on event listeners for 'message', 'start', 'stop', and 'error'. Ensure you register event handlers before calling `server.start()` to avoid missing initial events.
server.start
wrong:
```
server.start(options, callback);
```
correct:
```
server.start().then(() => console.log('Server started')).catch(err => console.error(err));
```
While `start` accepts an optional callback, it primarily returns a Promise for modern async/await patterns. Prefer Promise-based handling for better error propagation and readability.

Quickstart

This quickstart initializes a syslog server, logs incoming messages to the console, and includes basic error handling and graceful shutdown.

const SyslogServer = require('syslog-server');
const server = new SyslogServer();

server.on('message', (value) => {
    console.log(`Received message from ${value.host} (${value.protocol}) at ${value.date.toISOString()}:`);
    console.log(value.message);
});

server.on('start', () => {
    console.log('Syslog server started on port 514');
});

server.on('error', (err) => {
    console.error('Syslog server error:', err.message);
});

// Start the server, potentially on a different port if 514 is privileged or in use
server.start({
    port: process.env.SYSLOG_PORT ? parseInt(process.env.SYSLOG_PORT, 10) : 514,
    address: '0.0.0.0'
}).catch(err => {
    console.error('Failed to start syslog server:', err.message);
    process.exit(1);
});

// To stop the server gracefully on process exit
process.on('SIGINT', async () => {
    console.log('Shutting down syslog server...');
    await server.stop();
    console.log('Syslog server stopped.');
    process.exit(0);
});

view raw JSON →