diff --git a/plugins/snmp/plugin.yaml b/plugins/snmp/plugin.yaml index ba8d8a6..7ef3683 100644 --- a/plugins/snmp/plugin.yaml +++ b/plugins/snmp/plugin.yaml @@ -15,6 +15,16 @@ tags: config: poll_interval_seconds: 60 # Each device is polled independently. OIDs must resolve to numeric values. + # + # `host` is the SNMP poll target (IP/hostname we query). A device also shows + # up on a Steward Host's detail page when it maps to that host. By default + # that mapping is implicit: `host` is matched against the Host's address or + # name. To bind explicitly instead — e.g. when you poll by IP but the Host is + # recorded by DNS name, or for an SNMP-only switch/PDU/UPS — add ONE of: + # host_id: "" # exact Host.id match + # steward_host: "switch01" # Host name OR address (case-insensitive) + # An explicit binding is exclusive: the device then maps ONLY to that host, + # never implicitly to another by a coincidental address string. devices: - name: "core-switch" host: "192.168.1.1" diff --git a/plugins/snmp/routes.py b/plugins/snmp/routes.py index 6dc19f6..6157338 100644 --- a/plugins/snmp/routes.py +++ b/plugins/snmp/routes.py @@ -93,15 +93,40 @@ async def index(): poll_interval=poll_interval) -def _devices_for_host(devices_cfg: list, address: str | None, name: str | None) -> list[dict]: - """SNMP devices whose configured `host` matches a Steward host's address or - name (case-insensitive). SNMP devices are config-defined by IP/hostname, so - this is how they map onto a host's page.""" +def _device_binds_to_host(d: dict, keys: set[str], host_id: str) -> bool: + """Does config device `d` belong on the host identified by `keys` + (lowercased {address, name}) / `host_id`? + + A device may declare an **explicit** binding that decouples "which Steward + host this belongs to" from "where to poll" (the `host` field): + • `host_id` — the Steward Host UUID (exact match), the explicit link. + • `steward_host` — a friendly bind by Host name or address (case-insensitive). + An explicit binding is **exclusive**: a device bound to host A must not also + match host B by a coincidental poll-target string. Only when no explicit + binding is present do we fall back to the implicit `host`-string match + (backward compatible with configs that only set `host`). + """ + explicit_id = str(d.get("host_id", "")).strip() + explicit_name = str(d.get("steward_host", "")).strip().lower() + if explicit_id or explicit_name: + if explicit_id and host_id and explicit_id == host_id: + return True + return bool(explicit_name and explicit_name in keys) + return str(d.get("host", "")).strip().lower() in keys + + +def _devices_for_host(devices_cfg: list, address: str | None, name: str | None, + host_id: str | None = None) -> list[dict]: + """SNMP devices that map onto a Steward host's page. Prefers an explicit + per-device binding (`host_id` / `steward_host`); otherwise falls back to + matching the device's `host` (poll target) against the host's address or + name (case-insensitive). See `_device_binds_to_host` for the precedence.""" keys = {(address or "").strip().lower(), (name or "").strip().lower()} keys.discard("") + hid = (host_id or "").strip() return [ d for d in devices_cfg - if isinstance(d, dict) and str(d.get("host", "")).strip().lower() in keys + if isinstance(d, dict) and _device_binds_to_host(d, keys, hid) ] @@ -120,7 +145,7 @@ async def host_panel(host_id: str): select(Host).where(Host.id == host_id))).scalar_one_or_none() if host is None: return "" - matched = _devices_for_host(devices_cfg, host.address, host.name) + matched = _devices_for_host(devices_cfg, host.address, host.name, host.id) if not matched: return "" names = [d.get("name") or d.get("host", "?") for d in matched] @@ -131,6 +156,8 @@ async def host_panel(host_id: str): "host": d.get("host", ""), "oids": d.get("oids", []), "readings": latest.get(d.get("name") or d.get("host", "?"), {}), + "bound": bool(str(d.get("host_id", "")).strip() + or str(d.get("steward_host", "")).strip()), } for d in matched] return await render_template("snmp/host_panel.html", devices=devices) diff --git a/plugins/snmp/templates/snmp/host_panel.html b/plugins/snmp/templates/snmp/host_panel.html index 38166cc..42d471e 100644 --- a/plugins/snmp/templates/snmp/host_panel.html +++ b/plugins/snmp/templates/snmp/host_panel.html @@ -11,6 +11,10 @@
{{ device.name }} {{ device.host }} + {% if device.bound %} + bound + {% endif %} {% if device.readings %} ● reachable {% else %} diff --git a/tests/plugins/snmp/test_host_match.py b/tests/plugins/snmp/test_host_match.py index 282c7ea..7c02afb 100644 --- a/tests/plugins/snmp/test_host_match.py +++ b/tests/plugins/snmp/test_host_match.py @@ -27,3 +27,43 @@ def test_no_match_returns_empty(): def test_blank_address_and_name_match_nothing(): # A host with no address/name must not match a device with a blank host. assert _devices_for_host(_CFG, "", None) == [] + + +def test_implicit_match_unaffected_when_host_id_passed(): + # Passing the new host_id arg must not break the legacy implicit match. + out = _devices_for_host(_CFG, "192.168.1.1", "somehost", host_id="h-1") + assert [d["name"] for d in out] == ["core-switch"] + + +# ── Explicit binding ───────────────────────────────────────────────────────── + +def test_explicit_host_id_matches_exact_uuid(): + cfg = [{"name": "sw", "host": "10.0.0.5", "host_id": "uuid-abc"}] + out = _devices_for_host(cfg, "10.0.0.9", "other", host_id="uuid-abc") + assert [d["name"] for d in out] == ["sw"] + + +def test_explicit_steward_host_matches_by_name_or_address(): + cfg = [{"name": "pdu", "host": "10.0.0.5", "steward_host": "Switch01"}] + # Bind hits the Host's name despite a different poll target / address. + by_name = _devices_for_host(cfg, "10.0.0.9", "switch01", host_id="h9") + by_addr = _devices_for_host(cfg, "switch01", "whatever", host_id="h9") + assert [d["name"] for d in by_name] == ["pdu"] + assert [d["name"] for d in by_addr] == ["pdu"] + + +def test_explicit_binding_is_exclusive(): + # Device polls 192.168.1.1 but is explicitly bound to host A by name. + cfg = [{"name": "sw", "host": "192.168.1.1", "steward_host": "hostA"}] + # Host B *would* match implicitly by the poll target — but must NOT, + # because the explicit binding takes over and points only at host A. + hostB = _devices_for_host(cfg, "192.168.1.1", "hostB", host_id="b") + hostA = _devices_for_host(cfg, "10.0.0.2", "hostA", host_id="a") + assert hostB == [] + assert [d["name"] for d in hostA] == ["sw"] + + +def test_explicit_host_id_wrong_uuid_does_not_match(): + cfg = [{"name": "sw", "host": "10.0.0.5", "host_id": "uuid-abc"}] + out = _devices_for_host(cfg, "10.0.0.5", "sw", host_id="uuid-zzz") + assert out == []