feat(syslog): set-up help on the page, port 5514 published, Docker-hidden senders called out (#6003)
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:
@@ -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.
|
||||
Reference in New Issue
Block a user