Switch port lookup
switches.port_lookup finds which ICX switch port a device is plugged into, and
reports everything about that port: link, speed, PoE, errors, VLANs, 802.1X and
the other devices on it, with a list of what to check first. It is read-only and
open to every role. Ask Claude something like “which switch port is
172.16.128.40 plugged into?”, or pick Which switch port is it on? from
Claude’s + menu.
What can I look up?
Section titled “What can I look up?”Give one of these:
| Input | Finds |
|---|---|
mac | Any device, wired or wireless, from the switches’ MAC tables |
ip | A device by its IP address, matched across the MAC tables |
text | A device by its description or 802.1X user name, at least 2 characters |
apMac | The port an AP’s uplink is on, from the switches’ LLDP neighbours |
switchId + port | A port directly: the switch’s MAC and a port such as '1/1/7' |
A wireless client is in a switch’s MAC table only if its AP bridges traffic locally behind a managed switch. To find where a Wi-Fi client is connected, use the client journey.
Is this the device’s own port, or an uplink?
Section titled “Is this the device’s own port, or an uplink?”A switch’s MAC table lists, on an uplink, every device behind it, so a MAC can appear on several ports. Port lookup reads each sighting’s port and its LLDP neighbours, and gives the port a relation:
relation | Meaning |
|---|---|
direct | The device itself is the port’s LLDP neighbour |
edge | No network device is on the port, so the device is plugged in there |
behind | The device is seen through a neighbour on the port (a switch, router or AP), so this is an uplink, not its own port. via names the neighbour |
Sightings are ranked online first, then direct and edge before behind,
then newest. Up to five are judged; the best becomes the answer and the rest
are listed in otherSightings. For a behind answer, notes says whether the
neighbour is a switch this controller manages (whose own MAC table doesn’t list
the device yet) or one it doesn’t manage.
What it reports
Section titled “What it reports”| Field | Contents |
|---|---|
location | The switch (id, name, model, group, status, IP, firmware), the port, relation, via, and the device as the MAC table sees it: IP, VLAN, status, type, description, authentication, user name, last seen |
port | Status and admin status, speed, optics, VLANs and untagged VLAN, STP state, PoE, utilisation, error counters, broadcast and multicast counts, LAG, LLDP neighbours |
settings | The port’s configuration: name, untagged and tagged VLANs, voice VLAN, PoE class, priority and budget, LLDP, 802.1X and flexible authentication, ACLs, guards, storm control |
onPort | The other devices the MAC table lists on that port: a count, how many are online, and up to 25 of them |
findings | What to check first, worked out without a model (examples below) |
calls | How many controller calls the lookup made |
findings flags, among others: a port that is administratively down or whose
link is down; non-zero error counters; a link negotiated at 10 or 100 Mb; PoE
at 90% or more of the port’s allocation; a device seen in a VLAN the port’s
configuration doesn’t carry; a port disabled in its configuration; and a port
that requires authentication where the device shows none.
How many calls does it take?
Section titled “How many calls does it take?”Usually 4 to 6 controller calls, reported in calls. The switch list, the
MAC table rows for the device, the port row (read through its switch group),
the port’s settings and the other devices on the port are each one read, which
can run to more than one page. A lookup by ip or text reads the
whole of every switch’s MAC table (up to 20,000 rows, more pages on a large
network), because SwitchM’s search does not match IP addresses. If that read
stops early, notes says so.
Errors
Section titled “Errors”error | Meaning |
|---|---|
bad_request | None of mac, ip, text, apMac, or switchId with port was given |
bad_mac | mac is not a MAC address |
not_found | No switch MAC table lists the device, or no managed switch reports the AP as an LLDP neighbour (it may hang off an unmanaged switch, or LLDP is off on the port) |
ambiguous | Several devices match ip or text; candidates lists up to 20. Call again with one MAC |
unknown_switch | No switch with that switchId on this controller |
port_not_found | The switch has no such port in SwitchM’s port list |
switch_unknown | The MAC table names a switch the lookup cannot identify: it was renamed, or two switches share the name |
unexpected_response | The AP’s LLDP link names no switch or port |
switch_list_failed, mac_table_failed, ap_links_failed | A controller read failed; status and detail say why |