Skip to content

Custom Map

LibreNMS has the ability to create custom maps to give a quick overview of parts of the network including up/down status of devices and link use. They are also called weather maps.

Viewer

Each new map is then visible to every user with have read access to all devices on a given map. Custom maps are available through the Overview -> Maps -> Custom Maps menu.

Some key points about the viewer are:

  • A node changes colour when it is down or disabled
  • Links are only associated with a single network interface
  • The link use appears only with a known link speed
  • Link speed is decoded from SNMP if possible (Upload/Download) and defaults to the physical speed if SNMP data is not available, or cannot be decoded
  • A link changes colour in this way:
  • Black if the link is down, or the max speed is unknown
  • Green at 0% use, with a gradual change to
  • Yellow at 50% use, with a gradual change to
  • Orange at 75% use, with a gradual change to
  • Red at 100% use, with a gradual change to
  • Purple at 150% use and above

Viewer URL options

You can manually add the following parameters to a URL to alter the display of a custom map.

The following URL options are available:

  • bare=yes : Removes the control bar from the top of the page.
  • screenshot=yes : Removes all labels from the nodes and links

For example, for bare and screenshot enabled, use https://nmsserver/maps/custom/2 becomes https://nmsserver/maps/custom/2?bare=yes&screenshot=yes

Editor

To access the custom map editor, a user must be an admin. The editor is accessed through the Overview -> Maps -> Custom Map Editor menu.

The editor gives a dropdown list of all the custom maps so you can choose one to edit, or select "Create New Map" to create a new map.

Map Settings

A new map opens a page for some global map settings. These are:

  • Name: The name for the map
  • Width: The width of the map in pixels
  • Height: The height of the map in pixels
  • Node Alignment: it aligns each new device on the map the devices to an invisible grid this many pixels wide, which can help to make the maps look better. This can be set to 0 to disable.
  • Background: An image (PNG/JPG) up to 2MB can be uploaded as a background.

These settings can be changed at any stage by clicking on the "Edit Map Settings" button in the top-left of the editor.

Nodes

Once you have a map, you can start by adding "nodes" to the map. A node represents a device, or an external point in the network, for example the internet To add a node, you click on the "Add Node" button in the control bar, then click the position of the node on the map. LibreNMS then asks for the following information:

  • Label: The text to display on this point in the network
  • Device: If this node represents a device, you can select the device from the dropdown. This action overwrites the label. You can change it if you want to.
  • Style: you can select the style of the node. With a selected device you can choose the LibreNMS icon by choosing "Device Image". You can also choose "Icon" to select an image for the device.
  • Icon: If you choose "Icon" in the style box, you can select from a list of images to represent this node

There are also options to choose the size and colour of the node and the font.

Once you have finished choosing the options for the node, you can press Save to add it to the map. NOTE: This does not save anything to the database immediately. You need to click on the "Save Map" button in the top-right to save your changes to the database.

You can edit a node at any time by selecting it on the map and clicking on the "Edit Node" button in the control bar.

You can also modify the default settings for all new nodes by clicking on the "Edit Node Default" button at the top of the page.

Edges

Once you have 2 or more nodes, you can add links between the nodes. These are called edges in the editor. To add a link, click on the "Add Edge" button in the control bar, then click on one of the nodes you want to link and drag the cursor to the second node of the link. LibreNMS then asks for the following information:

  • From: the start node of the link. The default is your first selected node
  • To: the end node of the link. The default is your second selected node
  • Port: If the From or To node is linked to a device, you can select an interface from one of the devices. The custom map then shows the traffic use of the selected interface.
  • Reverse Port Direction: If the selected port displays data in the wrong direction for the link, you can reverse it by toggling this option.
  • Line Style: You can try different line styles, especially if you are running multiple links between the same 2 nodes
  • Show percent usage: Choose whether to have text on the lines showing the link use as a percentage
  • Recenter Line: this box moves the centre point of the line back to half way between the 2 nodes when you click on the save button.

Once you have finished choosing the options for the node, you can press Save to add it to the map. NOTE: This does not save anything to the database immediately. You need to click on the "Save Map" button in the top-right to save your changes to the database.

The save button creates 3 objects on the screen: 2 arrows and a round node in the middle. With the 3 objects, you can move the mid point of the line off centre, and also allows us to display bandwidth information for both directions of the link.

You can edit an edge at any time by selecting it on the map and clicking on the "Edit Edge" button in the control bar.

You can also modify the default settings for all new edges by clicking on the "Edit Edge Default" button at the top of the page.

Re-Render

A drag of an item on the map bends some lines. This bend causes a "Re-Render Map" button to appear at the top-right of the page. This button can be clicked to draw all lines again in the format of the viewer.

Save Map

Once you are happy with a set of changes that you have made, you can click on the "Save Map" button in the top-right of the page to commit changes to the database. Each viewer of the map then sees the new version at the next page refreshes.

Adding Images

You can add your own images to use on the custom map by copying files into the html/images/custommap/icons/ directory. Any files with a .svg, .png or .jpg extension appears in the image selection dropdown of the custom map editor.

Default configuration

The default configuration for all new maps can be set with the following commands:

lnms config:set custom_map.background_type
lnms config:set custom_map.background_data.color "#badaee"
lnms config:set custom_map.background_data.lat 40
lnms config:set custom_map.background_data.layer
lnms config:set custom_map.background_data.lng "-20"
lnms config:set custom_map.background_data.zoom 3
lnms config:set custom_map.edge_font_color "#343434"
lnms config:set custom_map.edge_font_face arial
lnms config:set custom_map.edge_font_size 12
lnms config:set custom_map.edge_seperation 10
lnms config:set custom_map.height "800px"
lnms config:set custom_map.legend_colours '{ "0": "#0000ff", "10": "#00ff00" }'
lnms config:set custom_map.node_align 10
lnms config:set custom_map.node_background "#D2E5FF"
lnms config:set custom_map.node_border "#2B7CE9"
lnms config:set custom_map.node_font_color "#343434"
lnms config:set custom_map.node_font_face arial
lnms config:set custom_map.node_font_size 14
lnms config:set custom_map.node_size 25
lnms config:set custom_map.node_type
lnms config:set custom_map.reverse_arrows false
lnms config:set custom_map.width "1800px"

All options can be reset to default by excluding the value argument.

Options with special requirements are as follows: - Give each colour in hex form, not as a colour name - background_type, background_data.layer, and node_type accept only valid values. See resources/definitions/config_definition.json - custom_map.legend_colours is an array of a lower percentage and a colour. In the example above, the lines are green from 0% to 10%, then blue above 10% - The legend colours have the special value "-1". It applies to an offline interface and to an unknown port speed - There is a special value of "-2" in the legend colours for when the device an interface is connected to is offline - The default legend_colours config is null. The lines then change gradually from green to orange to red to purple, from 0% to 50% to 100% to 150%