feat(syslog): set-up help on the page, port 5514 published, Docker-hidden senders called out (#6003)
CI / lint (push) Successful in 2s
CI / unit (push) Successful in 1m29s
CI / integration (push) Successful in 1m38s
CI / publish (push) Successful in 20s

The Syslog page says where to send (this server, its port and protocols) and
where the setting is on Synology, QNAP, TrueNAS, OpenWrt, UniFi and rsyslog,
open until a device sends. A sender whose address is on Steward's own
container network (Swarm ingress publishing hides the real sender) is
flagged, with the host-mode ports to publish instead. compose files and the
Dockerfile publish 5514/udp and /tcp; docs/plugins/syslog.md describes the
plugin and the deploy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-19 07:01:56 -04:00
co-authored by Claude Opus 5.5
parent 96f774ce24
commit ed9da56efa
10 changed files with 221 additions and 5 deletions
+67
View File
@@ -0,0 +1,67 @@
# 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:
```yaml
# docker compose
ports:
- "5514:5514/udp"
- "5514:5514/tcp"
```
Under **Docker Swarm**, publish it in **host mode**:
```yaml
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.