bvandeusenandClaude Opus 5.5
fcd58224de
The SNMP poll asks each device's sysName in the same GET and keeps it (snmp_003_sys_name). A syslog source told apart by name finds its own address from the SNMP device (reported or given name) or host of that name, so its lines reach the SNMP device's and host's pages again; the edit page gains Device address, which always wins (syslog_004). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# 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**, 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):
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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.
|