feat: LibreNMS location mapping and location string parsing

contrib/README.md

@@ -23,6 +23,7 @@ feature in the NetBox UI.
 | `normalization_rules.yaml` | Regex-based string normalization applied before module type/bay lookups |
 | `inventory_ignore_rules.yaml` | Suppresses phantom ENTITY-MIB entries (e.g. Cisco IOS-XR IDPROM artefacts) |
 | `platform_mappings.yaml` | Maps LibreNMS platform strings to NetBox device platforms |
+| `location_mappings.yaml` | Maps LibreNMS location values to NetBox regions, sites, locations, racks, or tenants |
 
 ## Customisation
 

contrib/location_mappings.yaml

@@ -0,0 +1,53 @@
+# Location Mappings — Examples
+#
+# Maps a LibreNMS `location` value (or a token parsed from it) to a specific
+# NetBox organisation object: a Region, Site, Location, Rack, or Tenant.
+#
+# Used when the LibreNMS value does not match the NetBox object's name exactly.
+# Matching is exact (case-insensitive) on `librenms_value`.
+#
+# Import via: LibreNMS → Location Mappings → Import → YAML
+#
+# Fields:
+#   field_type     — one of: region, site, location, rack, tenant
+#   librenms_value — the value as it appears in LibreNMS (e.g. "NYC")
+#   netbox_object  — the NetBox object's name (must already exist in NetBox)
+#   parent_site    — (optional) restricts location/rack lookups to this site,
+#                    since NetBox scopes locations and racks to a parent site
+#   description    — (optional) free-text notes
+
+# ── Region ────────────────────────────────────────────────────────────────────
+- field_type: region
+  librenms_value: us-east
+  netbox_object: US East
+  description: LibreNMS region code to NetBox Region
+
+# ── Site ──────────────────────────────────────────────────────────────────────
+- field_type: site
+  librenms_value: NYC
+  netbox_object: New York
+  description: LibreNMS site abbreviation to NetBox Site
+
+- field_type: site
+  librenms_value: LDN
+  netbox_object: London
+  description: LibreNMS site abbreviation to NetBox Site
+
+# ── Location ──────────────────────────────────────────────────────────────────
+# Scope to a parent site so the same value can differ per site.
+- field_type: location
+  librenms_value: Hall A
+  netbox_object: Data Hall A
+  parent_site: New York
+
+# ── Rack ──────────────────────────────────────────────────────────────────────
+- field_type: rack
+  librenms_value: R1
+  netbox_object: Rack-001
+  parent_site: New York
+
+# ── Tenant ────────────────────────────────────────────────────────────────────
+- field_type: tenant
+  librenms_value: acme
+  netbox_object: ACME Corp
+  description: LibreNMS tenant code to NetBox Tenant

netbox_librenms_plugin/api/serializers.py

@@ -5,6 +5,7 @@
     DeviceTypeMapping,
     InterfaceTypeMapping,
     InventoryIgnoreRule,
+    LocationMapping,
     ModuleBayMapping,
     ModuleTypeMapping,
     NormalizationRule,
@@ -112,6 +113,23 @@ class Meta:
         ]
 
 
+class LocationMappingSerializer(NetBoxModelSerializer):
+    """Serialize LocationMapping model for REST API."""
+
+    class Meta:
+        """Meta options for LocationMappingSerializer."""
+
+        model = LocationMapping
+        fields = [
+            "id",
+            "field_type",
+            "librenms_value",
+            "content_type",
+            "object_id",
+            "description",
+        ]
+
+
 class CarrierAutoInstallRuleSerializer(NetBoxModelSerializer):
     """Serialize CarrierAutoInstallRule model for REST API."""
 

netbox_librenms_plugin/api/urls.py

@@ -13,6 +13,7 @@
 router.register("normalization-rules", views.NormalizationRuleViewSet)
 router.register("inventory-ignore-rules", views.InventoryIgnoreRuleViewSet)
 router.register("platform-mappings", views.PlatformMappingViewSet)
+router.register("location-mappings", views.LocationMappingViewSet)
 router.register("carrier-auto-install-rules", views.CarrierAutoInstallRuleViewSet)
 
 urlpatterns = [

netbox_librenms_plugin/api/views.py

@@ -17,6 +17,7 @@
     DeviceTypeMappingFilterSet,
     InterfaceTypeMappingFilterSet,
     InventoryIgnoreRuleFilterSet,
+    LocationMappingFilterSet,
     ModuleBayMappingFilterSet,
     ModuleTypeMappingFilterSet,
     NormalizationRuleFilterSet,
@@ -28,6 +29,7 @@
     DeviceTypeMapping,
     InterfaceTypeMapping,
     InventoryIgnoreRule,
+    LocationMapping,
     ModuleBayMapping,
     ModuleTypeMapping,
     NormalizationRule,
@@ -39,6 +41,7 @@
     DeviceTypeMappingSerializer,
     InterfaceTypeMappingSerializer,
     InventoryIgnoreRuleSerializer,
+    LocationMappingSerializer,
     ModuleBayMappingSerializer,
     ModuleTypeMappingSerializer,
     NormalizationRuleSerializer,
@@ -134,6 +137,16 @@ class PlatformMappingViewSet(NetBoxModelViewSet):
     serializer_class = PlatformMappingSerializer
 
 
+class LocationMappingViewSet(NetBoxModelViewSet):
+    """API viewset for LocationMapping CRUD operations."""
+
+    permission_classes = [LibreNMSPluginPermission]
+    filterset_class = LocationMappingFilterSet
+
+    queryset = LocationMapping.objects.select_related("content_type")
+    serializer_class = LocationMappingSerializer
+
+
 class CarrierAutoInstallRuleViewSet(NetBoxModelViewSet):
     """API viewset for CarrierAutoInstallRule CRUD operations."""
 

netbox_librenms_plugin/filters.py

@@ -6,6 +6,7 @@
     DeviceTypeMapping,
     InterfaceTypeMapping,
     InventoryIgnoreRule,
+    LocationMapping,
     ModuleBayMapping,
     ModuleTypeMapping,
     NormalizationRule,
@@ -120,6 +121,20 @@ class Meta:
         fields = ["librenms_os", "description"]
 
 
+class LocationMappingFilterSet(django_filters.FilterSet):
+    """Filter set for LocationMapping model."""
+
+    field_type = django_filters.CharFilter(lookup_expr="iexact")
+    librenms_value = django_filters.CharFilter(lookup_expr="icontains")
+    description = django_filters.CharFilter(lookup_expr="icontains")
+
+    class Meta:
+        """Meta options for LocationMappingFilterSet."""
+
+        model = LocationMapping
+        fields = ["field_type", "librenms_value", "description"]
+
+
 class CarrierAutoInstallRuleFilterSet(django_filters.FilterSet):
     """Filter set for CarrierAutoInstallRule model."""