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, either publishing mode works.

Ingress (Swarm's default) lets Steward move between nodes. Devices send to any node's address, or to an address shared over the nodes (a keepalived VIP):

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

Through ingress every line arrives from Docker's own address on the ingress network, so the address no longer tells the devices apart. For such an address Steward keys the source by the hostname each line carries instead (#6096): each device is its own source. A device must put its hostname in its lines (NASes and routers do); lines with none at Docker's address all fold into one source, and the page says so.

Such a source's own address, which places its lines on its SNMP device's and host's pages (chart marks, the lines around an anomaly), is found by name: the SNMP device whose reported name (sysName, asked with every poll) or given name matches, else the host of that name. Where nothing matches, set Device address on the source's edit page; a value set there always wins.

Host mode keeps each device's own address, but only the node running the task answers, so devices must be pointed at that node:

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

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, ASUSTOR, QNAP, TrueNAS, OpenWrt, UniFi, rsyslog). The address is the plugin's send_to setting (Settings → Plugins → Syslog): Steward's web address is often a name only its proxy answers, so it isn't guessed. Both formats are read, BSD (RFC 3164) and IETF (RFC 5424); choose IETF where it is offered, as its lines carry their time zone. ASUSTOR's ADM offers no choice and sends BSD.