FabledSteward/docs/plugins/syslog.md

Syslog plugin

Receives syslog from NASes, routers and other devices over UDP and TCP (RFC 3164 and RFC 5424). The plugin keeps the lines of the sources you add and puts them beside Steward's other readings.

What it does

• Sources. A device that starts sending is offered on the Syslog page. Its lines are counted there but not stored until an admin adds it. Ignored senders are still counted. Each added source keeps its lines in a ring: the age limit (retention_days, 14 by default) and the size cap (max_bytes_per_source) are set in Settings → Plugins → Syslog.
• Reading. Each source has its own page, with lines filtered by severity, app, text and time. A host's page and an SNMP device's page show the newest lines of the sources mapped to them. A source maps to a host by its binding, or, when it has none, by sharing the host's or device's address.
• Patterns. Syslog → Patterns counts each source's lines matching some phrases (case-insensitive) or a severity over a window. The count is written every minute as the metric lines_matching_<key> under source module syslog, zeros included, so an ordinary alert rule fires on the first match and clears once the window has passed. Ready-made patterns cover disk I/O errors, disk resets, NFS server trouble, filesystem errors, degraded arrays and "errors and worse". "Alert on it" opens the rule form aimed at the count.
• Beside the readings. get_anomaly includes the warnings and worse logged by the anomaly's host or SNMP device. Each anomaly row has "Syslog around it". Host metrics charts and SNMP device charts mark each error with a dashed red line.
• MCP. list_syslog_sources and search_syslog.

Deploying

Steward runs as an unprivileged user, so it listens on 5514 (UDP and TCP), not 514. Publish that port from the container:

# docker compose
ports:
  - "5514:5514/udp"
  - "5514:5514/tcp"

Under Docker Swarm, publish it in host mode:

ports:
  - { target: 5514, published: 5514, protocol: udp, mode: host }
  - { target: 5514, published: 5514, protocol: tcp, mode: host }

Swarm's default (ingress) publishing hands every packet over from an address on the ingress network. Every device would then read as one sender, because sources are told apart by the address their lines come from. The Syslog page flags a sender whose address is on Steward's own container network.

Host mode publishes the port on the node that runs the task, so point devices at that node. Keep the service on one node with a placement constraint, so the address you give the devices stays right.

To let devices use 514 instead, publish 514:5514 instead of 5514:5514.

Pointing a device at it

The Syslog page's "Point a device here" section gives the address and port, and where the setting is on common devices (Synology, QNAP, TrueNAS, OpenWrt, UniFi, rsyslog). Choose the RFC 5424 / IETF format where it is offered: those lines carry their time zone.