Port Assignment Guide

System for mapping discovered devices to physical switch ports in racks. Version: v1.0.39 (13-03-2026)

1. Overview

The Port Assignment System connects the logical world (discovered DeviceProfiles such as APs, cameras, and IoT devices) to the physical world (switch ports mounted in racks). Each assignment records which profile is plugged into which port on which switch.

Why it matters:

• Physical-logical mapping: Know exactly where every device is physically connected.
• Troubleshooting: When a device goes offline, immediately identify the switch and port to check.
• Documentation: Maintain an accurate, up-to-date port map without spreadsheets.
• LLDP/CDP auto-match: Leverage neighbor discovery data to suggest assignments automatically.

2. Architecture

Model: PortConnection

Located in network/models.py:

Constraints

Data source for ports

Port metadata comes from device.model_data (JSON), specifically the ports dictionary. Each key is a port identifier and the value contains label, admin_status, oper_status, and speed. This data is populated during Auto-Provision SNMP discovery.

3. API Reference

All endpoints are under /api/network/ and require authentication. Tenant context is derived from the authenticated user’s organization.

3.1 List Connections

Response 200: Array of PortConnectionOut

Example:

GET /api/network/port-connections?device_id=42

3.2 Create Connection

Request body (PortConnectionIn):

Response 200: PortConnectionOut (the created connection)

Response 400: {"error": "..."} — see Validation Rules

Example:

POST /api/network/port-connections
{
    "device_id": 42,
    "port_key": "12",
    "profile_id": 107,
    "notes": "3rd floor AP uplink"
}

3.3 Delete Connection

Response 200: {"success": true}

Response 404: {"error": "Connection not found"}

3.4 List Switches

Returns all rack-mounted devices that have a ports dictionary in their model_data. These are the devices that can receive port assignments.

Response 200: Array of SwitchOut

3.5 Available Ports

Returns unoccupied ports for a given switch device, sorted numerically.

Response 200: Array of AvailablePortOut

3.6 Suggest Assignment (LLDP/CDP)

Auto-suggests a switch port based on the profile’s LLDP/CDP neighbor data.

Response 200: SuggestionOut

4. LLDP/CDP Auto-Match

The suggestion algorithm lives in network/services/port_suggestion.py. It attempts to match a profile to a physical switch port using LLDP/CDP neighbor data collected during discovery.

Algorithm steps

1. Read neighbors: Collect entries from profile.lldp_neighbors and profile.cdp_neighbors.
2. Match hostname: For each neighbor, look for a DeviceProfile in the same organization where hostname matches the neighbor’s neighbor_hostname (case-insensitive) AND has a linked_device (meaning it is mapped to a rack device).
3. Parse port key: Extract the numeric port identifier from the neighbor’s interface description using regex patterns that handle Cisco-style names (GigabitEthernet0/12, Gi1/0/24, Fa0/1), generic Port N, and plain numbers.
4. Check availability: Verify the parsed port is not already occupied by another PortConnection.
5. Return confidence score:

Supported interface name formats

• GigabitEthernet0/1/12, Gi1/0/24, Fa0/1
• TenGigabitEthernet1/1, Te1/0/1
• Eth1/12, Port 24
• Plain numeric (12)

5. Frontend Integration

PortAssignModal

Located in static/js/services/PortAssignModal.js. A reusable modal with cascading dropdowns.

Invocation:

PortAssignModal.show(profileId, profileName, onAssigned);

Modal workflow

1. Rack dropdown: Loads all racks via /api/racks/list.
2. Switch dropdown: Enabled after rack selection. Loads switches in that rack via the switches endpoint.
3. Port dropdown: Enabled after switch selection. Loads available (unoccupied) ports via the available-ports endpoint.
4. Check LLDP button: Calls the suggest endpoint. If confidence >= 50, auto-selects rack, switch, and port in the dropdowns.
5. Assign button: Enabled after port selection. POSTs the connection.
6. Current assignment: If the profile already has a connection, a blue info bar is shown with an “Unassign” button.

Where it appears

6. Validation Rules

The POST /api/network/port-connections endpoint enforces these rules before creating a connection:

To reassign a profile to a different port, first delete the existing connection, then create a new one. The modal handles this via the “Unassign” button.

7. Visual Integration

Port badges

Assigned profiles display a .port-badge element showing the switch name and port label. Clicking the badge opens the PortAssignModal for reassignment.

Unassigned profiles show a muted badge (or no badge) indicating no port mapping exists.

Locations with port badges:

• Wireless sidebar: Next to each AP entry, showing the physical connection.
• Wireless AP detail tab: Port Connection info panel next to Hardware section — shows switch/rack/port or “Not assigned” with inline Unassign button.
• Observatory sidebar: On rack devices that have a port assignment.
• Observatory manual target tab: Port badge appears after assignment, replacing the “Assign Port” button.
• Group Members table: In the Wireless Groups detail view, each member row shows its port assignment or an “Assign” button.

Rack Editor — Port Table

When viewing a switch in the Rack Editor properties panel, the port table includes:

• Device column: Shows the hostname (orange text) of the assigned DeviceProfile as a clickable link.
• Description column: Appends the assigned hostname after existing port description text (separated by ·).
• Navigation links: Clicking the hostname navigates to:
  • /monitoring/wireless/ — if profile_device_type is access_point
  • /monitoring/ (Observatory) — for all other device types
• Async loading: Port connections are fetched via loadPortConnections(deviceId) after the port table renders, so the page remains responsive.

CSS

Files Reference

Last updated: 13-03-2026

Véase también

• [[concept—network—auto-provision]] — concepto de auto-descubrimiento de red
• [[crearack-tech—backend—auto-provision-guide]] — guía técnica de Auto-Provision
• [[crearack-tech—agents—dev-auto-provision]] — perfil de subagente dev-auto-provision
• [[crearack-tech—guides—interconnection-guide]] — guía de interconexionado
• [[crearack—network—discovery]] — discovery de dispositivos
• [[crearack—redes-infra—switches-routers]] — switches y routers en CreaRack
• [[entity—network—model—deviceprofile]] — perfil de dispositivo descubierto