netbox-interface-name-rules 1.0.0__tar.gz

netbox_interface_name_rules-1.0.0/LICENSE

@@ -0,0 +1 @@
+Apache License 2.0

netbox_interface_name_rules-1.0.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: netbox-interface-name-rules
+Version: 1.0.0
+Summary: NetBox plugin for automatic interface renaming when modules are installed
+License-Expression: Apache-2.0
+Requires-Python: >=3.12.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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} - 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 | Example |
+|----------|---------|
+| Converter offset | GLC-T in CVR-X2-SFP → `GigabitEthernet3/10` |
+| Breakout channels | QSFP-4X10G-LR → `et-0/0/4:0` through `et-0/0/4:3` |
+| Platform naming | QSFP-100G-LR4 on ACX7024 → `et-0/0/{bay_position}` |
+| UfiSpace breakout | QSFP-100G on S9610 → `swp{bay_position_num}s{channel}` |
+
+## Installation
+
+```bash
+pip install netbox-interface-name-rules
+```
+
+Add to `configuration.py`:
+```python
+PLUGINS = ['netbox_interface_name_rules']
+```
+
+## Compatibility
+
+- NetBox ≥ 4.2.0
+- Python ≥ 3.12
+
+## License
+
+Apache 2.0

netbox_interface_name_rules-1.0.0/README.md

@@ -0,0 +1,50 @@
+# 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} - 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 | Example |
+|----------|---------|
+| Converter offset | GLC-T in CVR-X2-SFP → `GigabitEthernet3/10` |
+| Breakout channels | QSFP-4X10G-LR → `et-0/0/4:0` through `et-0/0/4:3` |
+| Platform naming | QSFP-100G-LR4 on ACX7024 → `et-0/0/{bay_position}` |
+| UfiSpace breakout | QSFP-100G on S9610 → `swp{bay_position_num}s{channel}` |
+
+## Installation
+
+```bash
+pip install netbox-interface-name-rules
+```
+
+Add to `configuration.py`:
+```python
+PLUGINS = ['netbox_interface_name_rules']
+```
+
+## Compatibility
+
+- NetBox ≥ 4.2.0
+- Python ≥ 3.12
+
+## License
+
+Apache 2.0

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from netbox.plugins import PluginConfig
+
+__version__ = "1.0.0"
+
+
+class InterfaceNameRulesConfig(PluginConfig):
+    name = "netbox_interface_name_rules"
+    verbose_name = "Interface Name Rules"
+    description = "Automatic interface renaming when modules are installed into bays."
+    version = __version__
+    base_url = "interface-name-rules"
+    min_version = "4.2.0"
+    required_settings = []
+    default_settings = {}
+
+    def ready(self):
+        super().ready()
+        from . import signals  # noqa: F401 — registers post_save handler
+
+
+config = InterfaceNameRulesConfig

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/api/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/api/serializers.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from netbox.api.serializers import NetBoxModelSerializer
+
+from netbox_interface_name_rules.models import InterfaceNameRule
+
+
+class InterfaceNameRuleSerializer(NetBoxModelSerializer):
+    class Meta:
+        model = InterfaceNameRule
+        fields = [
+            "id",
+            "module_type",
+            "parent_module_type",
+            "device_type",
+            "name_template",
+            "channel_count",
+            "channel_start",
+            "description",
+        ]

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/api/urls.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+app_name = "netbox_interface_name_rules"
+
+router = NetBoxRouter()
+router.register("rules", views.InterfaceNameRuleViewSet)
+
+urlpatterns = router.urls

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/api/views.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from netbox_interface_name_rules.models import InterfaceNameRule
+
+from .serializers import InterfaceNameRuleSerializer
+
+
+class InterfaceNameRuleViewSet(NetBoxModelViewSet):
+    queryset = InterfaceNameRule.objects.all()
+    serializer_class = InterfaceNameRuleSerializer

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/engine.py

@@ -0,0 +1,241 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+"""Core renaming engine — rule lookup and interface rename logic.
+
+This module is imported lazily by signals.py so that model imports happen
+after Django is fully initialised.
+"""
+
+import ast
+import re
+
+
+def apply_interface_name_rules(module, module_bay):
+    """Apply InterfaceNameRule rename after module installation.
+
+    Looks up a matching rule for (module_type, parent_module_type, device_type)
+    and renames interfaces created by NetBox's template instantiation.
+
+    Only processes interfaces whose name still matches the raw bay position
+    (i.e., haven't been renamed yet), ensuring idempotency.
+
+    Returns:
+        Number of interfaces renamed/created, or 0 if no rule matched.
+    """
+    from dcim.models import Interface
+
+    module_type = module.module_type
+
+    # Determine parent module type (if installed inside another module)
+    parent_module_type = None
+    if module_bay.parent:
+        parent_bay = module_bay.parent
+        if hasattr(parent_bay, "installed_module") and parent_bay.installed_module:
+            parent_module_type = parent_bay.installed_module.module_type
+
+    # Look up rule: most specific first, then broader matches
+    device_type = module.device.device_type if module.device else None
+    rule = _find_matching_rule(module_type, parent_module_type, device_type)
+
+    if not rule:
+        return 0
+
+    variables = _build_variables(module_bay)
+    interfaces = list(Interface.objects.filter(module=module))
+
+    if not interfaces:
+        return 0
+
+    # Determine the raw interface name NetBox assigned from the template
+    # (the bay position). Only rename interfaces that still have this name.
+    raw_name = variables["bay_position"]
+    unrenamed = [i for i in interfaces if i.name == raw_name]
+    if not unrenamed:
+        return 0  # Already renamed (idempotent guard)
+
+    renamed = 0
+    for iface in unrenamed:
+        variables["base"] = iface.name
+        renamed += _apply_rule_to_interface(rule, iface, variables, module)
+
+    return renamed
+
+
+def _find_matching_rule(module_type, parent_module_type, device_type):
+    """Find the most specific InterfaceNameRule matching the context.
+
+    Priority order:
+      1. module_type + parent_module_type + device_type
+      2. module_type + parent_module_type (any device)
+      3. module_type + device_type (any parent)
+      4. module_type only (universal)
+    """
+    from .models import InterfaceNameRule
+
+    candidates = [
+        (parent_module_type, device_type),
+        (parent_module_type, None),
+        (None, device_type),
+        (None, None),
+    ]
+
+    for pmt, dt in candidates:
+        if pmt is None and dt is None:
+            # Most generic — both nullable
+            rule = InterfaceNameRule.objects.filter(
+                module_type=module_type,
+                parent_module_type__isnull=True,
+                device_type__isnull=True,
+            ).first()
+        elif pmt is None:
+            rule = InterfaceNameRule.objects.filter(
+                module_type=module_type,
+                parent_module_type__isnull=True,
+                device_type=dt,
+            ).first()
+        elif dt is None:
+            rule = InterfaceNameRule.objects.filter(
+                module_type=module_type,
+                parent_module_type=pmt,
+                device_type__isnull=True,
+            ).first()
+        else:
+            rule = InterfaceNameRule.objects.filter(
+                module_type=module_type,
+                parent_module_type=pmt,
+                device_type=dt,
+            ).first()
+        if rule:
+            return rule
+
+    return None
+
+
+def _build_variables(module_bay):
+    """Build template variable dict from module bay context."""
+    bay_position = module_bay.position or "0"
+    # If position is a template expression (e.g., {module}), extract from bay name
+    if bay_position.startswith("{"):
+        match = re.search(r"(\d+)$", module_bay.name)
+        bay_position = match.group(1) if match else "0"
+    # Extract numeric-only version for arithmetic (e.g., "swp1" → "1")
+    bay_position_num_match = re.search(r"(\d+)$", bay_position)
+    bay_position_num = bay_position_num_match.group(1) if bay_position_num_match else bay_position
+
+    parent_bay_position = "0"
+    sfp_slot = bay_position_num
+    slot = bay_position_num
+
+    if module_bay.parent:
+        parent_bay = module_bay.parent
+        parent_bay_position = parent_bay.position or "0"
+        # slot is typically the top-level module position
+        if parent_bay.parent and hasattr(parent_bay.parent, "installed_module"):
+            grandparent = parent_bay.parent
+            slot = grandparent.position or parent_bay_position
+        else:
+            slot = parent_bay_position
+    elif hasattr(module_bay, "module") and module_bay.module:
+        # Bay belongs to an installed module (not nested, but module-scoped)
+        owner_module = module_bay.module
+        if hasattr(owner_module, "module_bay") and owner_module.module_bay:
+            slot = owner_module.module_bay.position or bay_position
+
+    return {
+        "slot": slot,
+        "bay_position": bay_position,
+        "bay_position_num": bay_position_num,
+        "parent_bay_position": parent_bay_position,
+        "sfp_slot": sfp_slot,
+    }
+
+
+def _apply_rule_to_interface(rule, iface, variables, module):
+    """Apply a single rule to an interface, handling breakout channels.
+
+    Returns number of interfaces renamed/created.
+    """
+    from dcim.models import Interface
+
+    count = 0
+
+    if rule.channel_count > 0:
+        # Breakout: rename base and create additional channel interfaces
+        for ch in range(rule.channel_count):
+            variables["channel"] = str(rule.channel_start + ch)
+            new_name = evaluate_name_template(rule.name_template, variables)
+            if ch == 0:
+                iface.name = new_name
+                iface.full_clean()
+                iface.save()
+                count += 1
+            else:
+                breakout_iface = Interface(
+                    device=module.device,
+                    module=module,
+                    name=new_name,
+                    type=iface.type,
+                    enabled=iface.enabled,
+                )
+                breakout_iface.full_clean()
+                breakout_iface.save()
+                count += 1
+    else:
+        # Simple rename (converter offset, platform naming, etc.)
+        new_name = evaluate_name_template(rule.name_template, variables)
+        if new_name != iface.name:
+            iface.name = new_name
+            iface.full_clean()
+            iface.save()
+            count += 1
+
+    return count
+
+
+def evaluate_name_template(template: str, variables: dict) -> str:
+    """Evaluate a name template with variable substitution and arithmetic.
+
+    Supports templates like:
+        "GigabitEthernet{slot}/{8 + ({parent_bay_position} - 1) * 2 + {sfp_slot}}"
+
+    Variables are substituted first, then any brace-enclosed expression
+    containing arithmetic operators is safely evaluated via AST.
+    """
+    # First pass: substitute all simple variables
+    result = template
+    for key, value in variables.items():
+        result = result.replace(f"{{{key}}}", str(value))
+
+    # Second pass: evaluate any remaining brace-enclosed arithmetic expressions
+    def _eval_expr(match):
+        expr = match.group(1).strip()
+        # Only allow digits, arithmetic operators, parentheses, and whitespace
+        if not re.match(r"^[\d\s\+\-\*\/\(\)]+$", expr):
+            raise ValueError(f"Unsafe expression in name template: {expr}")
+        try:
+            node = ast.parse(expr, mode="eval")
+            for child in ast.walk(node):
+                if not isinstance(
+                    child,
+                    (
+                        ast.Expression,
+                        ast.BinOp,
+                        ast.UnaryOp,
+                        ast.Constant,
+                        ast.Add,
+                        ast.Sub,
+                        ast.Mult,
+                        ast.Div,
+                        ast.FloorDiv,
+                        ast.Mod,
+                        ast.USub,
+                        ast.UAdd,
+                    ),
+                ):
+                    raise ValueError(f"Unsafe AST node in expression: {type(child).__name__}")
+            return str(eval(compile(node, "<template>", "eval")))  # noqa: S307
+        except (SyntaxError, TypeError) as e:
+            raise ValueError(f"Invalid arithmetic expression '{expr}': {e}") from e
+
+    result = re.sub(r"\{([^}]+)\}", _eval_expr, result)
+    return result

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/filters.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+import django_filters
+
+from .models import InterfaceNameRule
+
+
+class InterfaceNameRuleFilterSet(django_filters.FilterSet):
+    class Meta:
+        model = InterfaceNameRule
+        fields = ["module_type", "parent_module_type", "device_type"]

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/forms.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from django import forms
+from netbox.forms import NetBoxModelFilterSetForm, NetBoxModelForm, NetBoxModelImportForm
+
+from .models import InterfaceNameRule
+
+
+class InterfaceNameRuleForm(NetBoxModelForm):
+    class Meta:
+        model = InterfaceNameRule
+        fields = [
+            "module_type",
+            "parent_module_type",
+            "device_type",
+            "name_template",
+            "channel_count",
+            "channel_start",
+            "description",
+        ]
+
+
+class InterfaceNameRuleImportForm(NetBoxModelImportForm):
+    class Meta:
+        model = InterfaceNameRule
+        fields = [
+            "module_type",
+            "parent_module_type",
+            "device_type",
+            "name_template",
+            "channel_count",
+            "channel_start",
+            "description",
+        ]
+
+
+class InterfaceNameRuleFilterForm(NetBoxModelFilterSetForm):
+    module_type_id = forms.IntegerField(required=False, label="Module Type ID")
+    parent_module_type_id = forms.IntegerField(required=False, label="Parent Module Type ID")
+    device_type_id = forms.IntegerField(required=False, label="Parent Device Type ID")
+
+    model = InterfaceNameRule

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/migrations/0001_initial.py

@@ -0,0 +1,97 @@
+import django.db.models.deletion
+import netbox.models.deletion
+import taggit.managers
+import utilities.json
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("dcim", "0225_gfk_indexes"),
+        ("extras", "0134_owner"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="InterfaceNameRule",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False)),
+                ("created", models.DateTimeField(auto_now_add=True, null=True)),
+                ("last_updated", models.DateTimeField(auto_now=True, null=True)),
+                (
+                    "custom_field_data",
+                    models.JSONField(blank=True, default=dict, encoder=utilities.json.CustomFieldJSONEncoder),
+                ),
+                (
+                    "name_template",
+                    models.CharField(
+                        max_length=255,
+                        help_text=(
+                            "Interface name template expression, e.g. "
+                            "'GigabitEthernet{slot}/{8 + ({parent_bay_position} - 1) * 2 + {sfp_slot}}'"
+                        ),
+                    ),
+                ),
+                (
+                    "channel_count",
+                    models.PositiveSmallIntegerField(
+                        default=0,
+                        help_text="Number of breakout channels (0 = no breakout). Creates this many interfaces per template.",
+                    ),
+                ),
+                (
+                    "channel_start",
+                    models.PositiveSmallIntegerField(
+                        default=0,
+                        help_text="Starting channel number for breakout interfaces (e.g., 0 for Juniper, 1 for Cisco)",
+                    ),
+                ),
+                (
+                    "description",
+                    models.TextField(blank=True, help_text="Optional description or notes about this rule"),
+                ),
+                (
+                    "module_type",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="+",
+                        to="dcim.moduletype",
+                        help_text="The module type whose installation triggers this rename rule",
+                    ),
+                ),
+                (
+                    "parent_module_type",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="+",
+                        to="dcim.moduletype",
+                        help_text="If set, rule only applies when installed inside this parent module type",
+                    ),
+                ),
+                (
+                    "device_type",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="+",
+                        to="dcim.devicetype",
+                        help_text="If set, rule only applies to devices of this parent device type",
+                    ),
+                ),
+                (
+                    "tags",
+                    taggit.managers.TaggableManager(through="extras.TaggedItem", to="extras.Tag", related_name="+"),
+                ),
+            ],
+            options={
+                "ordering": ["module_type__model"],
+                "unique_together": {("module_type", "parent_module_type", "device_type")},
+            },
+            bases=(netbox.models.deletion.DeleteMixin, models.Model),
+        ),
+    ]

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/models.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from dcim.models import DeviceType, ModuleType
+from django.db import models
+from django.urls import reverse
+from netbox.models import NetBoxModel
+from taggit.managers import TaggableManager
+
+
+class InterfaceNameRule(NetBoxModel):
+    """Post-install interface rename rule for module types.
+
+    Handles cases where NetBox's position-based naming can't produce
+    the correct interface name, such as converter offset (CVR-X2-SFP)
+    or breakout transceivers (QSFP+ 4x10G).
+
+    The name_template uses Python str.format() syntax with these variables:
+      {slot}               - Slot number from parent module bay position
+      {bay_position}       - Position of the bay this module is installed into
+      {bay_position_num}   - Numeric suffix of bay position (e.g., "swp1" → "1")
+      {parent_bay_position} - Position of the parent module's bay
+      {sfp_slot}           - Sub-bay index within the parent module
+      {base}               - Base interface name from NetBox position resolution
+      {channel}            - Channel number (iterated for breakout)
+    """
+
+    module_type = models.ForeignKey(
+        ModuleType,
+        on_delete=models.CASCADE,
+        related_name="+",
+        help_text="The module type whose installation triggers this rename rule",
+    )
+    parent_module_type = models.ForeignKey(
+        ModuleType,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="+",
+        help_text="If set, rule only applies when installed inside this parent module type",
+    )
+    device_type = models.ForeignKey(
+        DeviceType,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="+",
+        help_text="If set, rule only applies to devices of this parent device type",
+    )
+    name_template = models.CharField(
+        max_length=255,
+        help_text=(
+            "Interface name template expression, e.g. "
+            "'GigabitEthernet{slot}/{8 + ({parent_bay_position} - 1) * 2 + {sfp_slot}}'"
+        ),
+    )
+    channel_count = models.PositiveSmallIntegerField(
+        default=0,
+        help_text="Number of breakout channels (0 = no breakout). Creates this many interfaces per template.",
+    )
+    channel_start = models.PositiveSmallIntegerField(
+        default=0,
+        help_text="Starting channel number for breakout interfaces (e.g., 0 for Juniper, 1 for Cisco)",
+    )
+    description = models.TextField(
+        blank=True,
+        help_text="Optional description or notes about this rule",
+    )
+
+    # Override inherited tags to avoid reverse accessor clash when co-installed
+    # with another plugin that has a model of the same name.
+    tags = TaggableManager(through="extras.TaggedItem", related_name="+")
+
+    def get_absolute_url(self):
+        return reverse("plugins:netbox_interface_name_rules:interfacenamerule_detail", args=[self.pk])
+
+    class Meta:
+        unique_together = ["module_type", "parent_module_type", "device_type"]
+        ordering = ["module_type__model"]
+
+    def __str__(self):
+        parent = f" in {self.parent_module_type.model}" if self.parent_module_type else ""
+        device = f" on {self.device_type.model}" if self.device_type else ""
+        return f"{self.module_type.model}{parent}{device} → {self.name_template}"

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/navigation.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from netbox.plugins import PluginMenu, PluginMenuButton, PluginMenuItem
+
+menu = PluginMenu(
+    label="Interface Name Rules",
+    icon_class="mdi mdi-swap-horizontal",
+    groups=(
+        (
+            "Rules",
+            (
+                PluginMenuItem(
+                    link="plugins:netbox_interface_name_rules:interfacenamerule_list",
+                    link_text="Interface Name Rules",
+                    buttons=(
+                        PluginMenuButton(
+                            link="plugins:netbox_interface_name_rules:interfacenamerule_add",
+                            title="Add",
+                            icon_class="mdi mdi-plus-thick",
+                        ),
+                        PluginMenuButton(
+                            link="plugins:netbox_interface_name_rules:interfacenamerule_bulk_import",
+                            title="Import",
+                            icon_class="mdi mdi-upload",
+                        ),
+                    ),
+                ),
+            ),
+        ),
+    ),
+)

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/signals.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+"""Django signals for automatic interface renaming on module install."""
+
+import functools
+import logging
+import threading
+
+from django.db import connection, transaction
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+logger = logging.getLogger("netbox_interface_name_rules")
+
+# Delay for auto-commit mode (seconds). Allows Module.save() to finish
+# creating component instances before the rename logic runs.
+_AUTOCOMMIT_DELAY = 0.5
+
+
+@receiver(post_save, sender="dcim.Module", dispatch_uid="interface_name_rules_post_save_module")
+def on_module_saved(sender, instance, created, **kwargs):
+    """Apply interface name rules when a module is installed (created).
+
+    NetBox creates module component instances (interfaces) in Module.save()
+    *after* super().save() returns — the point at which post_save fires.
+
+    In an explicit transaction (UI/API with atomic block),
+    transaction.on_commit() correctly defers execution until after the
+    full save completes, including interface creation.
+
+    In auto-commit mode, on_commit() fires immediately — a short timer
+    is used as a fallback to allow Module.save() to finish.
+    """
+    if not created:
+        return
+
+    module = instance
+    module_bay = getattr(module, "module_bay", None)
+    if not module_bay:
+        return
+
+    callback = functools.partial(_apply_rules_deferred, module.pk, module_bay.pk)
+
+    if connection.in_atomic_block:
+        transaction.on_commit(callback)
+    else:
+        threading.Timer(_AUTOCOMMIT_DELAY, callback).start()
+
+
+def _apply_rules_deferred(module_pk, module_bay_pk):
+    """Apply interface name rules after transaction commit."""
+    from dcim.models import Module, ModuleBay
+
+    try:
+        module = Module.objects.get(pk=module_pk)
+        module_bay = ModuleBay.objects.get(pk=module_bay_pk)
+    except (Module.DoesNotExist, ModuleBay.DoesNotExist):
+        return
+
+    try:
+        from .engine import apply_interface_name_rules
+
+        renamed = apply_interface_name_rules(module, module_bay)
+        if renamed:
+            logger.info(
+                "Renamed %d interface(s) for %s in %s",
+                renamed,
+                module.module_type,
+                module_bay.name,
+            )
+    except Exception:
+        logger.exception(
+            "Failed to apply interface name rules for %s in %s",
+            module.module_type,
+            module_bay.name,
+        )

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/tables.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+import django_tables2 as tables
+from netbox.tables import NetBoxTable, columns
+
+from .models import InterfaceNameRule
+
+
+class InterfaceNameRuleTable(NetBoxTable):
+    pk = columns.ToggleColumn()
+    module_type = tables.Column(verbose_name="Module Type", linkify=True)
+    parent_module_type = tables.Column(verbose_name="Parent Module Type", linkify=True)
+    device_type = tables.Column(verbose_name="Parent Device Type", linkify=True)
+    name_template = tables.Column(verbose_name="Name Template")
+    channel_count = tables.Column(verbose_name="Channels")
+    channel_start = tables.Column(verbose_name="Ch. Start")
+    description = tables.Column(verbose_name="Description", linkify=False)
+    actions = columns.ActionsColumn(actions=("edit", "delete"))
+
+    class Meta:
+        model = InterfaceNameRule
+        fields = (
+            "pk",
+            "id",
+            "module_type",
+            "parent_module_type",
+            "device_type",
+            "name_template",
+            "channel_count",
+            "channel_start",
+            "description",
+            "actions",
+        )
+        default_columns = (
+            "pk",
+            "module_type",
+            "parent_module_type",
+            "device_type",
+            "name_template",
+            "channel_count",
+            "description",
+            "actions",
+        )
+        attrs = {"class": "table table-hover table-headings table-striped"}

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/tests/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/urls.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from django.urls import path
+
+from . import views
+
+app_name = "netbox_interface_name_rules"
+
+urlpatterns = [
+    # List / CRUD
+    path("rules/", views.InterfaceNameRuleListView.as_view(), name="interfacenamerule_list"),
+    path("rules/add/", views.InterfaceNameRuleCreateView.as_view(), name="interfacenamerule_add"),
+    path("rules/import/", views.InterfaceNameRuleBulkImportView.as_view(), name="interfacenamerule_bulk_import"),
+    path("rules/bulk_delete/", views.InterfaceNameRuleBulkDeleteView.as_view(), name="interfacenamerule_bulk_delete"),
+    path("rules/<int:pk>/", views.InterfaceNameRuleView.as_view(), name="interfacenamerule_detail"),
+    path("rules/<int:pk>/edit/", views.InterfaceNameRuleEditView.as_view(), name="interfacenamerule_edit"),
+    path("rules/<int:pk>/delete/", views.InterfaceNameRuleDeleteView.as_view(), name="interfacenamerule_delete"),
+    path(
+        "rules/<int:pk>/changelog/",
+        views.InterfaceNameRuleChangeLogView.as_view(),
+        name="interfacenamerule_changelog",
+    ),
+]

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/utils.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+"""Version-detection utilities for the interface name rules plugin."""
+
+MODULE_PATH_MIN_VERSION = "4.9.0"
+
+
+def supports_module_path():
+    """Check if the running NetBox version supports the {module_path} template token."""
+    from django.conf import settings
+
+    version_str = getattr(settings, "VERSION", "0.0.0")
+    version_str = version_str.split("-")[0]
+    try:
+        current = tuple(int(x) for x in version_str.split("."))
+        required = tuple(int(x) for x in MODULE_PATH_MIN_VERSION.split("."))
+        return current >= required
+    except (ValueError, TypeError):
+        return False

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules/views.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from netbox.views import generic
+from utilities.views import register_model_view
+
+from .filters import InterfaceNameRuleFilterSet
+from .forms import InterfaceNameRuleFilterForm, InterfaceNameRuleForm, InterfaceNameRuleImportForm
+from .models import InterfaceNameRule
+from .tables import InterfaceNameRuleTable
+
+
+class InterfaceNameRuleListView(generic.ObjectListView):
+    queryset = InterfaceNameRule.objects.all()
+    table = InterfaceNameRuleTable
+    filterset = InterfaceNameRuleFilterSet
+    filterset_form = InterfaceNameRuleFilterForm
+    template_name = "netbox_interface_name_rules/interfacenamerule_list.html"
+
+    def get_extra_context(self, request):
+        from .utils import MODULE_PATH_MIN_VERSION, supports_module_path
+
+        return {
+            "supports_module_path": supports_module_path(),
+            "module_path_min_version": MODULE_PATH_MIN_VERSION,
+        }
+
+
+class InterfaceNameRuleCreateView(generic.ObjectEditView):
+    queryset = InterfaceNameRule.objects.all()
+    form = InterfaceNameRuleForm
+
+
+@register_model_view(InterfaceNameRule, "bulk_import", path="import", detail=False)
+class InterfaceNameRuleBulkImportView(generic.BulkImportView):
+    queryset = InterfaceNameRule.objects.all()
+    model_form = InterfaceNameRuleImportForm
+
+
+class InterfaceNameRuleView(generic.ObjectView):
+    queryset = InterfaceNameRule.objects.all()
+
+
+class InterfaceNameRuleEditView(generic.ObjectEditView):
+    queryset = InterfaceNameRule.objects.all()
+    form = InterfaceNameRuleForm
+
+
+class InterfaceNameRuleDeleteView(generic.ObjectDeleteView):
+    queryset = InterfaceNameRule.objects.all()
+
+
+class InterfaceNameRuleBulkDeleteView(generic.BulkDeleteView):
+    queryset = InterfaceNameRule.objects.all()
+    table = InterfaceNameRuleTable
+
+
+class InterfaceNameRuleChangeLogView(generic.ObjectChangeLogView):
+    queryset = InterfaceNameRule.objects.all()

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: netbox-interface-name-rules
+Version: 1.0.0
+Summary: NetBox plugin for automatic interface renaming when modules are installed
+License-Expression: Apache-2.0
+Requires-Python: >=3.12.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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} - 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 | Example |
+|----------|---------|
+| Converter offset | GLC-T in CVR-X2-SFP → `GigabitEthernet3/10` |
+| Breakout channels | QSFP-4X10G-LR → `et-0/0/4:0` through `et-0/0/4:3` |
+| Platform naming | QSFP-100G-LR4 on ACX7024 → `et-0/0/{bay_position}` |
+| UfiSpace breakout | QSFP-100G on S9610 → `swp{bay_position_num}s{channel}` |
+
+## Installation
+
+```bash
+pip install netbox-interface-name-rules
+```
+
+Add to `configuration.py`:
+```python
+PLUGINS = ['netbox_interface_name_rules']
+```
+
+## Compatibility
+
+- NetBox ≥ 4.2.0
+- Python ≥ 3.12
+
+## License
+
+Apache 2.0

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+README.md
+pyproject.toml
+netbox_interface_name_rules/__init__.py
+netbox_interface_name_rules/engine.py
+netbox_interface_name_rules/filters.py
+netbox_interface_name_rules/forms.py
+netbox_interface_name_rules/models.py
+netbox_interface_name_rules/navigation.py
+netbox_interface_name_rules/signals.py
+netbox_interface_name_rules/tables.py
+netbox_interface_name_rules/urls.py
+netbox_interface_name_rules/utils.py
+netbox_interface_name_rules/views.py
+netbox_interface_name_rules.egg-info/PKG-INFO
+netbox_interface_name_rules.egg-info/SOURCES.txt
+netbox_interface_name_rules.egg-info/dependency_links.txt
+netbox_interface_name_rules.egg-info/top_level.txt
+netbox_interface_name_rules/api/__init__.py
+netbox_interface_name_rules/api/serializers.py
+netbox_interface_name_rules/api/urls.py
+netbox_interface_name_rules/api/views.py
+netbox_interface_name_rules/migrations/0001_initial.py
+netbox_interface_name_rules/migrations/__init__.py
+netbox_interface_name_rules/tests/__init__.py

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

netbox_interface_name_rules-1.0.0/netbox_interface_name_rules.egg-info/top_level.txt

@@ -0,0 +1 @@
+netbox_interface_name_rules

netbox_interface_name_rules-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "netbox-interface-name-rules"
+version = "1.0.0"
+description = "NetBox plugin for automatic interface renaming when modules are installed"
+readme = "README.md"
+requires-python = ">=3.12.0"
+license = "Apache-2.0"
+
+[tool.setuptools.packages.find]
+include = ["netbox_interface_name_rules*"]
+
+[dependency-groups]
+dev = [
+    "build",
+    "reuse",
+    "ruff",
+    "pre-commit",
+    "pytest",
+    "pytest-django",
+    "python-semantic-release",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["/opt/netbox/netbox"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+ignore = ["E501", "F403", "F405"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["netbox_interface_name_rules/__init__.py:__version__"]
+branch = "main"
+commit_message = "chore(release): {version}\n\nAutomatically generated by python-semantic-release"
+build_command = "python -m build"
+upload_to_vcs_release = true
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

netbox_interface_name_rules-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+