Metadata-Version: 2.4
Name: netbox-geoview
Version: 0.10.0
Summary: NetBox plugin for geospatial map views, tile layers, and optional route planning
Author: Philipp Prohaszka
License-Expression: MIT
Project-URL: Homepage, https://github.com/phlpr/netbox_geoview
Project-URL: Repository, https://github.com/phlpr/netbox_geoview
Project-URL: Issues, https://github.com/phlpr/netbox_geoview/issues
Keywords: netbox,plugin,geospatial,map,gis,network
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# NetBox GeoView

NetBox GeoView is a NetBox plugin for displaying infrastructure in a map-oriented view.

It provides:

- a Leaflet map with configurable raster tile layers
- filters for sites, devices, device status, tags, ownership, tenancy, and related objects
- reusable saved filters and native dashboard map widgets
- device-role filters with inclusion/exclusion and descendant roles
- optional device-role colors and per-role marker styles
- configurable site and device popups, including custom fields
- direct-distance measurement and optional Valhalla route calculation
- reusable development test data for sites, locations, device types, devices, and custom fields

## Versioning

The plugin uses Semantic Versioning in the format `MAJOR.MINOR.PATCH`.

- `MAJOR`: incompatible plugin changes
- `MINOR`: new backward-compatible features
- `PATCH`: bug fixes and small corrections

NetBox compatibility is managed separately through `min_version` and `max_version` in the plugin.

## Project Note

This is a personal project to see how far one can go with a practical NetBox plugin idea.

Most of the code was generated with Codex as a coding co-pilot, but maintenance responsibility stays with the developer (the human still carries the pager).

## Compatibility

| Plugin Release | NetBox |
|---|---|
| `0.10.0` | `4.5.4` to `4.7.4` |

Later NetBox versions are not included automatically. See
[testing details](TESTING.md) for validation reports and test instructions.

Starting with 0.8.1, GeoView requires an authenticated, active user with
`dcim.view_site` **or** `dcim.view_device`. The menu is hidden otherwise, and the
same rule protects every GeoView endpoint, including tiles and routing. Anonymous
requests redirect to login even when NetBox's `LOGIN_REQUIRED` is disabled;
authenticated users without either permission receive HTTP 403. This also
applies on NetBox 4.5.10.

Permissions are evaluated through NetBox, including group/default permissions,
superusers and `EXEMPT_VIEW_PERMISSIONS`. Exemptions do not bypass GeoView's login
requirement. No separate GeoView permission or plugin model is needed. Object
constraints still limit the sites/devices shown, and users need view access to
related filter objects they want to select.
Saved filters must be enabled and shared or owned by the current user.
Saved filters containing unsupported conditions, such as `cf_*` custom-field
filters, are rejected with a visible error rather than silently broadening the map.

GeoView 0.9.0 adds a dedicated save/update/copy workflow and a native
NetBox dashboard widget. See [saved filters and widgets](docs/saved-filters-widgets.md)
for usage, filter semantics and permissions. It also adds device-role filtering
and optional role-based marker styles. GeoView 0.10.0 adds device-status filters,
native saved-filter slugs, tile revalidation and smoother map reloads. See the
[NetBox 4.7.4 validation report](docs/validation/netbox-4.7.4.md) for compatibility
checks and upstream upgrade notes.

## Installation

Install [netbox-geoview from PyPI](https://pypi.org/project/netbox-geoview/)
inside the NetBox virtual environment:

```bash
python -m pip install --upgrade netbox-geoview==0.10.0
```

Optional: install directly from a tagged GitHub source archive:

```bash
pip install https://github.com/phlpr/netbox_geoview/archive/refs/tags/v0.10.0.tar.gz
```

## Screenshots

GeoView 0.9.0 on NetBox 4.7.3, using synthetic network data in Austria.
Role colors and letter symbols are enabled in the demo configuration; see
[marker appearance](#device-role-marker-appearance) for the settings.
Click an image to view it at full size.

**Map with device-role colors**

[![GeoView map showing Austrian routers, switches, access switches and firewalls with role colors and symbols](https://raw.githubusercontent.com/phlpr/netbox_geoview/main/docs/screenshots/map-role-colors.jpg)](https://github.com/phlpr/netbox_geoview/blob/main/docs/screenshots/map-role-colors.jpg)

<details>
<summary>Saved filters, dashboard widgets and routing</summary>

**Saved filters and device roles**

Load a saved selection and refine it with location, hardware and device-role filters.

[![GeoView filter tab with the saved Austria Switches filter and a selected device role](https://raw.githubusercontent.com/phlpr/netbox_geoview/main/docs/screenshots/saved-filters-and-roles.jpg)](https://github.com/phlpr/netbox_geoview/blob/main/docs/screenshots/saved-filters-and-roles.jpg)

**Native NetBox dashboard widgets**

Show different saved selections side by side, with independent maps and refresh controls.

[![Two native GeoView dashboard widgets showing the complete Austrian demo network and its switches](https://raw.githubusercontent.com/phlpr/netbox_geoview/main/docs/screenshots/dashboard-widgets.jpg)](https://github.com/phlpr/netbox_geoview/blob/main/docs/screenshots/dashboard-widgets.jpg)

**Routing in dark mode**

Compare a calculated road route with the direct distance between two devices.

[![GeoView in dark mode with a calculated Linz to Vienna route and direct-distance measurement](https://raw.githubusercontent.com/phlpr/netbox_geoview/main/docs/screenshots/routing-dark.jpg)](https://github.com/phlpr/netbox_geoview/blob/main/docs/screenshots/routing-dark.jpg)

</details>

## Configuration

Example plugin settings for `configuration.py`:

```python
PLUGINS = ["netbox_geoview"]

PLUGINS_CONFIG = {
    "netbox_geoview": {
        "start_latitude": 47.59397,
        "start_longitude": 14.12456,
        "start_zoom": 7,
        "min_zoom": 2,
        "max_zoom": 19,
        "valhalla_url": "https://valhalla1.openstreetmap.de/route",
        "valhalla_timeout": 10,
        "valhalla_costing_options": ["auto", "bicycle", "pedestrian"],
        "valhalla_default_costing": "auto",
        "valhalla_request_defaults": {
            "alternates": 1,
            "directions_options": {
                "units": "kilometers",
            },
        },
        "valhalla_headers": {
            "X-Client-Id": "your-company-netbox-geoview",
        },
        "valhalla_query": {},
        "default_tile_layer": "OpenStreetMap",
        "scroll_wheel_zoom": True,
        "site_marker": {
            "color": "#f1c40f",
            "symbol": "",
            "icon_url": "",
            "icon_size": [28, 40],
            "icon_anchor": [14, 40],
            "popup_anchor": [0, -34],
        },
        "site_group_markers": {
            "burgenland": {"color": "#f1c40f"},
            "karnten": {"color": "#e74c3c"},
            "niederosterreich": {"color": "#3498db"},
            "oberosterreich": {"color": "#2ecc71"},
            "salzburg": {"color": "#ff69b4"},
            "steiermark": {"color": "#16a085"},
            "tirol": {"color": "#9b59b6"},
            "vorarlberg": {"color": "#34495e"},
            "wien": {"color": "#f39c12"},
        },
        "use_role_colors": False,
        "device_role_markers": {
            "core-router": {"symbol": "R"},
            "access-switch": {"symbol": "S"},
            "firewall": {"color": "#e74c3c", "symbol": "F"},
        },
        "tile_layers": [
            {
                "name": "OpenStreetMap",
                "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
                "attribution": "&copy; OpenStreetMap contributors",
            },
            {
                "name": "OpenStreetMap DE",
                "url": "https://tile.openstreetmap.de/{z}/{x}/{y}.png",
                "attribution": "&copy; OpenStreetMap contributors",
            },
            {
                "name": "OpenStreetMap HOT",
                "url": "https://a.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png",
                "attribution": "&copy; OpenStreetMap contributors, Humanitarian OpenStreetMap Team",
            },
            {
                "name": "MapTiler Satellite",
                "url": "https://api.maptiler.com/maps/satellite/{z}/{x}/{y}.jpg",
                "attribution": "&copy; MapTiler",
                "query": {
                    "key": "YOUR_MAPTILER_API_KEY",
                },
            },
            {
                "name": "MapTiler Hybrid",
                "url": "https://api.maptiler.com/maps/hybrid/{z}/{x}/{y}.png",
                "attribution": "&copy; MapTiler",
                "query": {
                    "key": "YOUR_MAPTILER_API_KEY",
                },
            },
        ],
        "tile_provider_url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    }
}
```

The same example is included in [configuration.example.py](./configuration.example.py).

Available settings:

- `start_latitude`: initial map latitude
- `start_longitude`: initial map longitude
- `start_zoom`: initial map zoom level
- `min_zoom`: minimum allowed zoom level
- `max_zoom`: maximum allowed zoom level
- `valhalla_url`: base URL of the Valhalla route endpoint
- `valhalla_timeout`: timeout in seconds for route requests
- `valhalla_costing_options`: route profile options shown in UI
- `valhalla_default_costing`: default route profile
- `valhalla_request_defaults`: additional request payload defaults
- `valhalla_headers`: optional HTTP headers for Valhalla requests
- `valhalla_query`: optional query string parameters for Valhalla requests
- `default_tile_layer`: default base layer name or ID
- `scroll_wheel_zoom`: enables zooming with the mouse wheel
- `site_marker`: base marker appearance for sites and devices
- `site_group_markers`: marker overrides by site group name or slug
- `use_role_colors`: Boolean switch to use NetBox device-role colors; default `False`
- `device_role_markers`: per-role color, symbol or image overrides by role ID, slug or name
- `tile_layers`: list of available base layers
- `query`: optional query string parameters per layer, useful for API keys
- `headers`: optional HTTP headers per layer
- `tile_provider_url`: upstream tile URL template with `{z}`, `{x}`, and `{y}`

### Device-role marker appearance

Set `use_role_colors=True` to color device pins with their assigned NetBox
DeviceRole's color. Only the Boolean `True` enables this; do not use strings
such as `"true"` or `"false"`. Site markers keep their existing appearance.

Styles are applied in this order, with later values overriding earlier ones:

1. The existing `site_marker` and matching `site_group_markers` style.
2. The NetBox role color, when `use_role_colors` is `True`.
3. A matching `device_role_markers` entry, independently of the switch.

With the switch off and no role override, device markers look as before.
Role overrides support the same fields as `site_marker`: `color`, `symbol`,
`icon_url`, `icon_size`, `icon_anchor` and `popup_anchor`. Specify only the fields
you want to change. An explicit role-marker `color` wins over the NetBox color.
Use `icon_url=""` to clear an inherited image and return to a colored pin.

For a custom image, provide its URL and optional sizing, for example:

```python
"device_role_markers": {
    "core-router": {
        "icon_url": "https://assets.example.net/netbox/router.svg",
        "icon_size": [32, 40],
        "icon_anchor": [16, 40],
        "popup_anchor": [0, -34],
    },
}
```

Replace the example URL with an image you host; local `/static/...` URLs also
work. Custom images retain their own colors; the role color applies to the
built-in pin. The `symbol` option adds plain text to that pin.

Matching is case-insensitive. If multiple entries match, the role's numeric ID
(an integer or string key) wins over its slug, which wins over its name. IDs
can distinguish duplicate names/slugs in a role hierarchy. Overrides apply to
the assigned role itself; child roles use their own color and configuration.
The full map and dashboard widgets share this styling. Restart NetBox after
changing plugin configuration.

## Satellite Providers

Providers with official API-key-based access that fit this plugin well:

- `MapTiler Satellite`: simple raster tile API with API key in the request. Official docs: [MapTiler Cloud API](https://docs.maptiler.com/cloud/api/)
- `MapTiler Hybrid`: raster hybrid style with satellite imagery plus labels and borders, also usable with an API key. Inference from MapTiler's documented style family plus verified tile endpoint.
- `Mapbox Satellite`: raster tiles with access token authentication. Official docs: [Mapbox Tilesets Reference](https://docs.mapbox.com/data/tilesets/reference/mapbox-satellite/)
- `Esri World Imagery`: enterprise-capable imagery via ArcGIS location services and token-based authentication. Official docs: [ArcGIS service endpoints](https://developers.arcgis.com/documentation/mapping-and-location-services/service-endpoints/) and [Esri Leaflet basemap example](https://developers.arcgis.com/esri-leaflet/maps/raster-tile-basemaps/display-multiple-basemap-layers/)

Recommendation:

- `MapTiler Satellite` is the easiest fit for the current plugin because it follows a straightforward raster tile pattern with an API key.
- `Mapbox Satellite` also fits well and can be configured today with `query.access_token`.
- `Esri World Imagery` is a strong enterprise option, but its exact request pattern depends on the ArcGIS endpoint and token model you want to use.

## Requirements

- GeoView `0.10.0`: NetBox `4.5.4` through `4.7.4`.
- Python `>=3.12`
- No additional Python runtime dependencies are required beyond NetBox's own environment
- Installation in the NetBox virtual environment (see [Installation](#installation))
- Plugin activation in `configuration.py`:
  - `PLUGINS = ["netbox_geoview"]`
  - `PLUGINS_CONFIG = {"netbox_geoview": {...}}`
- For MapTiler layers: valid API key (`query.key`)
- Optional for routing: reachable Valhalla endpoint (`valhalla_url`)

## Development Test Data

Release `0.6.0` includes an idempotent management command that creates a
reusable development data set:

```bash
python manage.py seed_geoview_testdata
```

The command is intended only for development and test databases. It creates or
updates clearly prefixed sites, locations, device types, devices, roles, and
custom fields. See [TESTDATA.md](./TESTDATA.md) for details and for using a
custom JSON definition.

## Firewall / Network Allowlist

NetBox GeoView fetches external map and route data server-side. So the egress rules must be applied on the NetBox host (or its outbound proxy), not only on client browsers.

Required for default tile setup:

- `HTTPS/443` to `tile.openstreetmap.org`
- `HTTPS/443` to `tile.openstreetmap.de`
- `HTTPS/443` to `a.tile.openstreetmap.fr`

Required when using MapTiler layers:

- `HTTPS/443` to `api.maptiler.com`

Optional when routing is enabled (Valhalla):

- `HTTPS/443` to your configured Valhalla host from `valhalla_url`
- For the shipped example: `HTTPS/443` to `valhalla1.openstreetmap.de`

Valhalla itself is MIT-licensed and can be self-hosted commercially. The
example endpoint is a public demonstration service, not an enterprise service:
fair-use limits apply and no availability guarantee is provided. Applications
using that endpoint should send an identifying `X-Client-Id` header. For
production or high-volume use, self-host Valhalla or use a provider with an
appropriate SLA.

The default map and routing data is based on OpenStreetMap. Keep the visible
`© OpenStreetMap contributors` attribution and comply with the ODbL when using
or redistributing derived data.

If your environment uses an explicit outbound proxy, make sure NetBox can reach these hosts through that proxy and that TLS inspection does not break certificate validation.
