diff --git a/README.md b/README.md index 8808a8a..b0c4b89 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,15 @@ ![Version](https://img.shields.io/pypi/v/netbox-topology-views) ![Downloads](https://img.shields.io/pypi/dm/netbox-topology-views) -Create topology views/maps from your devices in netbox. -The connections are based on the cables you created in netbox. +Create topology views/maps from your devices in NetBox. +The connections are based on the cables you created in NetBox. Support to filter on name, site, tag and device role. Options to export to xml (for draw.io/diagrams.net) or png. ## Preview -![preview image](doc/img/preview_3.1.jpeg?raw=true "preview") +![Topology with light mode](doc/img/topology_light.png) +![Topology with dark mode](doc/img/topology_dark.png) ## Install @@ -56,21 +57,24 @@ python3 manage.py collectstatic --no-input | >= 2.10.0 | >= v0.5.0 | | < 2.10.0 | =< v0.4.10 | -### Custom field: coordinates +### Update -There is also support for custom fields. +Run `pip install netbox-topology-views --upgrade` in your venv. -If you create a custom field "coordinates" for "dcim > device" and "Circuits > 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. +Run `python3 manage.py migrate netbox_topology_views` -The coordinates are stored as: "X;Y". +Run `python3 manage.py collectstatic --no-input` -Please read the "Configure" chapter to set the `allow_coordinates_saving` option to True. -You might also set the `always_save_coordinates` option to True. +Clear you browser cache. ## Configure +### Individual Options + All individual options can be assigned a default value per user directly in the plugin. The default value can be overridden on the filter page. +![Individual Options](doc/img/topology_individual_options.png) + The remaining options must be configured in the `PLUGINS_CONFIG` section of your `netbox/configuration.py`. Example: @@ -87,12 +91,40 @@ PLUGINS_CONFIG = { | Setting | Default value | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | 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` | -| allow_coordinates_saving | False | (bool) Set to true if you use the custom coordinates fields and want to save the coordinates | -| always_save_coordinates | False | (bool) Set if you want to enable the option to save coordinates by default | +| allow_coordinates_saving | False | (bool) Set to true if you want to enable the ability to save the coordinates. | +| 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. | + +### Custom field: coordinates + +There is also support for custom fields. + +>**_Note:_** The custom field "coordinates" is deprecated and will be removed in the future. Please use Coordinate Groups instead. + +If you create a custom field "coordinates" for "dcim > device" and "Circuits > 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. + +The coordinates are stored as: "X;Y". + +> Please read the "Configure" chapter to set the `allow_coordinates_saving` option to True. +You might also set the `always_save_coordinates` option to True. + +### Convert custom field to Coordinate Groups + +Please 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: ++ Navigate to "Topology" > "Filters". ++ Select "Show Unconnected" and "Show Cables". ++ Leave all other filter settings alone. We want all entries to be displayed! ++ Click "Search" and wait for the results to be displayed ++ 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. ++ Drag the selection a tiny bit to the side. This causes all coordinates for all devices to be stored in the "default" group. +> **_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._ ++ 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. ++ It is save to delete the custom field now. ### Custom Images -To 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. +To 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. + +![Images](doc/img/topology_images.png) ## Use @@ -100,9 +132,11 @@ Go to the plugins tab in the navbar and click topology or go to `$NETBOX_URL/plu Select your options for the topology view: -![topology_options](https://user-images.githubusercontent.com/20901110/235302073-234c3ef7-2c2b-4d0c-a674-9909d490d7ea.png) +![Filter Options](doc/img/topology_filter_options.png)
+
Coordinate Group
+
Select 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.
Save Coordinates
Save the coordinates of devices in the topology view.
Show Unconnected
@@ -125,17 +159,18 @@ Select your options for the topology view:
Displays wireless connections. These connections are displayed as blue dotted lines.
-### Update +### Coordinates and Coordinate Groups -Run `pip install netbox-topology-views --upgrade` in your venv. +Netbox Topology Views stores the position of the devices. In order to allow different representations for the topology, Coordinate Groups are supported. -Run `python3 manage.py migrate netbox_topology_views` +> Please read the "Configure" chapter to set the `allow_coordinates_saving` option to True. +You might also set the `always_save_coordinates` option to True. -Run `python3 manage.py collectstatic --no-input` +Navigate 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. +By 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". -Clear you browser cache. - +> **_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. ### Permissions @@ -145,11 +180,20 @@ To view `/plugins/netbox_topology-views/topology` you need the following permiss + extras | tag | can view tag + dcim | device role | can view device role -To view `/plugins/netbox_topology-views/image`: +To save `Coordinates` when moving icons: + + netbox_topology_views | coordinate | change + +To view `/plugins/netbox_topology-views/images`: + dcim | site | view + dcim | device role | view + dcim | device role | add + dcim | device role | change - To view `/plugins/netbox_topology-views/individualoptions`: - + netbox topology views | individualoptions | change +To view `/plugins/netbox_topology-views/individualoptions`: + + netbox_topology_views | individual options | change + +Set `Coordinate Groups` according to your needs: + + netbox_topology_views | coordinate groups | view/add/change/delete + +Set `Coordinates` according to your needs: + + netbox_topology_views | coordinate | view/add/change/delete diff --git a/doc/img/preview.png b/doc/img/preview.png deleted file mode 100644 index 83a411c..0000000 Binary files a/doc/img/preview.png and /dev/null differ diff --git a/doc/img/preview_3.1.jpeg b/doc/img/preview_3.1.jpeg deleted file mode 100644 index d102cc6..0000000 Binary files a/doc/img/preview_3.1.jpeg and /dev/null differ diff --git a/doc/img/selection_options.png b/doc/img/selection_options.png deleted file mode 100644 index dac7dd6..0000000 Binary files a/doc/img/selection_options.png and /dev/null differ diff --git a/doc/img/topology_dark.png b/doc/img/topology_dark.png new file mode 100644 index 0000000..d7eb761 Binary files /dev/null and b/doc/img/topology_dark.png differ diff --git a/doc/img/topology_filter_options.png b/doc/img/topology_filter_options.png new file mode 100644 index 0000000..ad2b1f7 Binary files /dev/null and b/doc/img/topology_filter_options.png differ diff --git a/doc/img/topology_images.png b/doc/img/topology_images.png new file mode 100644 index 0000000..a6f2d03 Binary files /dev/null and b/doc/img/topology_images.png differ diff --git a/doc/img/topology_individual_options.png b/doc/img/topology_individual_options.png new file mode 100644 index 0000000..1f1e09a Binary files /dev/null and b/doc/img/topology_individual_options.png differ diff --git a/doc/img/topology_light.png b/doc/img/topology_light.png new file mode 100644 index 0000000..b2f1155 Binary files /dev/null and b/doc/img/topology_light.png differ