Cabling & connections¶
Danbyte records the physical connections between ports - patch cables, breakouts, trunks, and links that run through patch panels - and can trace any connection from one end to the other.
Terminable ports: interfaces, front/rear (patch-panel) ports, console + console-server ports, power ports/outlets/feeds, and aux ports - so USB console links or video runs are first-class cables.
Connect two ports¶
- Open DCIM → Cables and click Add cable (or start from a port's detail page).
- Build each end - A side then B side - the same way:
- choose what the end lands on: a device, or a circuit (see Cabling a circuit below),
- pick the port type (interface, front/rear port, console, console server, power port, or power outlet),
- pick the device with the searchable device picker (use its advanced search to filter by site, role, tag, …),
- tick the port(s) on that device. Selected ports appear as chips; switch the device or type and keep ticking to add ports from several devices on the same end (breakout).
- Optionally set the cable's type, status, length, color, and a description.
- Save with Create cable (or Enter), or keep going with Save and add another.
Where a length came from. A length you enter (or import) is yours: a
cable's route on a floor plan never replaces it unless you tick Replace
measured length for that cable. A route fills a blank length, and keeps a
length it computed up to date; the API reads which with length_source
("" entered, computed worked out from a route - read-only). Editing the
length makes it entered again. See
stored routes and lengths.
A port can be cabled only once - Danbyte rejects connecting a port that's already in use, so every connection stays unambiguous.
Cabling a run of ports¶
Patching one device to another usually means port after port - Gi1/0/1 to Eth1/1, Gi1/0/2 to Eth½, and so on. The cable form has two ways to do that without leaving it.
Save and add another¶
Save and add another (or Ctrl+Enter / Cmd+Enter) saves the cable and keeps the form open:
- both ends stay on the same devices, and the cable's type, status, color, length, description and tags are kept; the label is cleared,
- each end moves on to the next free port on its device, in natural order (Gi1/0/2 after Gi1/0/1, Gi1/0/10 after Gi1/0/9), skipping ports that already carry a cable. An end of several ports moves on by as many. An end with no free port left, or one on a circuit, is left empty to pick by hand,
- the cables made this way are listed under N cables added, each with an undo button that deletes it again.
Enter saves the last one and closes the form. Done closes it without saving the ports currently picked.
Many at once¶
Switch the form from One cable to Many at once to cable a whole run in one step:
- On each side, pick the device and the port type. The side lists that device's free ports of that type in natural order, each with a checkbox; All ticks every listed port (after a filter, only the filtered ones) and None clears the side.
- Tick ports on both sides. Pairing is by position: the first ticked port on A (top-down) goes to the first ticked port on B, the second to the second, and so on. The Pairs table previews every cable before anything is written; ports ticked on one side without a partner are counted below it and left out.
- Set the shared type, status, length, color, description and tags - every cable in the run gets them. Labels are per cable, so the label field is hidden here.
- Create N cables.
The run is created all or nothing: each pair is checked exactly like a single cable (ports in the current tenant, not already cabled, kinds that plug into each other), and if any pair fails, no cable is created and the reason shows on that pair's row.
The same works through the API: POST /api/cables/bulk-create/ with
{"cables": [<cable>, ...]}, each item the body POST /api/cables/ takes (at
most 256). It needs the add permission on cables. A failure answers 400
with cables - one error object per item, in order, {} for the items that
were fine - and writes nothing; success answers 201 with created and the
new cables in results.
What connects to what¶
A cable has two ends, and an edit can swap an end's ports but never empty it. One edit can also swap the two ends, or move a port from one end to the other. The two ends must be ports that plug into each other:
| End | The other end may be |
|---|---|
| Interface | interface, front/rear port, circuit |
| Front / rear port | interface, front/rear port, console, console server, aux, circuit |
| Console port | console server port, front/rear port, aux port |
| Console server port | console port, front/rear port, aux port |
| Aux port | aux port, console, console server, front/rear port |
| Circuit | interface, front/rear port, circuit |
| Power port | power outlet, power feed |
| Power outlet | power port |
| Power feed | power port |
Patch panels carry any signal through, so front and rear ports take every kind
but power. Power runs from an outlet or a feed into an inlet. An aux port to a
console port is a USB console lead. Anything else - an interface to a power
outlet, two console ports - is refused (An interface can't be cabled to a
power outlet.).
Deleting the far end deletes the cable. When a device, a module or a port goes, a cable whose end it was the last port on goes with it, and the change log records it. A breakout that loses one leg keeps the others.
Cables stored before these rules keep reading and editing, from the cable form
too: the check applies when an end's ports change, in any order.
manage.py check_dcim_integrity lists cables with an empty end or with ends
that don't match, and changes nothing.
Port reservations¶
Sometimes you know a port will be needed before you know where its cable will land - a colleague claims "I'll need one on this switch" with the far end still undecided. A port reservation holds exactly one uncabled port, no far end required, complementing the Planned-cable flow (which needs both ends picked).
- Reserve from any port row's bookmark action (interfaces, front/rear ports, console, power) or from the interface page's Reserve port button, with an optional note. The row tints amber, shows a Reserved badge with the note and reserver on hover, and the faceplate outlines the port amber.
- A reserved port counts as reserved in port utilization, exactly like a planned cable.
- The hold releases automatically the moment any cable terminates on the port - including a Planned one, which then carries the reserved state itself. Releasing by hand: the same bookmark action, or the list page.
- DCIM → Connections → Port reservations lists every hold in the tenant:
port, kind, site, who reserved it, note, and age
(
/api/port-reservations/) - with kind/site/reserved-by facets, search, a pencil to edit the note, and select + release-many for bulk cleanup. Reservations are RBAC-controlled (Port reservations object type) and audited.
Cable type¶
Pick the medium from the Type dropdown, organised into sub-categories -
copper twisted pair (CAT3–CAT8, MRJ21), twinax/DAC, coaxial (RG-6…RG-213,
LMR-100…400), fiber multimode (OM1–OM5), fiber single-mode (OS1/OS2), AOC,
power, and USB. Start typing (e.g. om4, os2, dac, rg-6) to filter.
Full taxonomy: Interface & cable types.
Cable status & color¶
| Field | Notes |
|---|---|
| Status | connected, planned, or decommissioning. |
| Length | a number plus a unit (m / cm / ft / in). |
| Color | the literal color of the physical cable - shown on the topology map and the cable page's path strip. |
Proxmox VNet¶
A cable between two devices that are Proxmox VMs (a virtual router with Is
router set on its VM) can name the SDN VNet that carries it - field
Proxmox VNet, pve_vnet in the API. It is a VNet id: 1 to 8 characters, a
lowercase letter followed by lowercase letters or digits (c0042). Leave it
blank for any other cable. The cable list filters on ?pve_vnet=<id>.
The VNet is not unique: two cables naming the same one are allowed and are reported as duplicates in the source's network plan, which is what reads this field. Danbyte never creates the VNet itself.
Upgrading copies an interface custom field named pve_vnet onto the cable:
when every end that has a value agrees, or only one end has one. A
disagreement or a value that is not a VNet id is logged as a warning and the
cable stays blank; the custom field itself is left in place.
A Proxmox source can also make cables from VNets; see cables from VNets.
A cable's detail page draws its end-to-end path under the A/B boxes -
every device and panel the run passes through as linked chips, with the
pass-through ports shown front ⇄ rear and each cable segment labelled
(the current cable highlighted). Breakout fan-outs fall back to the Trace tab.
The port cells in a chip are click targets: an interface opens its own page,
while a front / rear / console / power port opens the
Components sub-tab of its device that lists
it - Front ports, Rear ports, Console or Power
(?tab=components&sub=front-ports, …).
Planning cables on a floor plan¶
A floor plan's Connect to… plans new direct cables between placed objects: it proposes free, compatible port pairs (same media and speed, uplinks first), shows their routes and lengths on the plan, and makes them on the plan's Save in a status marked Planned - all or nothing, through the same checks as Many at once. Mark a cable status Planned (Settings → Statuses) to use it; none is created for you.
A cable between two floors is routed through a riser: on each floor to the riser and up or down it, its computed length the whole run. A floor's cable schedule (Export → Cable schedule…) lists its cables with their ends, routes and lengths - computed, stored and where the stored one came from - as a PDF, CSV or XLSX pull sheet.
Connection shapes¶
You're not limited to one-to-one patches:
| Shape | A side | B side | Example |
|---|---|---|---|
| Patch | 1 port | 1 port | switch ⇄ server |
| Breakout | 1 port | many ports | one QSFP → four SFP |
| Trunk | many | many | bundled links |
One end may span devices. A breakout's four legs commonly land in four different servers, so the ports on a single end don't have to share a device. The cable form gives each end a tab per device for exactly this.
One end is one kind of port. Several interfaces on an end is a breakout; an interface and a power port on the same end is a typo, and is rejected - no cable is half network and half power. A circuit end follows the same rule: it is the whole end, never mixed with device ports.
Cabling a circuit¶
The provider hands off at a demarc, and that handoff lands on a real port on a real switch. A circuit termination is therefore a cable endpoint like any other: on either side of the cable form, switch the end from Device to Circuit, pick the circuit, and choose the side (A or Z) that lands here. Each side shows the site or provider network it terminates on, and a side already carrying a cable is greyed out - a circuit end takes one cable, exactly like a port.
Once connected, the trace runs from the interface across the panels and out to the circuit, and stops there: the far side of the circuit is the provider's, not yours, so the path is complete at the demarc.
The circuit end still carries its own cross-connect ID and patch-panel info - those describe the facility's paperwork. The cable is what records which of your ports it actually reaches.
Patch panels¶
A patch panel is just a device with front ports and rear ports. Each front jack maps to a rear strand. When a cable lands on a front port, the connection passes through to the rear and continues on whatever's cabled there - so a link can cross several panels and Danbyte still follows it.
Manage a panel's front/rear ports from its device page, alongside its interfaces. Each port takes a description - the room the trunk runs to, the label on the sticker - shown as a column in the front/rear port tables and editable in bulk.
Tracing a connection¶
Every interface, cable, and panel port has a Trace tab. It walks the connection end to end - hopping across each cable and through each patch panel - and draws the whole path as a single chain, so you can see the real far end of a link even when it runs through three panels to get there. A run that stops before it reaches a far port is marked Incomplete; a port with no cable says Not cabled. See the topology page for how a trace walks through panels and PDUs.
Under the chain, the trace map draws the same run as the topology Diagram does: each device a card in its role's color, in the order the run reaches them, a patch panel a dashed card between the two ends with a nub on each front and rear port the run uses (and no other), the port names and addresses on their own cable, and the traced cables thick in the accent color. It turns Left to right or Top to bottom, and Export saves it as PNG, SVG, PDF or draw.io (Trace maps). The trace dialogs on the cable list and a device's ports show the chain, and the map when a run cannot be drawn as one chain (a breakout, a loop).
Topology¶
The Topology page (sidebar, under Maps) draws an interactive device-to- device map of your cabling. Filter it by site to focus on one location, or by device to pull in just that device's neighbours. Drag nodes around, use the minimap to navigate, and use Arrange ▸ Reset layout to tidy it up. Cable colors carry through to the links. On very large networks, filter by site first - the map will prompt you.
Ports carry an optional Label - the printed, real-world name (X1-P1)
next to a template-generic Name (Port 1). Keep the name matching the
device type so photo markers keep resolving, and put reality in the label: it
shows beside the name in port tables and in the photo-port hovers.
Connecting from a port¶
You don't have to start from the Cables page: any uncabled interface offers a Connect cable button - on the interfaces table (row action) and in the interface detail header. It opens the cable form with that port already on the A side; pick the B side and save. A cabled row offers the reverse: a Disconnect cable action (unplug icon, cable-delete rights) that removes the run after a confirm naming both ends.
The same affordance follows every other cable-able port, permissions allowing (you need cable-add rights; the server enforces them regardless):
- Power tab - uncabled power ports and power outlets carry the same ghosted connect button as interface rows, landing on the cable form with the inlet or outlet pre-seeded as side A.
- Photo faceplate - on a device whose type has photo ports, a free power / console / console-server / aux / front / rear marker is a button: click it and the cable maker opens right there, titled from that port, with it already on the A side. Cabled markers keep their hover card.
- 3D room - clicking a free port marker on a device's face offers the same connect flow (pick the far end in 3D, or open the cable maker) - see floor plans.
However you arrive, the pre-seeded port shows as a named chip
(device:port) on the form, never a raw id - a power feed chip reads
panel:feed, since feeds terminate on power panels rather than devices.