feat(syslog): devices through Swarm's ingress told apart by name; the send-to address is a setting (#6096)

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>

plugins/syslog/mcp_tools.py

@@ -25,6 +25,10 @@ async def list_syslog_sources(state: str = "") -> dict:
       "offered" (sending but not added: counted, not kept), "ignored";
       empty for all.
 
+    A device whose lines reach Steward through Docker's own address (a port
+    published on Swarm's ingress) is told apart by the name its lines carry:
+    `through_docker` is true and `address` is Docker's, shared with the others.
+
     Each gives its address, the host it is shown on, lines received in all
     (`lines_total`) and, for an added source, in the last hour, when it was
     last heard and its newest line. search_syslog searches the kept lines.
@@ -41,6 +45,7 @@ async def list_syslog_sources(state: str = "") -> dict:
         hosts = {h.id: h.name for h in (await db.execute(select(Host))).scalars()}
     return {"sources": [{
         "source_id": s.id, "name": source_name(s), "address": s.address, "state": s.state,
+        "through_docker": bool(s.sender),
         "host_id": s.host_id, "host_name": hosts.get(s.host_id), "calls_itself": s.hostname_seen or None,
         "lines_total": s.lines_total, "lines_last_hour": per_hour.get(s.id, 0) if s.state == "accepted" else None,
         "last_heard": iso(s.last_seen_at), "last_heard_age_s": age_s(s.last_seen_at, now),

plugins/syslog/migrations/versions/syslog_003_sender.py

@@ -0,0 +1,30 @@
+"""Syslog: devices that reach Steward through Docker's one address, told apart
+by the name in their lines
+
+Revision ID: syslog_003_sender
+Revises: syslog_002_patterns
+Create Date: 2026-10-19
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "syslog_003_sender"
+down_revision: Union[str, None] = "syslog_002_patterns"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("syslog_sources",
+                  sa.Column("sender", sa.String(255), nullable=False, server_default=""))
+    op.drop_constraint("syslog_sources_address_key", "syslog_sources", type_="unique")
+    op.create_unique_constraint("uq_syslog_sources_address_sender", "syslog_sources", ["address", "sender"])
+
+
+def downgrade() -> None:
+    op.drop_constraint("uq_syslog_sources_address_sender", "syslog_sources", type_="unique")
+    op.execute("DELETE FROM syslog_sources WHERE sender <> ''")
+    op.create_unique_constraint("syslog_sources_address_key", "syslog_sources", ["address"])
+    op.drop_column("syslog_sources", "sender")

plugins/syslog/models.py

@@ -3,7 +3,8 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 
-from sqlalchemy import JSON, BigInteger, Boolean, DateTime, ForeignKey, Index, SmallInteger, String, Text
+from sqlalchemy import (JSON, BigInteger, Boolean, DateTime, ForeignKey, Index, SmallInteger, String, Text,
+                        UniqueConstraint)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from steward.core.ids import time_ordered_id
@@ -13,6 +14,10 @@ from steward.models.base import Base
 class SyslogSource(Base):
     """A device that sends syslog to Steward, one row per sending address.
 
+    Through a port Swarm publishes on its ingress (the default), every device
+    arrives from one address of Docker's own; there a row is a device by the
+    name its lines carry, `sender` (#6096). Everywhere else `sender` is "".
+
     A sender Steward hasn't been told about is a row too, `state="offered"`:
     its lines are counted and its newest kept as a sample, so the page can
     offer it ("1,204 lines from 192.168.0.7: add as a source?"), but none is
@@ -20,9 +25,11 @@ class SyslogSource(Base):
     on; `"ignored"` stops the offer and keeps counting.
     """
     __tablename__ = "syslog_sources"
+    __table_args__ = (UniqueConstraint("address", "sender", name="uq_syslog_sources_address_sender"),)
 
     id: Mapped[str] = mapped_column(String(36), primary_key=True, default=time_ordered_id)
-    address: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
+    address: Mapped[str] = mapped_column(String(64), nullable=False)
+    sender: Mapped[str] = mapped_column(String(255), nullable=False, default="")
     state: Mapped[str] = mapped_column(String(10), nullable=False, default="offered")
     name: Mapped[str] = mapped_column(String(100), nullable=False, default="")
     host_id: Mapped[str | None] = mapped_column(

plugins/syslog/plugin.yaml

@@ -11,8 +11,11 @@ tags:
 
 # Sources are added from the Syslog page (/plugins/syslog/), where a device
 # that starts sending is offered. Steward runs as an unprivileged user, so
-# the port is above 1024: point devices at it, or map 514 to it.
+# the port is above 1024: point devices at it, or map 514 to it. send_to is
+# the address the page's set-up help tells devices to send to (a swarm node's
+# IP, or an address shared over the nodes when the port is on Swarm's ingress).
 config:
+  send_to: ""
   port: 5514
   udp: true
   tcp: true

plugins/syslog/receiver.py

@@ -27,6 +27,7 @@ from sqlalchemy import func, select
 
 from steward.core.scheduler import ScheduledTask
 
+from .network import on_own_network
 from .parse import MAX_MESSAGE, Message, frames, parse
 
 if TYPE_CHECKING:
@@ -128,6 +129,14 @@ def settings(app: "Quart") -> tuple[int, bool, bool]:
     return int(cfg.get("port", 5514)), bool(cfg.get("udp", True)), bool(cfg.get("tcp", True))
 
 
+def send_to(app: "Quart") -> str:
+    """The address the set-up help tells devices to send to, as set in the
+    plugin's settings: the web address Steward is reached by is often a name
+    only its proxy answers, so it isn't guessed from that."""
+    cfg = (app.config.get("PLUGINS") or {}).get("syslog") or {}
+    return str(cfg.get("send_to") or "").strip()
+
+
 async def close() -> None:
     if LISTENER._udp_transport is not None:
         LISTENER._udp_transport.close()
@@ -218,32 +227,43 @@ async def _store(app: "Quart", rounds: list[list[Received]]) -> None:
             await store_lines(session, [line for lines in rounds for line in lines])
 
 
+def sender_of(line: Received) -> tuple[str, str]:
+    """(address, sender) a line is filed under. A line from Docker's own
+    address (a port published on Swarm's ingress) is any device's, so the
+    name it carries tells the device; elsewhere the address alone does, and
+    a device renamed stays one source."""
+    if on_own_network(line.address):
+        return line.address, line.message.hostname[:255]
+    return line.address, ""
+
+
 async def store_lines(session, lines: list[Received]) -> None:
     from .models import SyslogLine, SyslogSource
 
     if not lines:
         return
-    by_address: dict[str, list[Received]] = {}
+    by_sender: dict[tuple[str, str], list[Received]] = {}
     for line in lines:
-        by_address.setdefault(line.address, []).append(line)
-    sources = {s.address: s for s in (await session.execute(
-        select(SyslogSource).where(SyslogSource.address.in_(list(by_address))))).scalars()}
-    new = [a for a in by_address if a not in sources]
+        by_sender.setdefault(sender_of(line), []).append(line)
+    addresses = list({address for address, _ in by_sender})
+    sources = {(s.address, s.sender): s for s in (await session.execute(
+        select(SyslogSource).where(SyslogSource.address.in_(addresses)))).scalars()}
+    new = [k for k in by_sender if k not in sources]
     if new:
         known = (await session.execute(select(func.count()).select_from(SyslogSource))).scalar_one()
-        for address in new:
+        for key in new:
             if known >= MAX_SENDERS:
-                LISTENER.unoffered += len(by_address.pop(address))
+                LISTENER.unoffered += len(by_sender.pop(key))
                 continue
-            first = by_address[address][0]
-            source = SyslogSource(address=address, first_seen_at=first.at, last_seen_at=first.at)
+            first = by_sender[key][0]
+            source = SyslogSource(address=key[0], sender=key[1], first_seen_at=first.at, last_seen_at=first.at)
             session.add(source)
-            sources[address] = source
+            sources[key] = source
             known += 1
         await session.flush()
 
-    for address, received in by_address.items():
-        source = sources[address]
+    for key, received in by_sender.items():
+        source = sources[key]
         newest = received[-1]
         source.lines_total = (source.lines_total or 0) + len(received)
         source.last_seen_at = max(source.last_seen_at, newest.at) if source.last_seen_at else newest.at

plugins/syslog/routes.py

@@ -23,7 +23,7 @@ from .network import on_own_network
 from .parse import SEVERITIES, facility_name, severity_name
 from .patterns import (PRESETS, PRESETS_BY_KEY, SOURCE_MODULE, WINDOWS, PatternError, key_for, parse_form,
                        resource_of)
-from .receiver import LISTENER, MAX_SENDERS, settings
+from .receiver import LISTENER, MAX_SENDERS, send_to, settings
 from .service import (AROUND_LINES, AROUND_SEVERITY, MARK_SEVERITY, MAX_MARKS, PANEL_LINES, PANEL_SPAN,
                       SEVERITY_CHOICES, apps_of, filtered, line_filter, lines_between, place_for, rates, shown_on,
                       source_name)
@@ -55,7 +55,7 @@ def listener_view(port: int, udp: bool, tcp: bool) -> dict:
 
 def source_view(s: SyslogSource, hosts: dict, rate: int | None = None) -> dict:
     host = hosts.get(s.host_id) if s.host_id else None
-    return {"id": s.id, "address": s.address, "state": s.state, "rate": rate,
+    return {"id": s.id, "address": s.address, "sender": s.sender, "state": s.state, "rate": rate,
             "docker_address": on_own_network(s.address),
             "name": s.name or s.hostname_seen or s.address,
             "hostname_seen": s.hostname_seen, "host": host,
@@ -66,7 +66,11 @@ def source_view(s: SyslogSource, hosts: dict, rate: int | None = None) -> dict:
 
 
 def suggested_host(source: SyslogSource, hosts: list) -> str | None:
-    """The host whose address is the sender's, if one is."""
+    """The host whose address is the sender's, if one is; for a device that
+    reaches Steward through Docker's address, the host of the name it gives."""
+    if source.sender:
+        name = source.sender.lower()
+        return next((h.id for h in hosts if name in (h.name.lower(), (h.address or "").lower())), None)
     return next((h.id for h in hosts if h.address == source.address), None)
 
 
@@ -91,7 +95,7 @@ async def index():
     return await render_template("syslog/index.html", listener=listener,
                                  sources=views["accepted"], offered=views["offered"],
                                  ignored=views["ignored"], hosts=hosts,
-                                 server=request.host.rsplit(":", 1)[0] if request.host.count(":") == 1 else request.host,
+                                 server=send_to(current_app),
                                  now=datetime.now(timezone.utc))
 
 

plugins/syslog/templates/syslog/index.html

@@ -34,36 +34,43 @@
   {% if listener.senders_full %}<p class="tone-warn" style="margin:0.4rem 0 0;">Steward knows {{ listener.max_senders }} senders, the most it keeps; a new one is counted, not offered{% if listener.unoffered %} ({{ "{:,}".format(listener.unoffered) }} line{{ "s" if listener.unoffered != 1 }} so far){% endif %}. Remove ones you don't need.</p>{% endif %}
 </section>
 
-{% set hidden_senders = (offered + sources)|selectattr("docker_address")|list %}
-{% if hidden_senders %}
-<p class="tone-warn" role="status">{{ hidden_senders|map(attribute="address")|unique|join(", ") }} {{ "is" if hidden_senders|map(attribute="address")|unique|list|length == 1 else "are" }} on Steward's own container network: Docker is most likely standing in for the real devices, so they all read as one sender. Publish the port in host mode, as <a href="#syslog-setup">Point a device here</a> shows.</p>
+{% set unnamed = (offered + sources)|selectattr("docker_address")|rejectattr("sender")|list %}
+{% if unnamed %}
+<p class="tone-warn" role="status">Lines from {{ unnamed|map(attribute="address")|unique|join(", ") }} come through Docker's own address and carry no device name, so the devices sending them can't be told apart. Have each device put its hostname in its lines, or publish the port in host mode, as <a href="#syslog-setup">Point a device here</a> shows.</p>
 {% endif %}
 
 <details class="card" id="syslog-setup"{% if not sources and not offered %} open{% endif %}>
   <summary class="section-title" style="cursor:pointer;">Point a device here</summary>
   {% set port = listener.port %}
   {% set proto = listener.protocols|join(" or ") or "UDP or TCP" %}
-  <p style="margin:0.75rem 0 0.5rem;">In the device's remote syslog settings, send to <span class="mono">{{ server }}</span>, port <span class="mono">{{ port }}</span>, {{ proto }}. If the device can't resolve that name, use the server's IP address. Choose the RFC 5424 (IETF) format where it is offered: its lines carry their zone. Once a device sends, it appears above as sending, and Add keeps its lines.</p>
+  {% set to = server or "ADDRESS" %}
+  <p style="margin:0.75rem 0 0.5rem;">In the device's remote syslog settings, send to {% if server %}<span class="mono">{{ server }}</span>{% else %}the IP address of a Docker host that publishes the port (<span class="mono">ADDRESS</span> below; set it under Settings → Plugins → Syslog, "Send to"){% endif %}, port <span class="mono">{{ port }}</span>, {{ proto }}. Either syslog format is read: the BSD one (RFC 3164) or the IETF one (RFC 5424), which is better where a device offers the choice, as its lines carry their zone. Once a device sends, it appears above as sending, and Add keeps its lines.</p>
   <table class="table" style="width:100%;font-size:0.82rem;">
     <thead><tr><th>Device</th><th>Where</th></tr></thead>
     <tbody>
-      <tr><td>Synology (DSM)</td><td>Log Center → Log Sending: send logs to a syslog server, with the server, port, protocol and the IETF format.</td></tr>
+      <tr><td>Synology (DSM)</td><td>Log Center → Log Sending: send logs to a syslog server, with the server, port and protocol. Choose the IETF format if it is offered.</td></tr>
+      <tr><td>ASUSTOR (ADM)</td><td>In ADM's system log settings, send logs to a syslog server, with the server, port and protocol. ADM offers no format choice; Steward reads the BSD format it sends.</td></tr>
       <tr><td>QNAP (QTS)</td><td>QuLog Center → Log Sender: add a destination with the server, port, protocol and RFC 5424.</td></tr>
-      <tr><td>TrueNAS</td><td>System → Advanced Settings → Syslog: the remote syslog server as <span class="mono">{{ server }}:{{ port }}</span>, and its transport.</td></tr>
+      <tr><td>TrueNAS</td><td>System → Advanced Settings → Syslog: the remote syslog server as <span class="mono">{{ to }}:{{ port }}</span>, and its transport.</td></tr>
       <tr><td>OpenWrt</td><td>System → System → Logging: the external system log server, its port and protocol.</td></tr>
       <tr><td>UniFi</td><td>Network settings, under remote logging (named Activity Logging or SIEM server in newer versions): the server and port.</td></tr>
-      <tr><td>Linux (rsyslog)</td><td><span class="mono">*.* @{{ server }}:{{ port }}</span> (UDP) or <span class="mono">*.* @@{{ server }}:{{ port }}</span> (TCP) in <span class="mono">/etc/rsyslog.d/90-steward.conf</span>, then restart rsyslog.</td></tr>
+      <tr><td>Linux (rsyslog)</td><td><span class="mono">*.* @{{ to }}:{{ port }}</span> (UDP) or <span class="mono">*.* @@{{ to }}:{{ port }}</span> (TCP) in <span class="mono">/etc/rsyslog.d/90-steward.conf</span>, then restart rsyslog.</td></tr>
     </tbody>
   </table>
   <h3 class="section-title" style="margin:1rem 0 0.4rem;font-size:0.9rem;">Nothing arriving?</h3>
   <ul class="field-hint" style="margin:0;padding-left:1.1rem;">
-    <li>Steward's container must publish port {{ port }}. In Docker Swarm publish it in <strong>host mode</strong>: through Swarm's default ingress every device reaches Steward from one internal address and can't be told apart.</li>
+    <li>Steward's service must publish port {{ port }}, for UDP and TCP both. In Docker Swarm, either way works:
+      <ul style="padding-left:1.1rem;">
+        <li><strong>Ingress</strong> (Swarm's default; Steward can move between nodes): send to any node's address, or an address shared over the nodes. Every line then arrives from Docker's own address, so Steward tells the devices apart by the hostname in their lines; a device must send one.</li>
+        <li><strong>Host mode</strong> (add <span class="mono">mode: host</span>): each device keeps its own address, but only the node running Steward answers, so send to that node.</li>
+      </ul>
+    </li>
     <li>A firewall on the server, or between the device's network and the server's, may drop it.</li>
     <li>Ports below 1024, such as syslog's usual 514, can't be opened by Steward. Map 514 to {{ port }} where the port is published, or point devices at {{ port }}.</li>
   </ul>
   <pre class="mono" style="margin:0.6rem 0 0;font-size:0.78rem;white-space:pre-wrap;">ports:
-  - { target: {{ port }}, published: {{ port }}, protocol: udp, mode: host }
-  - { target: {{ port }}, published: {{ port }}, protocol: tcp, mode: host }</pre>
+  - { target: {{ port }}, published: {{ port }}, protocol: udp }
+  - { target: {{ port }}, published: {{ port }}, protocol: tcp }</pre>
 </details>
 
 {% if offered %}
@@ -75,15 +82,15 @@
     <tbody>
     {% for s in offered %}
     <tr>
-      <td><span class="mono">{{ s.address }}</span>{% if s.hostname_seen %}<div class="field-hint">calls itself {{ s.hostname_seen }}</div>{% endif %}{% if s.docker_address %}<div class="tone-warn" style="font-size:0.78rem;">Docker's address, not the device's</div>{% endif %}</td>
+      <td>{% if s.sender %}<span class="mono">{{ s.sender }}</span><div class="field-hint">through Docker's ingress, {{ s.address }}</div>{% else %}<span class="mono">{{ s.address }}</span>{% if s.hostname_seen %}<div class="field-hint">calls itself {{ s.hostname_seen }}</div>{% endif %}{% if s.docker_address %}<div class="tone-warn" style="font-size:0.78rem;">Docker's address, not the device's</div>{% endif %}{% endif %}</td>
       <td>{{ "{:,}".format(s.lines_total) }}</td>
       <td>{{ s.last_seen_at|ago }}</td>
       <td class="mono" style="max-width:28rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;" title="{{ s.last_line }}"><span class="{{ tone(s.level) }}">{{ s.severity or "" }}</span> {{ s.last_line or "—" }}</td>
       {% if admin %}
       <td style="white-space:nowrap;">
         <form method="post" action="/plugins/syslog/sources/{{ s.id }}/add" style="display:inline-flex;gap:0.4rem;align-items:center;margin:0;">{{ csrf_field() }}
-          <input class="input" name="name" aria-label="Name for {{ s.address }}" maxlength="100" value="{{ s.hostname_seen or '' }}" placeholder="Name" style="width:9rem;">
-          <select class="input" name="host_id" aria-label="Host for {{ s.address }}" style="width:9rem;">
+          <input class="input" name="name" aria-label="Name for {{ s.sender or s.address }}" maxlength="100" value="{{ s.hostname_seen or '' }}" placeholder="Name" style="width:9rem;">
+          <select class="input" name="host_id" aria-label="Host for {{ s.sender or s.address }}" style="width:9rem;">
             <option value="">No host</option>
             {% for h in hosts %}<option value="{{ h.id }}"{% if s.suggested_host == h.id %} selected{% endif %}>{{ h.name }}</option>{% endfor %}
           </select>
@@ -114,7 +121,7 @@
     <tbody>
     {% for s in sources %}
     <tr>
-      <td><a href="/plugins/syslog/sources/{{ s.id }}">{{ s.name }}</a><div class="field-hint mono">{{ s.address }}</div>{% if s.docker_address %}<div class="tone-warn" style="font-size:0.78rem;">Docker's address, not the device's</div>{% endif %}</td>
+      <td><a href="/plugins/syslog/sources/{{ s.id }}">{{ s.name }}</a><div class="field-hint mono">{{ s.address }}</div>{% if s.sender %}<div class="field-hint">through Docker's ingress</div>{% elif s.docker_address %}<div class="tone-warn" style="font-size:0.78rem;">Docker's address, not the device's</div>{% endif %}</td>
       <td>{% if s.host %}<a href="/hosts/{{ s.host.id }}">{{ s.host.name }}</a>{% else %}—{% endif %}</td>
       <td class="num">{{ "{:,}".format(s.rate or 0) }}</td>
       <td>{{ s.last_seen_at|ago }}</td>
@@ -135,7 +142,7 @@
     <tbody>
     {% for s in ignored %}
     <tr>
-      <td><span class="mono">{{ s.address }}</span>{% if s.hostname_seen %}<div class="field-hint">calls itself {{ s.hostname_seen }}</div>{% endif %}</td>
+      <td><span class="mono">{{ s.sender or s.address }}</span>{% if s.sender %}<div class="field-hint">through Docker's ingress, {{ s.address }}</div>{% elif s.hostname_seen %}<div class="field-hint">calls itself {{ s.hostname_seen }}</div>{% endif %}</td>
       <td>{{ "{:,}".format(s.lines_total) }}</td>
       <td>{{ s.last_seen_at|ago }}</td>
       {% if admin %}<td><form method="post" action="/plugins/syslog/sources/{{ s.id }}/offer" style="margin:0;">{{ csrf_field() }}<button type="submit" class="btn btn-sm btn-ghost">Offer again</button></form></td>{% endif %}