Read-only switch and virtualization collectors

Bring network switches and virtual machines into Renga’s observed inventory without installing anything on them. RFD 1 calls for protocol-first switch collection and read-only VM collection starting with libvirt/KVM; this RFD designs both as collectors that report through the same observation API, so reconciliation, freshness, findings, and the four collection clocks retain their meanings, with inventory clocks scoped to each collector stream.

Read-only means exactly that: no collector in this RFD changes device or hypervisor configuration. VM lifecycle operations are RFD 14.

Collectors run inside the existing renga-agent binary as optional modules, configured per installation:

Reusing the agent gives every collector the installation identity, intake key, on-disk queue, check-ins, and packaging already shipped. An installation can run host, SNMP, and libvirt collection together; it never retypes its host source or moves historical observations to a different source.

This extends RFD 3's one-source-per-installation registration contract. The installation keeps one Agent and its existing host source. Additional streams have server-resolved Sources keyed by organization, installation UUID, and a stable locally configured collector ID, with immutable kind (switch_poller or vm_provider). Multiple instances of a module use distinct collector IDs; changing a target address does not change its stream identity. Omitting the collector ID preserves the existing host API. Every queued observation retains its collector ID so replay resolves to the original source, not whichever module is currently enabled.

Contact and lease belong to the installation. Accepted and reconciled inventory clocks belong to each stream, with freshness and completeness tracked for its reported targets or hypervisor. Host check-ins or successful host reports cannot make stale switch or libvirt evidence fresh. Registering/removing streams does not silently transfer or retire another stream’s evidence.

Device credentials stay on the collector host, read from files the agent’s service account can read. They are never sent to Renga, never logged, and never appear in observations.

Today an observation must contain exactly one host resource. Provider observations need many resources per report: one per switch polled or VM listed. The payload gains a scope that says what the report is authoritative for:

Partial, paginated, or failed collection never marks inventory absent (RFD 1). Only a complete, successful report for a scope can retire what that scope no longer contains.

SNMP comes first because nearly every switch supports it read-only. The first release reads:

SNMPv3 with authentication and privacy is the default. SNMPv2c is allowed for lab gear only with an explicit allow_v2c = true. gNMI/OpenConfig is a later module behind the same payload, for switches where SNMP is incomplete.

A switch’s identity is its chassis serial number, with the LLDP chassis ID and management address as supporting identifiers, so a switch reported by two pollers reconciles to one resource.

libvirt comes first, read-only, over the local socket on each hypervisor (an agent already runs there) or a read-only remote URI. It reports:

A VM is correlated with the host agent running inside it by the SMBIOS system UUID that libvirt assigns and the guest agent reports as dmi_uuid, with MAC addresses as supporting evidence. When both exist they reconcile to one resource with two sources, the hypervisor’s view and the guest’s own, rather than two machines. Either side may report first.

The sandboxed agent cannot read the DMI UUID itself, because /sys/class/dmi/id/product_uuid is root-only. Guests report dmi_uuid from the SMBIOS snapshot that RFD 10 defines, so that snapshot is a prerequisite of automatic correlation. A guest without it keeps an empty dmi_uuid and is never matched by UUID.

MAC addresses alone never merge two resources, because they are reassigned, cloned with images, and spoofable. When a guest without a usable UUID shares every MAC address of exactly one fresh domain, Renga opens a "possible same machine" finding carrying that evidence. An operator confirms it, merging the resources as an operator’s assertion, or dismisses it, which suppresses that pairing.

Defined-on and active placement are different evidence. An inactive persistent domain may remain defined on the source after migration; that definition does not claim current execution there. Active domain state (including paused domains that still occupy the host), observation time, and the stream’s freshness determine execution placement. A complete report that a domain is inactive or absent withdraws only that source’s active-placement claim.

A migrated VM moves without an operator touching it when sufficiently fresh active evidence identifies one hypervisor. Competing fresh active claims open a finding and leave placement ambiguous; stale or missing evidence leaves it unknown. Renga never picks an arbitrary hypervisor, and privileged operations (RFD 14) cannot treat inactive definitions as active placement or use ambiguous placement to select their target. Starting an inactive VM instead requires the explicitly approved provider/domain binding defined in RFD 14.

Each module polls on its own interval (default 15 minutes for SNMP, 5 for libvirt), within per-target timeouts and a cap on concurrent targets. A slow switch can never hold up host inventory or lease check-ins, because modules run on their own worker like RFD 9 jobs. Each report respects the observation size limit by splitting large target sets across several reports.

Cloud provider APIs, VMware vCenter, Proxmox and Hyper-V APIs, SNMP traps, streaming telemetry, and any write operation. Each later provider reuses the payload scopes above.

Progress is tracked in the implementation checklist.