# 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.