Discovery

Discovery is the loop that turns a declared network into an inventory. The scheduler enqueues a scan, a daemon long-polls and picks it up, probes the range, and streams observations back while it works.

Declaring what to scan

Nothing is scanned until a network exists. Go to Networks → Add network and enter a CIDR, IPv4 or IPv6.

The one exception is LOOMSCOPE_NETWORK_CIDRS on a daemon, which exists for immutable deployments where the ranges are part of the host configuration. It is opt-in per host.

How a host is found

The sweep runs in both address families and combines four techniques, because no single one finds everything:

A host that answers nothing at all will not be found by active scanning. That is not a defect to work around; it is what SNMP collection, ARP tables from switches, and flow data are for. A printer with every port filtered still appears in its gateway's ARP table.

The ICMP privilege

The sweep needs exactly one privileged operation: sending an ICMP echo. When the daemon cannot, it degrades to TCP probes on 80, 443 and 22 — which finds web servers and misses everything that is up but serving nothing.

docker logs loomscope-daemon | grep "falling back to TCP"

If that matches, discovery is running at a fraction of its coverage and no number in the interface will look wrong. Deploying daemons covers both supported ways to grant it.

Port scanning

Once a host answers, the daemon probes ports. Defaults are the top 1 000 TCP ports and the top 50 UDP ports; the scan job carries both numbers, so a targeted scan can widen or narrow them without changing anything global.

UDP is deliberately shallow. An exhaustive UDP scan is slow, noisy and mostly inconclusive, and the ports that matter — 53, 123, 161, 500 — are in the first fifty.

Scan sessions

The Discovery page lists sessions with the daemon that ran each one, its target, and progress while it runs.

Running one on demand. Pick a network and a daemon, then Enqueue scan. The scheduler continues to run its own scans; an ad-hoc run does not disturb that.

Reading a stalled session. stalled means the daemon stopped reporting. Usually the process died or lost its route mid-scan. Nothing is lost — the next scheduled run picks the range back up — but a daemon that stalls repeatedly is worth investigating rather than ignoring.

How often scans run

The scheduler ticks every 30 seconds and enqueues whatever is due. Each network carries its own interval; the tick only ever enqueues a scan for a network that does not already have one queued or running, so a slow scan cannot pile up behind itself.

See Scheduled jobs for the full schedule and how to confirm it is running.

Progress while a scan runs

Observations stream back in batches rather than arriving at the end, so the host list fills as the scan works. The progress figure counts against hosts the sweep found, not against the size of the range — most of a /16 never answers, and a bar against the range would sit near zero and then jump.

What the daemon collects

One scan produces more than hosts and ports:

• Interfaces — names, MAC addresses, MTU, link speed
• Addresses — every v4 and v6 address seen on a host
• Services — signature matches with version, vendor, CPE and confidence
• Neighbours — LLDP and CDP adjacencies, where SNMP is configured
• VLANs, routing tables and link aggregation groups — from SNMP
• TLS certificates — from every handshake it performs
• Flows — from the NetFlow, IPFIX and sFlow listeners

All of it arrives as observations, which the control plane reconciles. The daemon never writes to the inventory directly, which is why a partial or duplicated scan cannot corrupt it.

SNMP

SNMP is what turns a network of guesses into a topology. It is also the only part of discovery that needs credentials.

Add them under Settings → Credentials, encrypted at rest with LOOMSCOPE_KMS_KEY. v1, v2c and v3 are supported; v3 with authentication and privacy is the one to use where the devices allow it.

With SNMP configured, discovery additionally collects interface tables, LLDP/CDP neighbours, VLAN membership, routing tables and LAG groups — which is what makes the L2 and L3 topology views real rather than inferred.

Flow collection

The daemon listens on UDP 2055 and 6343 by default (LOOMSCOPE_NETFLOW_PORTS) for NetFlow v5/v9, IPFIX and sFlow. Point your switches and routers at it.

Flows are what turn the application topology from "these services are on the same host" into "this service calls that one". Without them the application view draws lighter placeholder edges and says so.

Troubleshooting

Nothing is discovered at all. Does a network exist? Is the daemon online? Can it reach the range? Is it falling back to TCP?

Some hosts are missing. They may answer nothing. Check whether they appear in a gateway's ARP table via SNMP, or in flow data.

Hosts appear and disappear. Two daemons registered under the same name is the usual cause; each LOOMSCOPE_DAEMON_NAME must be distinct.

Scans queue but never run. No daemon is polling — check the daemon list, and check that the job worker is running.