Devices & Discovery

FreeSDN maintains a single unified device inventory that merges every discovery method into one list: server-initiated subnet scans, agent-assisted L2/L3 sweeps, and controller-reported devices all land in the same place. This page explains how discovery works, how to run a scan, what auto-adopt does, and how to bring a discovered device under full management.

Site scope required for Discovery

The Discovery sidebar item only appears when a specific site is selected in the Site selector, not in “All Sites” mode. Discovery is always scoped to a site.

---

The unified device inventory

/devices/ is the authoritative device inventory for your organization. It shows every device FreeSDN knows about regardless of how it was found - whether a controller reported it, an agent scanned it, or a server-side ICMP/SNMP sweep found it. The list is not a snapshot; it reflects the current known state and updates in real time via WebSocket.

Each row in the inventory shows:

• Identity - hostname, MAC address, IP address
• Status - online / offline / adopting / provisioning / error (the full lifecycle state machine)
• Site - which site the device is associated with
• Type - device class (switch, access point, camera, phone, firewall, server, unknown)
• Controller - which adapter/controller reported or manages the device, if any
• Last seen - timestamp of the most recent heartbeat or poll

Navigating into a device (/devices/{id}) opens a per-device detail view with identity, health gauges, port status, network info, and management actions such as reboot.

Device lifecycle states

Devices move through a defined state machine. The /lifecycle/ page visualizes this:

State	Meaning
discovered	Found by a scan; not yet adopted
adopting	Adoption initiated; controller provisioning in progress
provisioning	Configuration being pushed
managed	Fully under FreeSDN management
updating	Firmware or config update in progress
offline	Was managed; not responding to polls
error	Adoption or provisioning failed
decommissioned	Manually marked end-of-life

---

Discovery: how devices get found

FreeSDN has three discovery paths. They are not mutually exclusive - you can run all three in parallel.

1. Server-side subnet scan (network tab)

A server-initiated 4-phase async pipeline runs directly from the FreeSDN backend:

1. Protocol Discovery - mDNS/DNS-SD and SSDP/UPnP broadcasts surface advertising devices before any unicast probing begins
2. Port Scanning - async TCP connect against common management ports (22, 23, 80, 443, 554, 8080, 8443, and controller-specific ports), batched for concurrency
3. Service Probing - HTTP/HTTPS title and server-header fingerprinting plus RTSP OPTIONS for cameras and NVRs; vendor is inferred from page content and response headers
4. Hostname Resolution - reverse DNS lookup for all discovered IPs

To run a scan:

1. Go to /discovery/ (requires a site to be selected).
2. Open the Network tab.
3. Enter a CIDR range (e.g., 192.168.1.0/24) or pick a preset.
4. Click Start scan.
5. Watch the per-phase progress bars and the live discovered-device card feed.

Scan history is accessible in the history panel on the same page. Each run records the CIDR, start/end time, phase results, and discovered count.

Scan depth and timing

Large subnets (/16 or wider) can generate significant traffic and take many minutes to complete. Start with a narrow target range and expand only when needed.

2. Agent-assisted scan (agent tab)

The freesdn-agent (MIT, alpha) is a lightweight daemon that runs on a machine inside the target network segment. Because it runs on-site, it can reach L2 segments not accessible to the FreeSDN server, and its OS-level scanners produce deeper fingerprinting.

The agent exposes 14 active discovery scanners and 5 passive listeners. Active scanners include ARP, ICMP, SNMP, mDNS/Bonjour, LLDP/CDP neighbor detection, and others. Passive listeners capture DHCP leases and broadcast announcements.

To dispatch an agent scan:

1. Go to /discovery/ and open the Agent tab, or navigate to /agents/{id}/ directly.
2. Select the registered agent that covers the target site.
3. Configure the scan (target range, scanner selection).
4. Click Run scan - the job is dispatched over the live WebSocket connection and progress is reflected in real time.

Agents self-update via an ECDSA-P256 signed release channel. Updates are fail-closed: if the signature does not verify, the agent does not apply the update.

For agent installation and registration, see /agents/downloads/ (installer packages for Windows, macOS, and Linux) and the Agent guide.

Agent vs server-side scan

Use the agent tab when the target segment is not routable from the FreeSDN server (e.g., an isolated VLAN, a remote office without a VPN back to the FreeSDN host). Server-side scans are simpler to operate and sufficient for flat or well-routed networks.

3. Controller-reported devices (controllers tab)

When you register a network controller (Omada, UniFi, or similar) at /controllers/, FreeSDN polls it on a recurring schedule and imports its device list. Devices the controller already knows about appear in the inventory with a controller association and typically arrive in the managed state immediately, since the controller has already adopted them.

The Controllers tab on the Discovery page shows the adapters available to poll and lets you trigger an immediate sync.

---

The Discovered tab: reviewing scan results

After any scan completes, results appear in the Discovered tab. Each card shows:

• IP, MAC, hostname
• Vendor and driver match confidence (the fingerprinting engine attempts to match the device signature against the 6 registered discovery drivers: Omada, Hikvision, OPNsense, pfSense, MikroTik, or generic fallback)
• Suggested device type
• A 3-step adoption wizard button

You can view results as a grid or list. The toolbar lets you filter by confidence level, device type, and vendor.

Driver matching is the process by which FreeSDN maps a discovered device to a specific adapter. A high-confidence match means the fingerprint (sysObjectID, HTTP server header, mDNS service type, etc.) strongly identifies the vendor and model. A low-confidence match means FreeSDN has a candidate but cannot be certain. You can manually override the driver assignment in the adoption wizard.

---

Adopting a device

“Adopting” means moving a device from the discovered state into the management pipeline so FreeSDN can push configuration, poll status, and include it in reports and alerts.

Manual adoption (3-step wizard)

1. In the Discovered tab, click Adopt on a device card.
2. Step 1 - Confirm identity: review or edit the detected hostname, IP, and device type. Assign the device to a site.
3. Step 2 - Assign driver: confirm or override the driver match. If the device type matches a module (cameras, VoIP, switches), the appropriate adapter is listed. Select credentials from the vault (/credentials/) or enter them inline.
4. Step 3 - Review and confirm: FreeSDN tests the connection using the supplied credentials. A green check means reachability is confirmed. Click Adopt to submit.

After submission the device enters the adopting state. A Celery task contacts the device using the adapter’s provisioning flow. On success the device transitions to provisioning and then managed.

Credentials required for management

Discovery itself does not need device credentials. Adoption does - FreeSDN must authenticate to the device to push configuration and poll status. Store credentials in the vault at /credentials/ before starting adoption at scale.

Bulk adoption

The Discovered tab toolbar has a Bulk adopt option. Select multiple device cards (checkbox on each card), click Bulk adopt, and confirm. Bulk adoption applies the same driver selection and site assignment to all selected devices. Use this when scanning a homogeneous segment (e.g., a floor of identical switches or a rack of IP cameras).

Auto-adopt

Auto-adopt eliminates the manual step for high-confidence discoveries. When enabled for a site, devices that score above the confidence threshold are automatically adopted as soon as they are discovered, without requiring an operator to click through the wizard.

To enable auto-adopt for a site:

1. Go to /sites/{siteId}/ and open the Settings tab.
2. Toggle Auto-adopt high-confidence discoveries on.

Auto-adopt is opt-in and site-scoped

Auto-adopt is disabled by default. It acts only on devices whose fingerprint confidence exceeds the threshold - low-confidence matches are always held for manual review even when auto-adopt is on. Enable it only on sites where your scan targets are well-understood (known subnet, known vendor population).

---

Key API endpoints

The discovery and inventory surfaces are backed by the following REST endpoints (all under /api/v1/; full reference at /api/v1/docs/):

Method	Path	Purpose
GET	/devices/	List managed devices (org-scoped, filterable by site/status/type)
GET	/devices/{id}	Single device detail
PATCH	/devices/{id}	Update device metadata (hostname, site, tags)
POST	/devices/{id}/reboot	Reboot a managed device
GET	/discovery/scans/history	List scan history
POST	/discovery/scan	Start a new server-side subnet scan
GET	/discovery/scan/{id}/progress	Poll live scan progress
GET	/discovery/scan/{id}/results	Retrieve scan results (completed or in-progress)
GET	/discovery/discovered-hosts	List discovered (not-yet-adopted) devices from recent scans
POST	/discovery/adopt	Adopt a single discovered device
POST	/discovery/adopt/bulk	Bulk-adopt multiple discovered devices
GET	/agents/	List registered agents
POST	/agents/{id}/scan	Dispatch a scan to a specific agent over WebSocket

---

Permissions

Action	Required permission
View device inventory	device:read
Update device metadata	device:update
Adopt or bulk-adopt devices	discovery:write
Start a server-side scan	discovery:run
Dispatch an agent scan	agent:write
Manage agent binaries/releases	agent:admin
Configure auto-adopt (site settings)	site_admin role or higher

---

Topology view

The Topology tab on the Discovery page shows discovered devices plotted on an interactive network graph. The full topology explorer is at /topology/ (site-only, Network module required). The topology view uses live controller data to draw L2 connections between switches, access points, and uplinks. See the Network module reference for details.

---

Keeping the inventory current

Discovery is not a one-time operation. Devices are added, removed, and reassigned over time. Recommended practices:

1. Schedule recurring agent scans - the agent supports cron-scheduled scans via its configuration. Set a nightly or weekly scan on each segment to catch new hardware.
2. Register controllers - controller-polled devices update automatically on the controller’s sync interval (configurable per controller at /controllers/{id}/). This is the lowest-effort path for networks already managed by Omada or UniFi.
3. Use the Health dashboard - /health/ surfaces devices that have gone offline since last seen, which may indicate newly decommissioned or unreachable hardware that needs lifecycle action.
4. Act on the Lifecycle page - /lifecycle/ shows devices stuck in error or adopting states. Address these before running a new discovery sweep to avoid duplicate adoption attempts.

No PostgreSQL RLS

Multi-tenancy is enforced at the application layer: queries are org-scoped (fail-closed) in the service layer, and per-user site grants are enforced across the site-scoped modules. There is no PostgreSQL Row-Level Security. Do not assume database-level isolation; the isolation guarantee is the application authorization layer.

---

Next steps

• Register your first controller - go to /controllers/ or follow the Quick Start guide to wire FreeSDN to an Omada or UniFi controller and import its existing device list without a manual scan.
• Install an agent - download the installer at /agents/downloads/ and follow the Agent guide for L2-segment and remote-site discovery.
• Explore module-specific device pages - once a device is adopted, the relevant module opens richer management surfaces: /switches/ and /access-points/ for network devices, /cameras/ for cameras, /voip/phones/ for IP phones.
• Set up automation - use the Automation & Fabric guide to trigger workflows (alerts, notifications, config pushes) when a device changes state, goes offline, or is adopted.
• Manage device config - see Configuration & Reconciliation for config templates, drift detection, and the reconciliation engine.