CESNET ServicePath Plugin for NetBox

A NetBox plugin for managing service paths and segments in network infrastructure with advanced geographic path visualization.

📑 Table of Contents

• Overview
• Compatibility Matrix
• Features
• Data Model
• Installation and Configuration
  • Prerequisites
  • Step-by-Step Installation
• Additional Configuration
  • Custom Status Choices
  • Custom Kind Choices
• Geographic Path Data
• API Usage
• Development
• Navigation and UI
• Troubleshooting
• Credits
• License

Overview

The CESNET ServicePath Plugin extends NetBox's capabilities by providing comprehensive network service path management with:

• Interactive geographic path visualization using Leaflet maps, introduced in version 5.0.x
• Support for KML, KMZ, and GeoJSON path data
• Service path and segment relationship management
• Advanced filtering and search capabilities
• REST API and GraphQL support

Compatibility Matrix

NetBox Version	Plugin Version
4.4	5.1.x
4.3	5.0.x
4.2	4.0.x
3.7	0.1.0

Features

Service Path Management

• Define experimental, core, and customer service paths
• Track service path status and metadata
• Link multiple segments to create complete paths
• Visual relationship mapping

Segment Management

• Track network segments between locations
• Monitor installation and termination dates
• Manage provider relationships and contracts
• Link circuits to segments
• Automatic status tracking based on dates
• Geographic path visualization with actual route data
• segment types (dark fiber, optical spectrum, ethernet) with type specific data

Geographic Features

• Interactive map visualization with multiple tile layers (OpenStreetMap, satellite, topographic) and multiple color schema (status, provider, segment type)
• Path data upload supporting KML, KMZ, and GeoJSON formats
• Automatic path length calculation in kilometers
• Multi-segment path support with complex routing
• Fallback visualization showing straight lines when path data unavailable
• Overlapping segment detection and selection on maps
• Path data export as GeoJSON for external use
• An example of a geographic service path visualized using the plugin:

Integration Features

• Template extensions for Circuits, Providers, Sites, and Locations
• Custom table columns showing segment relationships
• Advanced filtering including path data availability
• REST API endpoints with geographic data support
• GraphQL schema with geometry field support

Data Model

Service Path

• Name and status tracking
• Service type classification (experimental/core/customer)
• Multiple segment support through mappings
• Comments and tagging support

Segment

• Provider and location tracking
• Date-based lifecycle management with visual status indicators
• Circuit associations
• Geographic path geometry storage (MultiLineString)
• Path metadata including length, source format, and notes
• Automated status monitoring

Geographic Path Data

• MultiLineString geometry storage in WGS84 (EPSG:4326)
• Multiple path segments support for complex routes
• Automatic 2D conversion from 3D path data
• Length calculation using projected coordinates
• Source format tracking (KML, KMZ, GeoJSON, manual)

Installation and Configuration

⚠️ Important: This plugin requires PostGIS and geographic libraries. Standard NetBox installations need additional setup steps.

Prerequisites

Before installing the plugin, ensure you have:

1. PostgreSQL with PostGIS extension (version 3.0 or higher recommended)
2. System libraries: GDAL, GEOS, and PROJ runtime binaries
3. NetBox 4.2 or higher

Installing System Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install postgresql-15-postgis-3 gdal-bin libgdal34 libgeos-c1t64 libproj25

Note: Package names may vary by Ubuntu/Debian version. Use apt-cache search libgdal to find the correct version for your system.

macOS:

brew install postgresql postgis gdal geos proj

Docker users: The official netboxcommunity/netbox images do NOT include PostGIS and GDAL libraries by default. You will need to create a custom Docker image. See the Docker-specific instructions below.

Step 1: Enable PostGIS in PostgreSQL

Connect to your NetBox database and enable the PostGIS extension:

-- Connect to your NetBox database
\c netbox

-- Enable PostGIS extension
CREATE EXTENSION IF NOT EXISTS postgis;

-- Verify installation
SELECT PostGIS_version();

Step 2: Configure NetBox Database Engine

CRITICAL: Update your NetBox configuration.py to use the PostGIS database engine:

# Set the database engine to PostGIS
DATABASE_ENGINE = "django.contrib.gis.db.backends.postgis"

# PostgreSQL database configuration
DATABASE = {
    "ENGINE": DATABASE_ENGINE,  # Must use PostGIS engine
    "NAME": environ.get("DB_NAME", "netbox"),
    "USER": environ.get("DB_USER", ""),
    "PASSWORD": read_secret("db_password", environ.get("DB_PASSWORD", "")),
    "HOST": environ.get("DB_HOST", "localhost"),
    "PORT": environ.get("DB_PORT", ""),
    "OPTIONS": {"sslmode": environ.get("DB_SSLMODE", "prefer")},
    "CONN_MAX_AGE": int(environ.get("DB_CONN_MAX_AGE", "300")),
}

Note: This is just an example. If you're using NetBox Docker, this can be configured via environment variables in your docker-compose.yml or similar configuration files.

Step 3: Install the Plugin

Standard Installation (pip)

pip install cesnet_service_path_plugin

Docker Installation

The official NetBox Docker images do not include the required geographic libraries. You need to create a custom Docker image.

Option 1: Create a Custom Dockerfile

Create a Dockerfile extending the official NetBox image:

FROM netboxcommunity/netbox:v4.4

# copy plugin requirements
COPY ./plugin_requirements.txt /opt/netbox/

# Install git and minimal PostGIS runtime dependencies
RUN apt-get update && apt-get install -y \
    git \
    gdal-bin \
    libgdal34 \
    libgeos-c1t64 \
    libproj25 \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install PostGIS and geospatial Python dependencies
RUN /usr/local/bin/uv pip install \
    psycopg2-binary \
    -r /opt/netbox/plugin_requirements.txt

Note: Library package names (like libgdal34) may vary depending on the base image's Ubuntu/Debian version. Check available packages if you encounter errors.

Then create a plugin_requirements.txt file:

cesnet_service_path_plugin

Build your custom image:

docker build -t netbox-with-gis:latest .

Update your docker-compose.yml to use the custom image:

services:
  netbox:
    image: netbox-with-gis:latest
    # ... rest of your configuration

Option 2: Use docker-compose override

Add a docker-compose.override.yml file:

version: '3.8'
services:
  netbox:
    build:
      context: .
      dockerfile: Dockerfile.custom

For detailed Docker setup instructions, see using netbox-docker with plugins.

Step 4: Enable the Plugin

Add the plugin to your NetBox configuration.py:

PLUGINS = [
    'cesnet_service_path_plugin',
]

PLUGINS_CONFIG = {
    "cesnet_service_path_plugin": {},
}

Step 5: Run Database Migrations

Apply the plugin's database migrations:

cd /opt/netbox/netbox
source venv/bin/activate
python manage.py migrate cesnet_service_path_plugin

Docker users:

docker exec -it netbox python /opt/netbox/netbox/manage.py migrate cesnet_service_path_plugin

Step 6: Restart NetBox

Restart your NetBox services to load the plugin:

sudo systemctl restart netbox netbox-rq

Docker users:

docker-compose restart netbox netbox-worker

Verification

To verify the installation:

1. Log into NetBox
2. Check that "Service Paths" appears in the navigation menu
3. Navigate to Service Paths → Segments to confirm the plugin is working

For geographic feature verification, you can use the diagnostic function in the Django shell:

python manage.py nbshell

from cesnet_service_path_plugin.utils import check_gis_environment
check_gis_environment()

Additional Configuration

Custom Status Choices

Extend or override default status choices in your configuration.py:

FIELD_CHOICES = {
    'cesnet_service_path_plugin.choices.status': (
        ('custom_status', 'Custom Status', 'blue'),
        # ('status_value', 'Display Name', 'color'),
    )
}

Status choice format:

• Value: Internal database value
• Name: UI display name
• Color: Badge color (blue, green, red, orange, yellow, purple, gray)

Default statuses (Active, Planned, Offline) will be merged with custom choices.

Custom Kind Choices

Extend or override default kind choices in your configuration.py:

FIELD_CHOICES = {
    'cesnet_service_path_plugin.choices.kind': (
        ('custom_kind', 'Custom Kind Name', 'purple'),
        # ('kind_value', 'Display Name', 'color'),
    )
}

Kind choice format:

• Value: Internal database value
• Name: UI display name
• Color: Badge color (blue, green, red, orange, yellow, purple, gray)

Default kinds:

• experimental: Experimentální (cyan)
• core: Páteřní (blue)
• customer: Zákaznická (green)

Custom kinds will be merged with the default choices.

Geographic Path Data

Supported Formats

• GeoJSON (.geojson, .json): Native web format
• KML (.kml): Google Earth format
• KMZ (.kmz): Compressed KML with enhanced support for complex files

Path Data Features

• Automatic format detection from file extension
• Multi-layer KMZ support with comprehensive extraction
• 3D to 2D conversion for compatibility
• Path validation with detailed error reporting
• Length calculation using accurate projections

Map Visualization

• Multiple tile layers: OpenStreetMap, satellite imagery, topographic maps
• Interactive controls: Pan, zoom, fit-to-bounds
• Segment information panels with detailed metadata
• Overlapping segment handling with selection popups
• Status-based color coding for visual identification

API Usage

The plugin provides comprehensive REST API and GraphQL support:

REST API Endpoints

• /api/plugins/cesnet-service-path-plugin/segments/ - Segment management
• /api/plugins/cesnet-service-path-plugin/service-paths/ - Service path management
• /api/plugins/cesnet-service-path-plugin/segments/{id}/geojson-api/ - Geographic data

Example of segment with path file PATCH and POST

See detailed example in docs.

Geographic API Features

• Lightweight list serializers for performance
• Detailed geometry serializers for map views
• GeoJSON export endpoints
• Path bounds and coordinates in API responses

GraphQL Support

Full GraphQL schema with:

• Geographic field support for path geometry
• Filtering capabilities on all geographic fields
• Nested relationship queries

Development

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/CESNET/cesnet_service_path_plugin.git
cd cesnet_service_path_plugin

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate  # Windows

3. Install development dependencies:

pip install -e ".[dev]"

4. Install geographic dependencies:

# Ubuntu/Debian - only runtime libraries needed
sudo apt-get install gdal-bin libgdal34 libgeos-c1t64 libproj25

# macOS
brew install gdal geos proj

# Install Python packages
pip install geopandas fiona shapely

Note: For development, you typically only need the runtime libraries. The Python packages (geopandas, fiona, shapely) use precompiled wheels that already include the necessary bindings. Development headers (-dev packages) are only needed if you're compiling these libraries from source.

Testing Geographic Features

Use the built-in diagnostic function:

from cesnet_service_path_plugin.utils import check_gis_environment
check_gis_environment()

Navigation and UI

The plugin adds a Service Paths menu with:

• Segments - List and manage network segments
• Segments Map - Interactive map view of all segments
• Service Paths - Manage service path definitions
• Mappings - Relationship management tools

Template Extensions

Automatic integration with existing NetBox models:

• Circuit pages: Show related segments
• Provider pages: List provider segments
• Site/Location pages: Display connected segments
• Tenant pages: Show associated provider information

Troubleshooting

Common Issues

1. PostGIS not enabled: Ensure PostGIS extension is installed in your database
2. GDAL library missing: Install system GDAL runtime libraries (gdal-bin, libgdal34) before Python packages
3. Path upload fails: Check file format and ensure it contains LineString geometries
4. Map not loading: Verify JavaScript console for tile layer errors
5. Library version mismatch: If you encounter errors about missing libraries, check that library package names match your OS version (e.g., libgdal34 vs libgdal32)

Debug Mode

Enable detailed logging for geographic operations:

LOGGING = {
    'loggers': {
        'cesnet_service_path_plugin.utils': {
            'level': 'DEBUG',
            'handlers': ['console'],
        },
    },
}

Credits

• Created using Cookiecutter and netbox-community/cookiecutter-netbox-plugin
• Based on the NetBox plugin tutorial
• Geographic features powered by GeoPandas, Leaflet, and PostGIS

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.