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, after a module moves, and after the position of an occupied module bay changes. A bay name change also triggers them when a template variable reads the name. No manual step is 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
• netbox-branching: renames run in the active branch, and a merge, revert or sync keeps the names that it replays (netbox-branching 1.2.x on NetBox 4.7). A channel that the plugin kept at its old name is the exception: see Limits in a branch

Supported scenarios

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