{"id":13585985,"url":"https://github.com/netbox-community/netbox-topology-views","last_synced_at":"2025-12-14T13:40:20.883Z","repository":{"id":39333039,"uuid":"252408164","full_name":"netbox-community/netbox-topology-views","owner":"netbox-community","description":"A netbox plugin that draws topology views ","archived":false,"fork":false,"pushed_at":"2025-05-05T10:59:03.000Z","size":3327,"stargazers_count":863,"open_issues_count":31,"forks_count":78,"subscribers_count":41,"default_branch":"develop","last_synced_at":"2025-05-08T01:07:16.747Z","etag":null,"topics":["netbox","netbox-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netbox-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-02T09:14:29.000Z","updated_at":"2025-05-06T13:41:44.000Z","dependencies_parsed_at":"2024-01-13T22:22:16.966Z","dependency_job_id":"62c25e74-12ef-44b1-8849-c4c5fa571c2f","html_url":"https://github.com/netbox-community/netbox-topology-views","commit_stats":{"total_commits":133,"total_committers":18,"mean_commits":7.388888888888889,"dds":0.6240601503759399,"last_synced_commit":"c4ee38c0c9bc8aa92a31cba9d3f39be7f611b570"},"previous_names":["netbox-community/netbox-topology-views","mattieserver/netbox-topology-views"],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbox-community%2Fnetbox-topology-views","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbox-community%2Fnetbox-topology-views/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbox-community%2Fnetbox-topology-views/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbox-community%2Fnetbox-topology-views/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netbox-community","download_url":"https://codeload.github.com/netbox-community/netbox-topology-views/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140739,"owners_count":22021218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["netbox","netbox-plugin"],"created_at":"2024-08-01T15:05:15.450Z","updated_at":"2025-12-14T13:40:20.804Z","avatar_url":"https://github.com/netbox-community.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Netbox Topology Views Plugin\n\n![Version](https://img.shields.io/pypi/v/netbox-topology-views) ![Downloads](https://img.shields.io/pypi/dm/netbox-topology-views)\n\nCreate topology views/maps from your devices in NetBox.\nThe connections are based on the cables you created in NetBox.\nSupport to filter on name, site, tag and device role.  \nOptions to export to xml (for draw.io/diagrams.net) or png.\n\n## Preview\n\n![Topology with light mode](doc/img/topology_light.png)\n![Topology with dark mode](doc/img/topology_dark.png)\n\n## Install\n\n**_NOTE:_** For docker please see: [Docker install](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins)\n\n**_NOTE:_** Add `RUN mkdir -p /opt/netbox/netbox/static/netbox_topology_views/img` to the Dockerfile-Plugins file to create the image folder\n\nThe plugin is available as a Python package and can be installed with pip.\n\nRun `pip install netbox-topology-views` in your virtual env.\n\nTo ensure NetBox Topology Views plugin is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the NetBox root directory (alongside `requirements.txt`) and list the `netbox-topology-views` package:\n\n```no-highlight\n# echo netbox-topology-views \u003e\u003e local_requirements.txt\n```\n\nOnce installed, the plugin needs to be enabled in your `configuration.py`\n\n```python\n# In your configuration.py\nPLUGINS = [\"netbox_topology_views\"]\n```\n\nFirst run `source /opt/netbox/venv/bin/activate` to enter the Python virtual environment.\n\n\nThen run \n```bash\ncd /opt/netbox/netbox\npip3 install netbox-topology-views\npython3 manage.py migrate netbox_topology_views\npython3 manage.py collectstatic --no-input\n```\n\n### Versions\n\n\u003e [!NOTE]  \n\u003e If the version of netbox is not listed here the plugin will most likely not work. Remove the plugin if you want to update netbox before this plugin has released an update for that netbox version.\n\n| netbox version | netbox-topology-views version |\n| -------------- | ----------------------------- |\n| = 4.2.0        | = v4.2.0                      |\n| = 4.1.X        | = v4.1.0                      |\n| = 4.0.X        | = v4.0.0                      |\n| = 3.7.0        | = v3.9.0                      |\n| = 3.6.4        | = v3.8.1                      |\n| = 3.6.0        | = v3.7.0                      |\n| = 3.5.0        | = v3.6.2                      |\n\n\n### Update\n\nRun `pip install netbox-topology-views --upgrade` in your venv.\n\nRun `python3 manage.py migrate netbox_topology_views`\n\nRun `python3 manage.py collectstatic --no-input`\n\nClear you browser cache.\n\n## Configure\n\n### Individual Options\n\nAll individual options can be assigned a default value per user directly in the plugin. The default value can be overridden on the filter page.\n\n![Individual Options](doc/img/topology_individual_options.png)\n\nThe remaining options must be configured in the `PLUGINS_CONFIG` section of your `netbox/configuration.py`.\n\nExample:\n```\nPLUGINS_CONFIG = {\n    'netbox_topology_views': {\n        'static_image_directory': 'netbox_topology_views/img',\n        'allow_coordinates_saving': True,\n        'always_save_coordinates': True\n    }\n}\n```\n\n| Setting                  | Default value                                                                                                                                  | Description                                                                                                            |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| static_image_directory   | netbox_topology_views/img                                                                                                                      | (str or pathlib.Path) Specifies the location that images will be loaded from by default. Must be within `STATIC_ROOT`  |\n| allow_coordinates_saving | False                                                                                                                                          | (bool) Set to true if you want to enable the ability to save the coordinates.                           |\n| always_save_coordinates  | False                                                                                                                                          | (bool) Set if you want to enable the option to save coordinates by default. Setting allow_coordinates_saving to true is mandatory.                                             |\n\n### Custom field: coordinates\n\nThere is also support for custom fields.\n\n\u003e**_Note:_** The custom field \"coordinates\" is deprecated and will be removed in the future. Please use Coordinate Groups instead.\n\nIf you create a custom field \"coordinates\" for \"dcim \u003e device\" and \"Circuits \u003e circuit\" with type \"text\" and name \"coordinates\" you will see the same layout every time. It is recommended to set this field to \"UI visibility\" \"Hidden\" and let the plugin manage it in the background.\n\nThe coordinates are stored as: \"X;Y\".\n\n\u003e Please read the \"Configure\" chapter to set the `allow_coordinates_saving` option to True.\nYou might also set the `always_save_coordinates` option to True.\n\n### Convert custom field to Coordinate Groups\n\nPlease note that values stored in the custom field \"coordinates\" are not being converted to Coordinate Groups automatically. A pragmatic way to do this conversion yourself is as follows:\n+ Navigate to \"Topology\" \u003e \"Filters\".\n+ Select \"Show Unconnected\" and \"Show Cables\". \n+ Leave all other filter settings alone. We want all entries to be displayed!\n+ Click \"Search\" and wait for the results to be displayed\n+ Select all nodes. This can be done by holding down the Shift key and dragging a frame around all icons with the left mouse button.\n+ Drag the selection a tiny bit to the side. This causes all coordinates for all devices to be stored in the \"default\" group.\n\u003e **_Hint_**: Don't wait too long after clicking an icon in order to drag. If you hold the mouse button for too long before dragging starts, the selection is reset._\n+ Storing the values might take some time, depending on the number of devices. Please be patient and check \"Coordinates\" in order to make sure that everthing has been stored.\n+ It is save to delete the custom field now.\n\n### Custom Images\n\nTo change image with associated device use the `Images` page - it allows to map a device role with an image found in the NetBox static directory (defined by the plugin config `static_image_directory` which defaults to `netbox_topology_views/img`). You can also upload you own custom images to there - these images will automatically be used for a device (if it does not already have a specified image in the settings) if their name is the device role slug.\n\n![Images](doc/img/topology_images.png)\n\n## Use\n\nGo to the plugins tab in the navbar and click topology or go to `$NETBOX_URL/plugins/netbox_topology_views/` to view your topologies\n\nSelect your options for the topology view:\n\n![Filter Options](doc/img/topology_filter_options.png)\n\n\u003cdl\u003e\n    \u003cdt\u003eCoordinate Group\u003c/dt\u003e\n    \u003cdd\u003eSelect Coordinate Group. These groups allow devices to be displayed in different positions depending on the group, thus providing different representations for the same topology. If nothing is selected, the group \"default\" is set automatically.\u003c/dd\u003e\n    \u003cdt\u003eSave Coordinates\u003c/dt\u003e\n    \u003cdd\u003eSave the coordinates of devices in the topology view.\u003c/dd\u003e\n    \u003cdt\u003eShow Unconnected\u003c/dt\u003e\n    \u003cdd\u003eShow devices that have no connections or for which no connection is displayed. This option depends on other parameters like 'Show Cables' and 'Show Logical Connections'.\u003c/dd\u003e\n    \u003cdt\u003eShow Cables\u003c/dt\u003e\n    \u003cdd\u003eShow connections between interfaces, front / rear ports, etc., that are connected with one or more cables. These connections are displayed as solid lines in the color of the cable.\u003c/dd\u003e \n    \u003cdt\u003eShow Logical Connections\u003c/dt\u003e\n    \u003cdd\u003eShow logical connections between interfaces (referred to as Interface Connections in NetBox) in the topology view. Where the path between\n        interfaces includes multiple cables (e.g., via patch panels), only the end interface connections are shown, not the \n        intermediate front / rear port connections, etc. This is similar to what was referred to as 'end-to-end' connections in previous versions. These connections are displayed as yellow dotted lines.\u003c/dd\u003e\n    \u003cdt\u003eShow redundant Cable and Logical Connection\u003c/dt\u003e\n    \u003cdd\u003eShows a logical connection (in addition to a cable), even if a cable is directly connected. Leaving this option disabled prevents that redundant display. This option only has an effect if 'Show Logical Connections' is activated.\u003c/dd\u003e\n    \u003cdt\u003eShow Neighbors\u003c/dt\u003e\n    \u003cdd\u003eAdds neighbors to the filter result set automatically. Link peers will be added if 'Show Cables' is ticked, far-end terminations will be added if 'Show Logical Connections' is ticked.\u003c/dd\u003e\n    \u003cdt\u003eShow Circuit Terminations\u003c/dt\u003e\n    \u003cdd\u003eShow connections which end at a circuit termination in the topology view. These connections are displayed as blue dashed lines.\u003c/dd\u003e\n    \u003cdt\u003eShow Power Feeds\u003c/dt\u003e\n    \u003cdd\u003eDisplays connections between power outlets and power ports. These connections are displayed as solid lines in the color of the cable. This option depends on 'Show Cables'.\u003c/dd\u003e\n    \u003cdt\u003eShow Wireless Links\u003c/dt\u003e\n    \u003cdd\u003eDisplays wireless connections. These connections are displayed as blue dotted lines.\u003c/dd\u003e\n\u003c/dl\u003e\n    \n### Coordinates and Coordinate Groups\n\nNetbox Topology Views stores the position of the devices. In order to allow different representations for the topology, Coordinate Groups are supported.\n\n\u003e Please read the \"Configure\" chapter to set the `allow_coordinates_saving` option to True.\nYou might also set the `always_save_coordinates` option to True.\n\nNavigate to \"Coordinate Groups\" in the menu and create as many groups as you like. You can select a group later in the filter pane in order to show icon positions according to this group (see chapter \"Use\"). You can also omit creating a group if you don't need this feature. Netbox Topology Views automatically creates a group named \"default\" for you and stores all coordinates in this group, even if you do not select a group in the filter.\n\nBy default, the position of the devices are calculated with a physics engine. As soon as a device icon is dragged to another location, its position is saved and excluded from the calculation by the physics engine. All saved coordinates can be viewed and edited under the menu item \"Coordinates\".\n\n\u003e **_Note:_** At the time of writing, it is not possible to store the positions of circuit terminations, power panels and power feeds, as these are not devices.\n\n### Permissions\n\nTo view `/plugins/netbox_topology-views/topology` you need the following permissions:\n + dcim | device | can view device\n + dcim | site | can view site\n + extras | tag | can view tag\n + dcim | device role | can view device role\n\nTo save `Coordinates` when moving icons:\n + netbox_topology_views | coordinate | change\n\nTo view `/plugins/netbox_topology-views/images`:\n + dcim | site | view\n + dcim | device role | view\n + dcim | device role | add\n + dcim | device role | change\n\nTo view `/plugins/netbox_topology-views/individualoptions`:\n + netbox_topology_views | individual options | change\n\nSet `Coordinate Groups` according to your needs:\n + netbox_topology_views | coordinate groups | view/add/change/delete\n\nSet `Coordinates` according to your needs:\n + netbox_topology_views | coordinate | view/add/change/delete\n\nSet `Power Feed Coordinates` according to your needs:\n + netbox_topology_views | power feed coordinate | view/add/change/delete\n\nSet `Power Panel Coordinates` according to your needs:\n + netbox_topology_views | power panel coordinate | view/add/change/delete\n\nSet `Circuit Coordinates` according to your needs:\n + netbox_topology_views | circuit coordinate | view/add/change/delete\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetbox-community%2Fnetbox-topology-views","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetbox-community%2Fnetbox-topology-views","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetbox-community%2Fnetbox-topology-views/lists"}