The Connected Host Metadata workflow joins a switch’s MAC forwarding table and LLDP neighbor table against Nautobot’s host inventory to produce a per-interface picture of what is connected to the device. It is the standard tool for spot-checking what is actually plugged into a switch — useful when bringing up a new device, debugging a host that is not appearing where expected, or validating that Nautobot’s modeled hosts match reality.
Before running the workflow, confirm the following are in place:
After submission, a status page appears showing the three stages. A typical run completes in well under a minute.
The workflow runs three stages. The first two are independent and run in parallel; the third waits on both. None of the stages require manual approval.
get_device_mac_table — Read the FDB from the device.
Queries the device for its MAC forwarding table, drops entries without a VLAN (typically CPU/local MACs), and renders the result as a Markdown table of (Interface, MAC, VLAN). On an empty FDB the stage display reads “No MAC Addresses found on device.” rather than failing.
get_device_neighbors — Read the LLDP neighbor table from the device.
Queries the device for its LLDP neighbors and renders (Interface, Neighbor Device, Neighbor Interface, Link Status). On an empty table the stage display reads “No LLDP neighbors found on device.” rather than failing.
get_connected_host_data — Join MAC + LLDP against Nautobot.
Depends on the prior two stages. For each interface with a MAC or LLDP entry, the workflow:
Looks up hosts by MAC via get_host_data_by_macs.
Looks up hosts by device name via get_host_data_by_names (used when the LLDP neighbor name resolves to a Nautobot host).
For each interface with multiple MAC candidates, prefers the entry whose MAC matches a known Nautobot host; otherwise prefers the youngest FDB entry.
Emits a final table with columns: Network Interface, Host, LLDP Name, Alias, Connected Interface, MAC Address, Tenant, VLAN.
If both the FDB and LLDP stages returned empty data, this stage short-circuits to UNREACHABLE rather than running a join.
The workflow archives the result before completing. Activity timeouts are short (1 minute) with up to 3 retries on transient errors.
After the workflow reports success, confirm:
Stage 1 or 2 reports UNREACHABLE.
The device was not reachable or the management credentials were wrong. Verify the device is up on its management IP and that Config Manager’s site credentials are current. The Monitoring DHCP and ZTP section of New Site Bringup has the canonical reachability troubleshooting path.
Host columns are empty (--) for interfaces where I expect a host.
Either the MAC on the wire does not match any host in Nautobot, or the host has been renamed/moved. Confirm the MAC the FDB reports and reconcile it against Nautobot. For hosts modeled by name (LLDP-derived), confirm the LLDP system name matches the Nautobot device name exactly.
An interface shows different MACs across runs.
The FDB is unstable — typically a trunk port where multiple hosts share the segment, or a server churning through MACs (PXE retries, link flap). Investigate the neighbor rather than retrying the workflow.
Both stages return empty data.
The workflow short-circuits and marks get_connected_host_data as UNREACHABLE. Confirm the device has any live ports — a switch with no traffic and LLDP disabled has nothing to report.