netbox-render

A NetBox plugin that subdivides device bay rectangles in rack elevation SVGs to show per-bay labels, role colors, and clickable links to child devices.

What it does

NetBox's rack elevation view renders devices with device bays as a single opaque rectangle, showing only an occupancy count (e.g. "3/4"). Child devices installed in bays are invisible — you must click into the parent device and check its Device Bays tab to see what's installed.

This plugin patches the elevation renderer so that any device with device bays has its rectangle subdivided into one section per bay. Each section shows:

• A sequential index number (1, 2, 3, ...) based on bay name sort order
• The child device name installed in that bay, or (empty) if no device is installed
• Role-based coloring matching the child device's assigned role (front face only; rear face renders grey, consistent with stock NetBox behavior)
• A clickable link to the child device's detail page (empty bays are not clickable)

Devices without device bays are completely unaffected — their rendering is identical to stock NetBox.

Bay ordering caveat

Bay sections are numbered sequentially (1, 2, 3, ...) in the order the device's bays sort by name. NetBox device bays have no separate numeric position field, so this ordering reflects alphabetical/natural sort of bay names, not a silkscreen-printed slot number on the physical hardware. For example, if bays are named "Bay A", "Bay B", "Bay C", they will be numbered 1, 2, 3 in that order.

Compatibility

The plugin declares min_version = '4.6.0' and max_version = '4.6.99' in its configuration. NetBox will refuse to load the plugin if the version falls outside this range, displaying a clear error at startup.

Additionally, the plugin verifies the internal method signature it patches (RackElevationSVG._draw_device) at startup. If the signature doesn't match what's expected, the plugin raises a RuntimeError with a descriptive message rather than silently producing incorrect renderings. This guards against internal API changes within the supported version range.

Installation

1. Install the plugin into your NetBox virtual environment:

   pip install netbox-render
   

   Or for development:

   cd /path/to/netbox-render
   pip install -e .
   

2. Add the plugin to your NetBox configuration (configuration.py):

   PLUGINS = [
       'netbox_render',
   ]
   

3. Restart NetBox:

   sudo systemctl restart netbox netbox-rq
   

   A restart is required for the plugin to take effect. This is standard behavior for all NetBox plugins and is not a bug.

Configuration

The plugin supports one configuration option, set through NetBox's standard PLUGINS_CONFIG in configuration.py:

enable_images

Controls whether device type images are rendered inside each bay section.

To enable image rendering:

PLUGINS_CONFIG = {
    'netbox_render': {
        'enable_images': True,
    },
}

When enabled, each bay section with an installed child device will display the child device type's front or rear image (matching the elevation face being viewed), with a text label overlay for readability.

Changing this setting requires a NetBox restart to take effect.

Shelf device modeling guide

If you are new to representing shelf-mounted devices in NetBox, see docs/shelf-devices-guide.md for a step-by-step walkthrough covering how to create shelf device types, child device types, and how this plugin improves their rack elevation rendering.

Known limitations

• Bay ordering is name-based: Section numbering reflects alphabetical/natural sort of bay names, not physical slot positions. There is no way to override this without adding fields to the NetBox data model, which is explicitly out of scope.
• No images by default: Device type images in bay sections are disabled by default and must be explicitly enabled via configuration.
• Rear face coloring: Bay sections on the rear face render as grey (the stock "blocked" pattern), consistent with how NetBox renders rear-facing devices. Only the front (mounted) face shows role-based colors.
• Front/rear parity: Both front and rear elevation views show the same subdivided bay breakdown. There is no face-specific filtering of bays.
• No data model changes: This plugin makes no migrations and adds no database fields. It is a rendering-only modification.
• Monkeypatch approach: Because NetBox provides no plugin hook for SVG elevation rendering, this plugin patches an internal method at runtime. The signature check at startup mitigates the risk of silent breakage, but NetBox version upgrades should always be tested with this plugin before deploying to production.

Validation checklist

After installing the plugin on a live NetBox instance, verify the following:

• No-bay regression: A device with no device bays renders exactly as it did before the plugin was installed. This is the most important check — compare the elevation visually with and without the plugin.
• All-empty bays: A device with device bays defined but no child devices installed renders subdivided sections, all showing "(empty)".
• Partially filled bays: A device with some bays filled and some empty renders a mix of named child devices and "(empty)" sections, in the correct relative order (by bay name sort).
• Click navigation: Clicking a subdivided section with a child device installed navigates to that child device's detail page.
• Empty bay click: Clicking an empty bay section does not navigate anywhere (no link).
• Role colors (front): On the front face, each bay section with a child device is colored according to the child device's role color.
• Grey rear face: On the rear face, bay sections render as grey (blocked pattern), matching stock behavior for rear-facing devices.
• Default config (no images): With enable_images at its default (False), bay sections show name-only text labels.
• Image config override: After setting enable_images: True in PLUGINS_CONFIG and restarting, bay sections display device type images alongside labels.
• Version check: The plugin starts cleanly on a compatible NetBox version (4.6.x). If tested against an incompatible version, it produces a clear startup error rather than loading silently.

License

Apache-2.0