Device Discovery - Interface Type Matching

The device discovery backend uses an intelligent six-tier priority system to automatically determine interface types. This system provides zero-configuration support for common network equipment while allowing fine-grained customization through user-defined patterns.

Priority Order

Interface types are determined using the following priority order (first match wins):

1. Structural Detection (Highest Priority)

• Subinterfaces (e.g., GigabitEthernet0/0.100, ethernet-1/1.0) are always assigned type virtual
• This rule applies regardless of any patterns, driver-reported type, or speed data

2. User-Defined Patterns

• Patterns configured in defaults.interface_patterns are checked first
• If ANY user pattern matches, the most specific (longest) user match is used
• User patterns ALWAYS take priority over built-in patterns, even if the built-in pattern would be more specific

3. Driver-Reported Type

• Some backend drivers report the interface type directly from device state (rather than inferring it from the name), which is more reliable on platforms whose interface names do not encode the type - e.g. Ciena SAOS (LAGs) and MikroTik RouterOS
• When a driver reports a type, it is honored over the built-in patterns, speed, and default below - but a user pattern (tier 2) still wins, so you retain an explicit override
• The reported value must be a valid NetBox interface type; an invalid value is ignored (a warning is logged) and matching falls through to the tiers below
• Drivers that do not report a type skip this tier entirely (no change to behavior)

4. Built-In Patterns

• If no user pattern matches and no driver type applies, built-in vendor patterns are checked
• Provides zero-configuration support for common network equipment (Cisco, Juniper, Arista, Nokia, etc.)
• Most specific (longest) built-in match is used

5. Speed-Based Detection

• If nothing above matches, interface speed (from NAPALM) is used to determine type
• Only applies when speed data is present and greater than 0
• Maps speeds from 100 Mbps to 800G to appropriate interface types

6. Default Fallback (Lowest Priority)

• If nothing else matches, uses defaults.if_type
• Defaults to other if not specified

User-Defined Interface Patterns

You can define custom interface patterns in the defaults.interface_patterns list. Each pattern consists of a regular expression match and a NetBox interface type.

Configuration:

defaults:
  if_type: other  # Fallback type when nothing matches
  interface_patterns:
    - match: "^(GigabitEthernet|Gi).*"
      type: "1000base-t"
    - match: "^(TenGigE|Te).*"
      type: "10gbase-x-sfpp"
    - match: "^Loopback.*"
      type: "virtual"

Pattern Matching Rules:

• Patterns are case-sensitive regular expressions
• Within user patterns, the most specific match wins (longest match)
• If multiple patterns have equal length matches, the first pattern wins
• User patterns always override built-in patterns, regardless of specificity

Example:

interface_patterns:
  - match: "^Gi.*"              # Matches "Gi" prefix (2 chars)
    type: "10gbase-x-sfpp"
  # Built-in pattern: "^(GigabitEthernet|Gi)\S+" would match 16 chars

# Result for "GigabitEthernet0/0": Uses user pattern "10gbase-x-sfpp"
# User pattern wins even though built-in is more specific

Interface Exclusion Patterns

Use interface_exclude_patterns to prevent specific interfaces - and their associated IP addresses - from being ingested into NetBox. This is useful for filtering out virtual or host-only interfaces (TAP, veth, loopback, etc.) that are not relevant to your network inventory.

Configuration

defaults:
  interface_exclude_patterns:
    - "^tap.*"      # exclude TAP interfaces (e.g. tap103i0)
    - "^veth.*"     # exclude veth pairs
    - "^docker.*"   # exclude Docker bridge interfaces

Rules

• Patterns are case-sensitive regular expressions matched against the full interface name
• A pattern matches anywhere in the name - use ^ to anchor to the start (e.g. ^tap matches tap0 but not mytap0)
• When an interface is excluded, all IP addresses assigned to it are also suppressed
• The override_defaults field on a device replaces the global list wholesale (same behaviour as interface_patterns)

Per-Device Override

defaults:
  interface_exclude_patterns:
    - "^tap.*"
scope:
  - hostname: 192.168.1.1
    username: admin
    password: secret
    override_defaults:
      interface_exclude_patterns:
        - "^tap.*"
        - "^veth.*"   # this device also excludes veth interfaces

Invalid Patterns

Invalid regex patterns are logged as warnings and skipped. Valid patterns in the same list are still applied.

Built-In Patterns

When no user patterns are configured (or none match), the system automatically applies built-in patterns for common network equipment:

Cisco IOS/IOS-XE:

• HundredGig*, Hu* → 100gbase-x-qsfp28
• FortyGig*, Fo* → 40gbase-x-qsfpp
• TenGig*, Te* → 10gbase-x-sfpp
• GigabitEthernet*, Gi* → 1000base-t
• FastEthernet*, Fa* → 100base-tx

Juniper:

• ge-* → 1000base-t (Gigabit Ethernet)
• xe-* → 10gbase-x-sfpp (10 Gigabit Ethernet)
• et-* → 40gbase-x-qsfpp (40 Gigabit Ethernet)
• ae* → lag (Link Aggregation)
• lo* → virtual (Loopback)

Nokia SR OS:

• ethernet-* → 1000base-t

Arista:

• Ethernet* → 1000base-t

Virtual/Logical Interfaces:

• Loopback*, Lo* → virtual
• Vlan*, vlan* → virtual
• Tunnel*, Tu* → virtual

Management Interfaces:

• Management*, Mg*, mgmt* → 1000base-t
• fxp* → 1000base-t (Juniper management)

Linux Interfaces:

• eth*, ens*, enp*, swp* → 1000base-t

LAG Interfaces:

• Port-channel* → lag (Cisco)
• Bundle-Ether* → lag (Cisco IOS-XR)

Speed-Based Detection

When no patterns match, the system uses interface speed (in Mbps from NAPALM) to determine the type:

Note: Speed-based detection is skipped if any pattern (user or built-in) matches the interface name, or if the driver reported a valid type, even if the speed suggests a different type.

Complete Matching Flow Example

defaults:
  if_type: other
  interface_patterns:
    - match: "^Gi.*"
      type: "10gbase-x-sfpp"  # User override for Gigabit interfaces

Interface Matching Results:

Zero-Configuration Support

If no interface_patterns are configured, the system automatically applies built-in patterns to provide intelligent defaults for 80-90% of deployments:

defaults:
  if_type: other
  # No interface_patterns specified

Automatic Results:

• Cisco GigabitEthernet0/0 → 1000base-t
• Juniper ge-0/0/0 → 1000base-t
• Arista Ethernet1 → 1000base-t
• Any Loopback0 → virtual
• Any ae0 → lag
• Generic interfaces with speed data → Speed-based detection
• Unknown interfaces without speed → other (defaults.if_type)