Network Map - netdisco/netdisco GitHub Wiki

Introduction
Basic Operation
Making Great Network Maps
Moving and Pinning Devices
Choosing which Devices to Show
- Configuring Host Groups and Display Names
Other Options
- Color Groups
- Dynamic Size
Alternatives
Tips and Tricks
Limitations of Network Mapping
Troubleshooting

Introduction

This is a user guide for Netdisco’s network map, also known as the device neighbor report. This page will help you produce useful and attractive pictures of your network while understanding the limitations of network topology mapping.

For example:

Feedback is always welcome in the #netdisco@libera IRC channel, or on our community email list.

Basic Operation

Click and drag the map to move around (known as panning)
Scroll up and down with your mouse to zoom in and out
Hover over a link or a device to see more information
Double click a device to load its details/ports/map/interfaces

There is an icon in the top-right corner of the map to make it fullscreen.

Making Great Network Maps

Define named groups of devices in your deployment.yml file using the host_groups and host_group_displaynames settings (examples are below).
Load the map, select your Host Groups in the sidebar list, and choose Color By "Host Group".
Click "Redraw Map".
Drag devices or groups of devices around to get the layout you want.
Positions are saved automatically after a few seconds, or click the Save button.

Bookmark the link in your browser to return to this map any time. If new devices are added then they will be put in a sensible place. The map can be made fullscreen by clicking the icon in the top right corner.

Moving and Pinning Devices

A few seconds after the map has loaded and settled down, all devices are pinned in place. You can click one and drag it around with your mouse. To move multiple devices, hold down the Shift key and click to draw a circle (lasso) around a set of devices. You can then move the group by clicking one of the devices and dragging it. Firefox is a little buggy.

Buttons in the sidebar allow you to "release" devices (unlock icon), which triggers the map to try to redraw and find the best location for nodes and links. You can do this for devices selected with a lasso, or for all devices at once.

When viewing all devices, or specific groups of devices, you can move nodes around and then save positions to Netdisco’s database (click "Save"). The layout will be restored if you revisit the page another time.

Choosing which Devices to Show

When the map first loads it will display only the parent device (for this set of details/ports/interfaces tabs) and its immediate neighbors.

You can choose to view all devices (change the radio button in the sidebar) and then click "Redraw Map". Similarly, you can view specific groups of devices if they are configured, by selecting Host Groups or Locations.

The "Neighbor Cloud" option shows all devices which are reachable from the current parent device, that is, the local cloud of connected devices. The "Neighbor Hops" option allows more dynamic selection of how far from the parent device the map will reach. You can restrict the devices shown using a VLAN ID number.

If you have more than 1000 devices, some options are hidden for efficiency.

Configuring Host Groups and Display Names

Displaying specific groups of devices is only available if you have configured the host_groups and host_group_displaynames settings in your deployment.yml file.

First set up your groups of devices using standard Access Control List syntax in the host_groups setting. For example:

host_groups:
  backbone_routers: '192.0.2.0/28'
  cpe_devices:
    - 'dns:.+\.customer\.example\.com'
    - '2001:db8::/64'

Then assign each of the groups a friendly alias name:

host_group_displaynames:
  backbone_routers: 'Backbone Routers'
  cpe_devices: 'Customer Premises'

The Netdisco web server will restart automatically when you save changes to the deployment.yml file.

Once this is done, the network map will offer group names to be used to filter the devices shown (if "Host Groups" is selected) and/or colour the devices (if the "Color Groups" option is also selected).

Only groups given an alias name will be available in the network map interface (so you can still use host_groups for other access control list settings as well).

Other Options

Color Groups

Any devices matching selected groups will be assigned colors (from the d3 categorical color sets).

By default, Netdisco will try to color devices by their total port throughput. If you then select any Locations or Host Groups in the sidebar, you can choose to color according to those names instead, and a legend will appear.

If a device matches more than one of your named host groups, the first match in the list of defined and named host groups will be used.

Dynamic Size

Enable this option to size the device blobs according to their total available throughput bandwidth. Netdisco takes into account the bandwidth of all device ports (regardless of up/down state). This is a somewhat approximate calculation and there can be only about six node sizes in the map anyway; however it can be very handy when displaying large networks.

Alternatives

Netdisco also provides a secondary option to create network maps based on graphviz, this is currently commandline only. Documentation can be found in the netdisco-do manual and the master config file , but needs improvement.

Tips and Tricks

Displaying management IPs and Link Speeds is immediate and does not require redraw of the map.
Link Speed is the total of all links between the two devices (that is, it works for aggregates as well).
The Host Group and Location lists can be used to restrict which devices are shown, as well as being used to color devices.
Layouts are always automatically saved to the database a few seconds after the last change is made, to make rendering faster on redraw.
A small icon in the bottom-right of the network map shows whether Netdisco is still calculating the map layout (yellow arc) or has completed (green circle).

Limitations of Network Mapping

A network topology map has some limitations:

it does not show the actual path that packets or traffic will take in your network
it only shows the neighbor relations reported by devices to Netdisco or configured manually by yourself.

In particular, it is a layer1/layer2 map, so does not take into account routing protocols that might steer packets down alternate paths in the network.

Troubleshooting

Sometimes devices are not shown, or links are not shown. Here are some reasons why:

Netdisco needs to know neighbor relations between devices, from protocols such as CDP or LLDP, or from manually linking interfaces via port control / manual device topology.
Ports are in undiscovered VRFs.

If you have trouble, open a ticket at GitHub.