NetBox Interface Name Rules Plugin

Automatic interface renaming when modules are installed into NetBox device bays.

What it does

When a module (transceiver, line card, converter) is installed into a module bay, NetBox creates interfaces using position-based naming from the module type template. This often produces incorrect names — e.g., Interface 1 instead of et-0/0/4.

This plugin hooks into Django's post_save signal on the Module model to automatically apply renaming rules based on configurable templates.

Features

• Signal-driven — rules fire automatically on module install, no manual step needed
• Template variables — {slot}, {bay_position}, {bay_position_num}, {base}, {channel}, etc.
• Arithmetic expressions — {8 + ({parent_bay_position_num} - 1) * 2 + {sfp_slot}}
• Breakout support — create multiple channel interfaces from a single port (e.g., QSFP+ 4x10G)
• Scoping — rules can be scoped to specific device types, parent module types, or be universal
• Bulk import/export — YAML-based rule management via the UI or API

Supported scenarios

Scenario	Name template	Example result
Converter offset	GigabitEthernet{slot_num}/{8 + ({parent_bay_position_num} - 1) * 2 + {sfp_slot}}	GLC-T in CVR-X2-SFP → GigabitEthernet3/10
Breakout channels	et-0/0/{bay_position}:{channel}	QSFP-4X10G-LR → et-0/0/4:0 through et-0/0/4:3
Platform naming	et-0/0/{bay_position}	QSFP-100G-LR4 on ACX7024 → et-0/0/4
UfiSpace breakout	swp{bay_position_num}s{channel}	QSFP-100G on S9610 → swp1s0 through swp1s3

Installation

pip install netbox-interface-name-rules

Add to configuration.py:

PLUGINS = ["netbox_interface_name_rules"]

Configuration

Rules are managed through the NetBox UI under Plugins → Interface Name Rules, or via the REST API at /api/plugins/interface-name-rules/rules/.

See the full configuration guide for all rule fields, priority scoring, and template variable reference.

Screenshots

Compatibility

• NetBox ≥ 4.3.0 (CI tests 4.3, 4.5, 4.7, plus NetBox main and feature as non-blocking early warnings)
• Python ≥ 3.12

License

Apache 2.0

Documentation

• Full documentation — installation, configuration, examples
• DeepWiki — AI-generated codebase overview

Contributing

See CONTRIBUTING.md for how to submit code or interface name rules.

Community-contributed rules for various vendors are in the contrib/ directory.

Testing

Inside the devcontainer:

netbox-test                          # run this plugin's suite with pytest
netbox-test <pytest args>            # e.g. one file, or -k 'a test name'

netbox-test runs pytest, the runner CI uses, so the fixtures and guards in conftest.py apply. It uses the test_netbox_interface_name_rules database and gives each xdist worker its own copy. Concurrent netbox-test calls wait for each other. Set TEST_DB_NAME=... or TEST_REDIS_HOST=... to use other targets.

netbox-test-isolated <app> [flags] runs the Django test runner (manage.py test) on an isolated database. Do not use it for this plugin's suite: it skips conftest.py. It exists for the performance runner and for other apps. Django otherwise names the test database test_<DB_NAME> (test_netbox), so two concurrent runs share one database and corrupt each other's migrations. The helper sets the database name to test_<app> from the first app argument, or to TEST_DB_NAME=..., through the isolated_test_settings shim:

netbox-test-isolated <other_app> --keepdb