MrBlake/mrb-netbox-topology-views
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README in English with standard structure

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
MrBlake
2026-09-30 13:37:00 +02:00
co-authored by Claude Opus 5.5
parent 4a12037ac4
commit ffe594a5f9
1 changed files with 140 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+140 -146
View File
@@ -1,92 +1,95 @@
# MRB NetBox Topology Views # MRB NetBox Topology Views
Ein angepasster Fork von **NetBox Topology Views** mit erweiterten Rack-Ansichten, A customised fork of **NetBox Topology Views** with extended rack views,
interaktiver Kabelverfolgung und zusätzlichen Netzwerk-Icons. interactive cable tracing and additional network icons.
Das Plugin erzeugt Topologien aus den in NetBox gepflegten Geräten, Ports und The plugin builds topologies from the devices, ports and cables maintained in
Kabeln. Neben der klassischen Topologie bietet dieser Fork eine vollständige NetBox. In addition to the classic topology, this fork provides a complete view
Darstellung einzelner oder mehrerer Racks einschließlich Vorderseite, of one or more racks including front, rear and cabling.
Rückseite und Verkabelung.
## Vorteile dieses Forks | | |
|---|---|
| **Plugin name** | `netbox_topology_views` |
| **Package** | `netbox-topology-views` |
| **NetBox** | `4.7.x` |
| **Python** | see `setup.py` |
| **Repository** | <https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views> |
- Ein oder mehrere Racks gemeinsam anzeigen ## Features
- Geräte positionsgenau anhand ihrer Höheneinheiten darstellen
- Vorder- und Rückseite eines Racks getrennt betrachten
- Auf- und absteigende HE-Nummerierung sowie individuelle Start-HE automatisch berücksichtigen
- Rackübergreifende und externe Kabelverbindungen erkennen
- Geräte in der Kabeltopologie frei verschieben
- Geräte in der Kabeltopologie innerhalb jedes Racks nach ihrer Rackposition sortieren
- Kabeltopologie in den Browser-Vollbildmodus schalten
- Kabeltopologie zwischen 50 und 200 Prozent zoomen und im Vollbild scrollen
- Geräte in der Kabeltopologie mit rund 5 mm Abstand darstellen
- P2P-WirelessLinks und Multi-Access-WLANs als violette, gestrichelte Funkstrecken darstellen
- Funk-/WLAN-Verbindungen und Stromkabel in der Kabeltopologie der Rack-Ansicht optional ein-/ausblenden, farblich abgesetzt von Netzwerkkabeln (violett gestrichelt bzw. orange gepunktet)
- Manuelle Positionen pro Rack-Auswahl im Browser speichern
- Verbindungen eines Geräts beim Hover weiß hervorheben
- Alle verbundenen Ports und Gegenstellen eines Geräts anzeigen
- Schnittstellen eines Kabels beim Hover anzeigen
- Geräte und Kabel direkt aus der Topologie in NetBox öffnen
- Einzelne Racks, alle Racks oder die Kabeltopologie als SVG, PNG und draw.io exportieren
- Exporte grundsätzlich mit transparentem Hintergrund erzeugen
- Farben von Rackansicht und Export an den aktiven Light- oder Dark-Mode anpassen
- Topologie als PNG oder diagrams.net/draw.io-XML exportieren
- Zusätzliche Icons für Network-, Leaf-, Spine- und Aggregation-Switche
- Unterstützung für helle und dunkle NetBox-Themes
## Änderungen gegenüber dem Original - Show one or more racks together
- Render devices at their exact rack unit position
- View front and rear of a rack separately
- Ascending/descending U numbering and custom starting unit are respected automatically
- Detect cross-rack and external cable connections
- Freely move devices in the cable topology
- Sort devices in the cable topology by rack position within each rack
- Browser full-screen mode for the cable topology
- Zoom the cable topology between 50 and 200 % and scroll in full-screen
- Render P2P wireless links and multi-access WLANs as purple dashed radio links
- Optionally show/hide wireless links and power cables in the rack view's cable topology, visually distinct from network cables (purple dashed / orange dotted)
- Store manual positions per rack selection in the browser
- Highlight a device's connections in white on hover
- Show all connected ports and peers of a device
- Show a cable's terminations on hover
- Open devices and cables in NetBox directly from the topology
- Export single racks, all racks or the cable topology as SVG, PNG and draw.io — always with transparent background
- Colours of rack view and export follow the active light or dark mode
- Additional icons for network, leaf, spine and aggregation switches
Dieser Fork ergänzt insbesondere: ### Changes compared to the original
1. Die neue Menükategorie **Weitere Ansichten**. 1. New menu category **More views**.
2. Eine Rack-Ansicht mit Filtern für Site, Location und mehrere Racks. 2. A rack view with filters for site, location and multiple racks.
3. Positionsgenaue Rack-Elevations für Vorder- und Rückseite. 3. Position-accurate rack elevations for front and rear.
4. Eine Kabeltabelle mit A- und B-Terminierungen. 4. A cable table with A and B terminations.
5. Eine interaktive, verschiebbare Kabeltopologie unter den Racks. 5. An interactive, movable cable topology below the racks.
6. Hover-Hervorhebung und Port-zu-Port-Verfolgung für Geräte und Kabel. 6. Hover highlighting and port-to-port tracing for devices and cables.
7. Lokal gespeicherte Gerätepositionen und eine Funktion zum Zurücksetzen. 7. Locally stored device positions and a reset function.
8. Ein erweitertes, skalierbares SVG-Iconset für Switch-Rollen. 8. An extended, scalable SVG icon set for switch roles.
9. Transparente SVG-, PNG- und draw.io-Exporte für Rack- und Topologieansichten. 9. Transparent SVG, PNG and draw.io exports for rack and topology views.
10. Anpassungen für die Verwendung mit NetBox 4.6, darunter die geänderte 10. Adjustments for NetBox 4.6+, including the changed `Rack.units` property.
`Rack.units`-Property.
## Vorschau
Die klassische Topologieansicht stammt aus dem ursprünglichen Plugin:
![Topology in light mode](doc/img/topology_light.png) ![Topology in light mode](doc/img/topology_light.png)
![Topology in dark mode](doc/img/topology_dark.png) ![Topology in dark mode](doc/img/topology_dark.png)
## Installation aus Gitea ## Compatibility
Das Plugin kann direkt aus dem `develop`-Branch installiert werden: - NetBox `4.7.x` (`min_version`/`max_version` in `netbox_topology_views/__init__.py`)
- Based on NetBox Topology Views `4.5.1`
Since the upstream release officially targets NetBox 4.5.x, test updates to
newer NetBox versions in a staging instance first.
## Installation
All paths assume a standard installation under `/opt/netbox`.
### 1. Install the package
```bash ```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ /opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop"
``` ```
Für eine reproduzierbare Produktivinstallation sollte statt `develop` ein For reproducible production installs, replace `develop` with a release tag or a
Release-Tag oder ein bestimmter Commit verwendet werden: full commit ID.
### 2. Add the plugin to `local_requirements.txt`
This makes `upgrade.sh` reinstall the plugin automatically on every NetBox upgrade:
```bash ```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ grep -qxF "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" /opt/netbox/local_requirements.txt \
"git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@v4.5.1-mrb.1" || echo "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" | sudo tee -a /opt/netbox/local_requirements.txt
``` ```
Für automatische Neuinstallationen bei einem NetBox-Upgrade wird derselbe If the repository is private, the NetBox server needs a read-only deploy token
Eintrag in `/opt/netbox/local_requirements.txt` hinterlegt: or an SSH key. Do not store credentials in `local_requirements.txt`.
```text ### 3. Enable the plugin
git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop
```
Bei einem privaten Gitea-Repository muss der NetBox-Server Zugriff über einen In `/opt/netbox/netbox/netbox/configuration.py`:
Deploy-Token oder SSH-Key erhalten.
## NetBox-Konfiguration
In `netbox/configuration.py` wird das Python-Paket aktiviert:
```python ```python
PLUGINS = [ PLUGINS = [
@@ -102,135 +105,126 @@ PLUGINS_CONFIG = {
} }
``` ```
Danach werden Migrationen und statische Dateien verarbeitet: If other plugins are already configured, add `netbox_topology_views` to the
existing list and dictionary instead of replacing them.
### 4. Apply migrations, collect static files, restart
```bash ```bash
cd /opt/netbox/netbox cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate /opt/netbox/venv/bin/python manage.py migrate netbox_topology_views
/opt/netbox/venv/bin/python manage.py collectstatic --no-input /opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq sudo systemctl restart netbox netbox-rq
``` ```
Nach Änderungen an CSS oder Icons kann ein Hard-Reload des Browsers mit After changes to CSS or icons a hard reload in the browser (`Ctrl+F5`) may be
`Strg+F5` erforderlich sein. necessary.
## Aktualisierung ## Update
```bash ```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ /opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop"
cd /opt/netbox/netbox cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate /opt/netbox/venv/bin/python manage.py migrate netbox_topology_views
/opt/netbox/venv/bin/python manage.py collectstatic --no-input /opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq sudo systemctl restart netbox netbox-rq
``` ```
`--force-reinstall` ist derzeit sinnvoll, da der Fork intern noch die `--force-reinstall` is required because the fork still uses the internal
Paketversion `4.5.2` verwendet. package version `4.5.2`.
## Verwendung When NetBox itself is upgraded, `upgrade.sh` reinstalls the plugin from
`local_requirements.txt` and runs migrations and `collectstatic`:
### Klassische Topologie ```bash
sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq
```
Unter **Plugins → Topology Views → Topology** steht die ursprüngliche, ## Uninstall
filterbare Topologieansicht zur Verfügung. Sie unterstützt unter anderem:
- physische Kabel 1. Remove `"netbox_topology_views"` from `PLUGINS` and `PLUGINS_CONFIG`.
- logische Verbindungen 2. Remove the line from `/opt/netbox/local_requirements.txt`.
- Nachbargeräte 3. Uninstall the package and restart NetBox:
- Circuit-Terminations
- Power Feeds
- Wireless Links
- Coordinate Groups
- PNG- und XML-Export
### Rack-Ansicht ```bash
/opt/netbox/venv/bin/pip uninstall netbox-topology-views
sudo systemctl restart netbox netbox-rq
```
Die erweiterte Ansicht befindet sich unter: ## Usage
**Plugins → Topology Views → Weitere Ansichten → Rack-Ansicht** ### Classic topology
Über Site, Location und Rack können ein einzelnes Rack oder mehrere Racks **Plugins → Topology Views → Topology** provides the original, filterable
ausgewählt werden. Optional lassen sich auch leere Racks einblenden. topology view. It supports physical cables, logical connections, neighbour
devices, circuit terminations, power feeds, wireless links, coordinate groups,
and PNG and XML export.
In der Elevation werden Geräte entsprechend ihrer Position, Gerätehöhe und ### Rack view
Rack-Seite dargestellt. Unter den Elevations folgen:
1. die interaktive Kabeltopologie und **Plugins → Topology Views → More views → Rack view**
2. eine tabellarische Übersicht sämtlicher betroffener Kabel.
In der Kabeltopologie können Geräte per Drag-and-drop verschoben werden. Beim Select a single rack or several racks via site, location and rack; empty racks
Hover über ein Gerät werden dessen Kabel hervorgehoben und alle verbundenen can be shown optionally. Devices are rendered according to position, height and
Ports aufgelistet. Beim Hover über ein Kabel erscheinen beide Terminierungen. rack face. Below the elevations follow:
Ein Klick öffnet das jeweilige NetBox-Objekt.
Über die Export-Schaltflächen können ein einzelnes Rack, alle aktuell 1. the interactive cable topology, and
angezeigten Racks oder die interaktive Kabeltopologie als SVG, PNG oder 2. a table of all involved cables.
draw.io-Datei gespeichert werden. Sämtliche Exportformate werden ohne
Hintergrundfläche erzeugt. Im draw.io-Export bleiben Rack-Rahmen, Geräte und
Beschriftungen als einzelne Elemente bearbeitbar. Topologiekabel werden als
echte Kanten exportiert und folgen den Geräten beim Verschieben in draw.io.
Die Positionen werden im `localStorage` des Browsers gespeichert. Sie gelten In the cable topology, devices can be moved via drag and drop. Hovering a device
damit nur für den jeweiligen Browser und die konkrete Rack-/Filterauswahl. highlights its cables and lists all connected ports; hovering a cable shows both
terminations. A click opens the NetBox object.
## Geräte-Icons The export buttons save a single rack, all displayed racks or the cable topology
as SVG, PNG or draw.io, always without background. In the draw.io export, rack
frames, devices and labels remain individually editable, and topology cables are
real edges that follow the devices.
Das Plugin ordnet Icons anhand des Slugs einer Device Role zu. Dieser Fork Positions are stored in the browser's `localStorage` and apply only to that
liefert zusätzlich folgende SVG-Dateien aus: browser and the specific rack/filter selection.
| Device-Role-Slug | Icon-Datei | With [Netbox-Utilities](https://git.mrblake.cc/MrBlake/Netbox-Utilities)
installed, partial-width devices are rendered side by side in the rack view.
## Device icons
Icons are assigned by device role slug. This fork additionally ships:
| Device role slug | Icon file |
| --- | --- | | --- | --- |
| `network-switch` | `network-switch.svg` | | `network-switch` | `network-switch.svg` |
| `leaf-switch` | `leaf-switch.svg` | | `leaf-switch` | `leaf-switch.svg` |
| `spine-switch` | `spine-switch.svg` | | `spine-switch` | `spine-switch.svg` |
| `aggregation-switch` | `aggregation-switch.svg` | | `aggregation-switch` | `aggregation-switch.svg` |
Eigene Bilder können weiterhin über die Seite **Images** zugeordnet werden. Custom images can still be assigned on the **Images** page. The default path is
Der Standardpfad lautet `netbox_topology_views/img` innerhalb von `netbox_topology_views/img` within `STATIC_ROOT`.
`STATIC_ROOT`.
## Berechtigungen ## Permissions
Für die klassische Topologie werden mindestens folgende Rechte benötigt: Classic topology: `dcim.view_site`, `dcim.view_device`.
- `dcim.view_site` Rack view: `dcim.view_rack`, `dcim.view_device`, `dcim.view_cable`.
- `dcim.view_device`
Für die Rack-Ansicht werden benötigt: Saving classic topology coordinates additionally requires the corresponding
permissions on `netbox_topology_views.coordinate`.
- `dcim.view_rack` ## Origin and credits
- `dcim.view_device`
- `dcim.view_cable`
Für das Speichern klassischer Topologiekoordinaten werden zusätzlich die This project is a fork of the open-source plugin
entsprechenden Rechte auf `netbox_topology_views.coordinate` benötigt.
## Kompatibilität
Die Basis dieses Forks ist NetBox Topology Views `4.5.1`. Die neuen
Rack-Funktionen wurden für den Einsatz mit NetBox `4.6.5` angepasst und das
Plugin ist für NetBox `4.7.x` (`min_version`/`max_version` in
`netbox_topology_views/__init__.py`) freigegeben. Da das ursprüngliche
Release offiziell für NetBox 4.5.x ausgewiesen ist, sollten Updates auf
neuere NetBox-Versionen zunächst in einer Testumgebung geprüft werden.
## Ursprung und Danksagung
Dieses Projekt ist ein Fork des Open-Source-Plugins
[NetBox Topology Views](https://github.com/mattieserver/netbox-topology-views). [NetBox Topology Views](https://github.com/mattieserver/netbox-topology-views).
The original plugin was created by **Mattijs Vanhaverbeke**. Most of the classic
topology view, data models, filters and export functions are based on his work
and the contributions to the original project.
Das ursprüngliche Plugin wurde von **Mattijs Vanhaverbeke** erstellt. Der This fork is developed independently and is not officially affiliated with the
größte Teil der klassischen Topologieansicht, Datenmodelle, Filter und original author or the NetBox project.
Exportfunktionen basiert auf seiner Arbeit und den Beiträgen des ursprünglichen
Projekts.
Dieser Fork wird unabhängig weiterentwickelt und ist nicht mit dem ## License
ursprünglichen Autor oder dem NetBox-Projekt offiziell verbunden.
## Lizenz Like the original, this project is licensed under the
[Apache License 2.0](LICENSE). Existing copyright, license and attribution
Das Projekt steht wie das Original unter der notices of the original project are retained.
[Apache License 2.0](LICENSE). Bestehende Copyright-, Lizenz- und
Urheberhinweise des ursprünglichen Projekts bleiben erhalten.