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