Interface¶

A network port on a device - physical (a switch port, a NIC) or virtual (a sub-interface, LAG, loopback). Interfaces terminate cables, carry IP addresses and VLANs, and are what monitoring, discovery, and the topology views reason about.

Fields¶

Device¶

The device this interface belongs to. An interface's name must be unique on its device.

Module¶

Read-only. The installed module that created this interface (module_id), or empty for the device's own ports. Removing the module removes the interfaces it owns.

Name¶

The port's name (GigabitEthernet0/1, eth0). On create, a [a-b] range in the name fans out into one interface per number.

Type¶

The media type (1000base-t, 10gbase-x-sfpp, …) from the standard taxonomy. Drives the faceplate rendering and the speed-capability colouring.

Enabled¶

Administratively up. Disabled interfaces render dashed on faceplates.

Description¶

Free-text note shown on rows and the detail page.

Tags¶

Tenant-scoped tags.

Switching & routing¶

802.1Q mode¶

How the port handles VLAN tagging: Access (one untagged VLAN), Tagged (a native VLAN plus tagged VLANs), or Tagged (all) (carries every VLAN). Blank for routed ports.

Untagged VLAN¶

The access / native VLAN.

Tagged VLANs¶

The VLANs carried tagged on a trunk. Only valid in Tagged mode.

VRF¶

The VRF this interface routes in. Empty = the Global table.

State¶

Status¶

Lifecycle status from the tenant's status catalog, distinct from Enabled (the admin flag the device reports). Seeded values: Active, Disabled, Planned, Not present, Decommissioning. Empty reads as Active. Not present marks hardware the agent reports as absent - a pre-allocated stack port or an empty slot; SNMP sync sets it automatically when the Import pre-allocated ports setting is on. Not present and Decommissioning ports are excluded from port-utilization capacity entirely.

Management only¶

Out-of-band management port; excluded from data-plane views. Still counted in port utilization: it is a real port.

Mark connected¶

A cable is physically in the port but not documented yet. Counts as connected in port utilization and clears itself when a real cable is attached.

Reservation¶

A port reservation holding this (uncabled) port - who claimed it, the note, and since when. Read-only here; managed through the reserve actions or /api/port-reservations/.

Uplink¶

Automatic, Always or Never - two fields on the API:

• is_uplink (Always) - faces other network gear: discovery never suggests hosts on this port, a learned MAC is located on it only as behind uplink when no access port reports it, and topology treats it as an infrastructure link.
• never_uplink (Never) - never an uplink, whatever the automatic uplink rules say (an LLDP switch neighbour, a LAG, more learned MACs than Uplink above).

Both off is Automatic. Both on is refused (400).

Hardware¶

Speed¶

Free-text speed label (10G); the type's capability is used when unset. A bare integer is taken as kbps and normalised on save (1000000 → 1G).

MTU¶

Maximum transmissible unit.

MAC address¶

The primary MAC. Additional MACs live as first-class MAC address objects linked to the interface.

Duplex¶

Half / full / auto.

PoE mode / PoE type¶

Whether the port supplies or draws power, and the PoE standard.

WWN¶

Fibre Channel World Wide Name.

Combo group¶

Combo / shared port: alternate connectors of one logical port (an RJ45 and its SFP twin) share a group name; enabling one disables the others on the device.

Nesting¶

Virtual interface¶

Marks a sub-interface, LAG, or loopback - no physical attributes, cannot be cabled. Always set for types virtual, bridge and lag: save(), bulk edit and the device-type and module installs set it, and SNMP discovery creates loopbacks, SVIs, tunnels and VLAN interfaces as type virtual. Port utilization counts an interface as virtual when this is set or its type is one of those three, and leaves virtual interfaces out of the total unless the deployment's port_count_virtual setting is on.

Parent interface¶

The interface a sub-interface nests under.

LAG / aggregate¶

The aggregate interface this port is a member of. The target must be an interface of type LAG on the same device or virtual chassis; an aggregate can't itself be a member. Changing an aggregate's type away from LAG is refused while it has members.

Bundle¶

Set on the aggregate (type LAG) only - "Only an interface of type LAG has bundle settings." Picking type LAG marks the interface virtual.

Protocol¶

lag_protocol: blank = static aggregate (no negotiation), lacp (802.3ad), pagp. The port-channel / ae / bond is the logical link; this is the protocol negotiating it.

LACP mode / LACP rate¶

lacp_mode (active / passive) and lacp_rate (slow 30 s / fast 1 s). Only kept under LACP - any other protocol clears them on save.

Min links¶

lag_min_links: members that must be up for the bundle to count as up (at least 1). The detail page flags the bundle when it has fewer members.

Bridge¶

The bridge interface this one belongs to.

Discovery¶

SNMP name¶

What the polled agent calls this port; links the row to SNMP discovery. Clearing it unlinks.

Exclude from SNMP drift¶

The agent can never report this port - it is skipped by drift comparison.

Read-only¶

cable (the terminating cable and its status), ip_addresses, tunnel_terminations (VPN ends on this port), child_count, lag_member_count, lag_protocol_display. A member's lag relation carries the aggregate's lag_protocol and lacp_mode.

ip_addresses lists only the addresses the caller may view: IP view permission in the active tenant, with its site scope and row constraints. A viewer limited to Site A sees the Site A address on a port, not the Site B address bound to the same port, and the port shows as L2 when none are visible. The device's Interfaces tab and GET /api/interfaces/<id>/ips/ follow the same rule.

GET /api/interfaces/<id>/lag/ returns an aggregate's members as full rows plus capacity (sum of parseable member speeds), unparsed_speeds, min_links / degraded, peers (the far-end aggregates its members' direct cables land on, with a member count each), unpaired (members whose far end is uncabled, on a panel, or in no bundle) and mixed_peers (more than one peer - an MLAG / vPC pair). The list accepts ?type=lag and ?lag=<id>.