diff --git a/README.md b/README.md index 8706cec..5fbb502 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,95 @@ # MRB NetBox Topology Views -Ein angepasster Fork von **NetBox Topology Views** mit erweiterten Rack-Ansichten, -interaktiver Kabelverfolgung und zusätzlichen Netzwerk-Icons. +A customised fork of **NetBox Topology Views** with extended rack views, +interactive cable tracing and additional network icons. -Das Plugin erzeugt Topologien aus den in NetBox gepflegten Geräten, Ports und -Kabeln. Neben der klassischen Topologie bietet dieser Fork eine vollständige -Darstellung einzelner oder mehrerer Racks einschließlich Vorderseite, -Rückseite und Verkabelung. +The plugin builds topologies from the devices, ports and cables maintained in +NetBox. In addition to the classic topology, this fork provides a complete view +of one or more racks including front, rear and cabling. -## Vorteile dieses Forks +| | | +|---|---| +| **Plugin name** | `netbox_topology_views` | +| **Package** | `netbox-topology-views` | +| **NetBox** | `4.7.x` | +| **Python** | see `setup.py` | +| **Repository** | | -- Ein oder mehrere Racks gemeinsam anzeigen -- 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 +## Features -## Ä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**. -2. Eine Rack-Ansicht mit Filtern für Site, Location und mehrere Racks. -3. Positionsgenaue Rack-Elevations für Vorder- und Rückseite. -4. Eine Kabeltabelle mit A- und B-Terminierungen. -5. Eine interaktive, verschiebbare Kabeltopologie unter den Racks. -6. Hover-Hervorhebung und Port-zu-Port-Verfolgung für Geräte und Kabel. -7. Lokal gespeicherte Gerätepositionen und eine Funktion zum Zurücksetzen. -8. Ein erweitertes, skalierbares SVG-Iconset für Switch-Rollen. -9. Transparente SVG-, PNG- und draw.io-Exporte für Rack- und Topologieansichten. -10. Anpassungen für die Verwendung mit NetBox 4.6, darunter die geänderte - `Rack.units`-Property. - -## Vorschau - -Die klassische Topologieansicht stammt aus dem ursprünglichen Plugin: +1. New menu category **More views**. +2. A rack view with filters for site, location and multiple racks. +3. Position-accurate rack elevations for front and rear. +4. A cable table with A and B terminations. +5. An interactive, movable cable topology below the racks. +6. Hover highlighting and port-to-port tracing for devices and cables. +7. Locally stored device positions and a reset function. +8. An extended, scalable SVG icon set for switch roles. +9. Transparent SVG, PNG and draw.io exports for rack and topology views. +10. Adjustments for NetBox 4.6+, including the changed `Rack.units` property. ![Topology in light mode](doc/img/topology_light.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 /opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" ``` -Für eine reproduzierbare Produktivinstallation sollte statt `develop` ein -Release-Tag oder ein bestimmter Commit verwendet werden: +For reproducible production installs, replace `develop` with a release tag or a +full commit ID. + +### 2. Add the plugin to `local_requirements.txt` + +This makes `upgrade.sh` reinstall the plugin automatically on every NetBox upgrade: ```bash -/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ - "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@v4.5.1-mrb.1" +grep -qxF "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" /opt/netbox/local_requirements.txt \ + || 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 -Eintrag in `/opt/netbox/local_requirements.txt` hinterlegt: +If the repository is private, the NetBox server needs a read-only deploy token +or an SSH key. Do not store credentials in `local_requirements.txt`. -```text -git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop -``` +### 3. Enable the plugin -Bei einem privaten Gitea-Repository muss der NetBox-Server Zugriff über einen -Deploy-Token oder SSH-Key erhalten. - -## NetBox-Konfiguration - -In `netbox/configuration.py` wird das Python-Paket aktiviert: +In `/opt/netbox/netbox/netbox/configuration.py`: ```python 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 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 sudo systemctl restart netbox netbox-rq ``` -Nach Änderungen an CSS oder Icons kann ein Hard-Reload des Browsers mit -`Strg+F5` erforderlich sein. +After changes to CSS or icons a hard reload in the browser (`Ctrl+F5`) may be +necessary. -## Aktualisierung +## Update ```bash /opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" 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 sudo systemctl restart netbox netbox-rq ``` -`--force-reinstall` ist derzeit sinnvoll, da der Fork intern noch die -Paketversion `4.5.2` verwendet. +`--force-reinstall` is required because the fork still uses the internal +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, -filterbare Topologieansicht zur Verfügung. Sie unterstützt unter anderem: +## Uninstall -- physische Kabel -- logische Verbindungen -- Nachbargeräte -- Circuit-Terminations -- Power Feeds -- Wireless Links -- Coordinate Groups -- PNG- und XML-Export +1. Remove `"netbox_topology_views"` from `PLUGINS` and `PLUGINS_CONFIG`. +2. Remove the line from `/opt/netbox/local_requirements.txt`. +3. Uninstall the package and restart NetBox: -### 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 -ausgewählt werden. Optional lassen sich auch leere Racks einblenden. +**Plugins → Topology Views → Topology** provides the original, filterable +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-Seite dargestellt. Unter den Elevations folgen: +### Rack view -1. die interaktive Kabeltopologie und -2. eine tabellarische Übersicht sämtlicher betroffener Kabel. +**Plugins → Topology Views → More views → Rack view** -In der Kabeltopologie können Geräte per Drag-and-drop verschoben werden. Beim -Hover über ein Gerät werden dessen Kabel hervorgehoben und alle verbundenen -Ports aufgelistet. Beim Hover über ein Kabel erscheinen beide Terminierungen. -Ein Klick öffnet das jeweilige NetBox-Objekt. +Select a single rack or several racks via site, location and rack; empty racks +can be shown optionally. Devices are rendered according to position, height and +rack face. Below the elevations follow: -Über die Export-Schaltflächen können ein einzelnes Rack, alle aktuell -angezeigten Racks oder die interaktive Kabeltopologie als SVG, PNG oder -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. +1. the interactive cable topology, and +2. a table of all involved cables. -Die Positionen werden im `localStorage` des Browsers gespeichert. Sie gelten -damit nur für den jeweiligen Browser und die konkrete Rack-/Filterauswahl. +In the cable topology, devices can be moved via drag and drop. Hovering a device +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 -liefert zusätzlich folgende SVG-Dateien aus: +Positions are stored in the browser's `localStorage` and apply only to that +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` | | `leaf-switch` | `leaf-switch.svg` | | `spine-switch` | `spine-switch.svg` | | `aggregation-switch` | `aggregation-switch.svg` | -Eigene Bilder können weiterhin über die Seite **Images** zugeordnet werden. -Der Standardpfad lautet `netbox_topology_views/img` innerhalb von -`STATIC_ROOT`. +Custom images can still be assigned on the **Images** page. The default path is +`netbox_topology_views/img` within `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` -- `dcim.view_device` +Rack view: `dcim.view_rack`, `dcim.view_device`, `dcim.view_cable`. -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` -- `dcim.view_device` -- `dcim.view_cable` +## Origin and credits -Für das Speichern klassischer Topologiekoordinaten werden zusätzlich die -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 +This project is a fork of the open-source plugin [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 -größte Teil der klassischen Topologieansicht, Datenmodelle, Filter und -Exportfunktionen basiert auf seiner Arbeit und den Beiträgen des ursprünglichen -Projekts. +This fork is developed independently and is not officially affiliated with the +original author or the NetBox project. -Dieser Fork wird unabhängig weiterentwickelt und ist nicht mit dem -ursprünglichen Autor oder dem NetBox-Projekt offiziell verbunden. +## License -## Lizenz - -Das Projekt steht wie das Original unter der -[Apache License 2.0](LICENSE). Bestehende Copyright-, Lizenz- und -Urheberhinweise des ursprünglichen Projekts bleiben erhalten. +Like the original, this project is licensed under the +[Apache License 2.0](LICENSE). Existing copyright, license and attribution +notices of the original project are retained.