Interfaces

Interfaces in NetBox represent network interfaces used to exchange data with connected devices. On modern networks, these are most commonly Ethernet, but other types are supported as well. IP addresses, VLANs, and VRFs can be assigned to interfaces.

Tip

Like most device components, interfaces are instantiated automatically from interface templates assigned to the selected device type when a device is created.

Note

Although both devices and virtual machines can have interfaces assigned, a separate model is used for each. Thus, device interfaces have some properties that are not present on virtual machine interfaces and vice versa.

Breaking Change: VRF is Now Multi-Select

Breaking Change — DCIM-4890

The vrf field on Interface has been changed from a single foreign key to a many-to-many relationship. This is a breaking change affecting the REST API, GraphQL API, bulk import CSV format, and any custom scripts or integrations that read or write the vrf field.

A database migration is required before upgrading. See Migration Notes below.

What changed

Layer	Before	After
Model	`ForeignKey` — one VRF per interface	`ManyToManyField` — zero or more VRFs
REST API	`"vrf": { "id": 1, ... }` (object or null)	`"vrf": [{ "id": 1, ... }, ...]` (array)
GraphQL	`vrf: VRFType` (nullable scalar)	`vrf: [VRFType]` (list)
UI form	Single dropdown	Multi-select dropdown
Bulk import	Single RD value	Comma-separated RD values
Bulk edit	Single dropdown, nullable	Multi-select dropdown
Filtering	`vrf_id=1`	`vrf_id=1&vrf_id=2` (multi-value, unchanged syntax)
clone_fields	Included `vrf`	`vrf` removed (M2M fields are not cloned)

Migration Notes

The underlying database schema changes from a vrf_id integer column on the dcim_interface table to a new join table (dcim_interface_vrf). Run the migration before starting the application:

python manage.py migrate dcim

Existing single-VRF assignments are preserved automatically by the migration — each interface that previously had a vrf_id will have that VRF added to its new M2M set.

REST API Examples

Before (single VRF — no longer valid)

// GET /api/dcim/interfaces/42/
{
  "id": 42,
  "name": "GigabitEthernet0/0",
  "vrf": {
    "id": 3,
    "url": "/api/ipam/vrfs/3/",
    "display": "MGMT",
    "name": "MGMT",
    "rd": "65000:100"
  }
}

// PATCH /api/dcim/interfaces/42/  — old single-value write
{
  "vrf": 3
}

After (multiple VRFs)

// GET /api/dcim/interfaces/42/
{
  "id": 42,
  "name": "GigabitEthernet0/0",
  "vrf": [
    {
      "id": 3,
      "url": "/api/ipam/vrfs/3/",
      "display": "MGMT",
      "name": "MGMT",
      "rd": "65000:100"
    },
    {
      "id": 7,
      "url": "/api/ipam/vrfs/7/",
      "display": "PROD",
      "name": "PROD",
      "rd": "65000:200"
    }
  ]
}

// PATCH /api/dcim/interfaces/42/  — new multi-value write (array of IDs)
{
  "vrf": [3, 7]
}

// PATCH to clear all VRFs from an interface
{
  "vrf": []
}

Filtering (unchanged syntax, now returns matches on any assigned VRF)

GET /api/dcim/interfaces/?vrf_id=3
GET /api/dcim/interfaces/?vrf_id=3&vrf_id=7
GET /api/dcim/interfaces/?vrf=65000:100

GraphQL Examples

Before

query {
  interface_list {
    name
    vrf {
      name
      rd
    }
  }
}

After

query {
  interface_list {
    name
    vrf {
      name
      rd
    }
  }
}

Note

The query syntax is identical, but the vrf field now returns a list. Code that assumed vrf was a single nullable object must be updated to iterate over the list.

Bulk Import (CSV) Examples

Before (single RD)

device,name,type,vrf.pk
Device1,GigabitEthernet0/0,1000base-t,3

After (comma-separated RDs in quotes)

device,name,type,vrf
Device1,GigabitEthernet0/0,1000base-t,"65000:100,65000:200"

Fields

Device

The device to which this interface belongs.

Module

The installed module within the assigned device to which this interface belongs (optional).

Name

The name of the interface, as reported by the device's operating system. Must be unique to the parent device.

Label

An alternative physical label identifying the interface.

Type

The type of interface. Interfaces may be physical or virtual in nature, but only physical interfaces may be connected via cables.

Note

The interface type refers to the physical termination or port on the device. Interfaces which employ a removable optic or similar transceiver should be defined to represent the type of transceiver in use, irrespective of the physical termination to that transceiver.

Speed

The operating speed, in kilobits per second (kbps).

Duplex

The operation duplex (full, half, or auto).

VRFs

One or more virtual routing and forwarding instances to which this interface is assigned. An interface may belong to zero, one, or multiple VRFs simultaneously — for example to model a sub-interface that carries traffic for multiple routing domains.

Breaking change

Prior to DCIM-4890, this field accepted a single VRF. It now accepts a list. See the breaking change notice above.

MAC Address

The 48-bit MAC address (for Ethernet interfaces).

WWN

The 64-bit world-wide name (for Fibre Channel interfaces).

MTU

The interface's configured maximum transmissible unit (MTU).

Transmit Power

The interface's configured output power, in dBm (for optical interfaces).

Enabled

If not selected, this interface will be treated as disabled/inoperative.

Management Only

Designates the interface as handling management traffic only (e.g. for out-of-band management connections).

Mark Connected

If selected, this component will be treated as if a cable has been connected.

Parent Interface

Virtual interfaces can be bound to a physical parent interface. This is helpful for modeling virtual interfaces which employ encapsulation on a physical interface, such as an 802.1Q VLAN-tagged subinterface.

Note

An interface with one or more child interfaces assigned cannot be deleted until all its child interfaces have been deleted or reassigned.

Bridged Interface

Interfaces can be bridged to other interfaces on a device in two manners: symmetric or grouped.

Symmetric: For example, eth0 is bridged to eth1, and eth1 is bridged to eth0. This effects a point-to-point bridge between the two interfaces, which NetBox will follow when tracing cable paths.
Grouped: Multiple interfaces are each bridged to a common virtual bridge interface, effecting a multiaccess bridged segment. NetBox cannot follow these relationships when tracing cable paths, because no forwarding information is available.

LAG Interface

Physical interfaces may be arranged into link aggregation groups (LAGs, also known as "trunks") and associated with a parent LAG (virtual) interface. LAG interfaces can be recursively nested to model bonding of trunk groups. Like all virtual interfaces, LAG interfaces cannot be connected physically.

PoE Mode

The power over Ethernet (PoE) mode for this interface. (This field must be left empty for interfaces which do not support PoE.) Choices include:

Powered device (PD)
Power-supplying equipment (PSE)

PoE Type

The classification of PoE transmission supported, for PoE-enabled interfaces. This can be one of the listed IEEE 802.3 standards, or a passive setting (24 or 48 volts across two or four pairs).

802.1Q Mode

For switched Ethernet interfaces, this identifies the 802.1Q encapsulation strategy in effect. Options include:

Access: All traffic is assigned to a single VLAN, with no tagging.
Tagged: One untagged "native" VLAN is allowed, as well as any number of tagged VLANs.
Tagged (all): Implies that all VLANs are carried by the interface. One untagged VLAN may be designated.

This field must be left blank for routed interfaces which do not employ 802.1Q encapsulation.

Untagged VLAN

The "native" (untagged) VLAN for the interface. Valid only when one of the above 802.1Q modes is selected.

Tagged VLANs

The tagged VLANs which are configured to be carried by this interface. Valid only for the "tagged" 802.1Q mode above.

Wireless Role

Indicates the configured role for wireless interfaces (access point or station).

Wireless Channel

The configured channel for wireless interfaces.

Tip

Selecting one of the pre-defined wireless channels will automatically populate the channel frequency and width upon saving the interface.

Channel Frequency

The configured operation frequency of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use.

Channel Width

The configured channel width of a wireless interface, in MHz. This is typically inferred by the configured channel above, but may be set manually e.g. to identify a licensed channel not available for general use.

Wireless LANs

The wireless LANs for which this interface carries traffic. (Valid for wireless interfaces only.)

IBM Fields

The following fields are IBM-specific extensions to the standard NetBox Interface model. They are surfaced in the IBM fieldset on the UI form and as first-class fields on the REST API.

Profile

The port profile assigned to this interface (e.g. uplink-100g, server-access). Free-form text, maximum 50 characters. Optional.

Status

The provisioning status of the interface. Optional — leave blank when status is not yet known. Allowed values:

Value	Label	Meaning
`discovered`	Discovered	Interface has been discovered but not yet provisioned
`provisioned`	Provisioned	Interface has been fully provisioned and is in service

Note

Status is not a required field. An interface with no status set is valid and will display a placeholder dash in the UI.

IBM REST API Examples

Read an interface with profile and status

// GET /api/dcim/interfaces/42/
{
  "id": 42,
  "name": "GigabitEthernet0/0",
  "profile": "uplink-100g",
  "status": "provisioned"
}

Create an interface with profile and status

// POST /api/dcim/interfaces/
{
  "device": 5,
  "name": "GigabitEthernet0/1",
  "type": "1000base-t",
  "profile": "server-access",
  "status": "discovered"
}

Update status only

// PATCH /api/dcim/interfaces/42/
{
  "status": "provisioned"
}

Clear status (set back to blank)

// PATCH /api/dcim/interfaces/42/
{
  "status": null
}

Invalid status — API validation error

Submitting any value outside discovered / provisioned returns HTTP 400:

// PATCH /api/dcim/interfaces/42/
{
  "status": "active"
}

// Response 400
{
  "status": [
    "\"active\" is not a valid choice."
  ]
}

Filter by status

GET /api/dcim/interfaces/?status=discovered
GET /api/dcim/interfaces/?status=provisioned

Filter by profile (contains)

GET /api/dcim/interfaces/?profile=uplink