bvandeusenandClaude Opus 5.5
0a647bbb82
Through ingress every device arrives from Docker's own address, so a source there is keyed by the hostname its lines carry (new column sender, unique with address). The set-up help no longer guesses the address from the web hostname: it shows the plugin's send_to setting, covers ingress and host mode, ASUSTOR ADM, and both syslog formats. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
81 lines
3.6 KiB
Markdown
81 lines
3.6 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, linked to a host by name. 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.
|
|
|
|
**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.
|