Topology Map

This section describes how to configure the topology map.

Properties

The topology map supports the following properties, which can be influenced by changing the file etc/org.opennms.features.topology.app.cfg:

Property Description Type Default

showHeader

Defines if the Horizon header is shown.

Boolean

true

autoRefresh.enabled

If enabled, auto refresh is enabled by default.

Boolean

false

autoRefresh.interval

Defines the auto refresh interval in seconds.

Integer

60

hiddenCategoryPrefix

A string that enables hiding categories. For example a value of server will hide all categories starting with server. Be aware, that this setting is case sensitive, so Servers will not be shown. The resolution is enabled only if no longitude/latitude information is available.

String

empty String

Edge Status

The choice of topology provider controls the status and color of an edge, or link between two vertices. Each topology provider has different notions of what an edge represents and may provide different controls for managing the behavior.

Linkd Topology Provider

The Linkd Topology Provider uses the state and existence of alarms to determine the color of the edge. An edge between two vertices on a topology map represents a link that has been discovered between two interfaces on distinct nodes. If an alarm is present with a UEI uei.opennms.org/internal/topology/linkDown, and the alarm is associated with either of the interfaces on either node, then the edge is red. If no such alarm is present, the edge is green.

These alarms are not generated by default. Enable them by changing the logmsg property on the uei.opennms.org/internal/topology/linkDown and uei.opennms.org/internal/topology/linkUp events from donotpersist to logndisplay. These events are automatically generated by the default set of event translator rules that process incoming SNMP Link Up & Down traps.

Icons

Each Vertex on the topology map is represented by an icon. The default icon is configured in the icon mapping file: ${OPENNMS_HOME}/etc/org.opennms.features.topology.app.icons.<topology-namespace>.cfg. If an icon mapping file does not exist for a topology provider, the provider does not support customization.

List of available icon mapping files (may not be complete)
org.opennms.features.topology.app.icons.default.cfg (1)
org.opennms.features.topology.app.icons.application.cfg (2)
org.opennms.features.topology.app.icons.bsm.cfg (3)
org.opennms.features.topology.app.icons.linkd.cfg (4)
org.opennms.features.topology.app.icons.vmware.cfg (5)
1 Default icon mapping
2 Icon mapping for the Application Topology Provider
3 Icon mapping for the Business Services Topology Provider
4 Icon mapping for the Linkd Topology Provider
5 Icon mapping for the Vmware Topology Provider

Each file contains a mapping in the form of <icon key> = <icon id>.

Icon key

A topology-provider-dependent string that maps to an icon id. An icon key consists of one-to-multiple segments. Each segment must contain only numbers or characters. If multiple segments exist, they must be separated by .; for example, my.custom.key. Any existing default icon keys are not configurable and should not be changed.

Icon id

The icon id is a unique icon identifier to reference an icon within one of the available SVG icons located in ${OPENNMS_HOME}/jetty-webapps/opennms/svg. For more details, see Add new icons.

Icon key and icon id specification using BNF
icon key ::= segment["."segment]*
segment ::= text+ [( "-" | "_" | ":" ) text]*
text ::== (char | number)+
char ::== A | B | ... | Z | a | b | ... | z
number ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
icon id ::= segment
Example icon mapping file
# Business Service Topology
bsm.business-service = business_service (1)
bsm.ip-service = IP_service (2)
bsm.reduction-key = reduction_key (3)
1 Icon definition for business services
2 Icon definition for IP services
3 Icon definition for reduction keys

Icon resolution

The icon of a vertex is resolved as follows:

  • If a vertex id to icon id mapping is defined, the icon referenced by the icon id is used.

  • If a mapping for the icon key determined by the Topology Provider for the vertex is defined, the icon referenced by the icon id is used.

    • If no mapping exists and the icon key has more than one segments, reduce the icon key by the last segment and try resolving that icon key.

  • If no mapping is defined, the fallback icon key default is used.

The following example icon mapping is defined for the Linkd Topology Provider to illustrate this behavior.

linkd.system.snmp.1.3.6.1.4.1.9.1.485 = server1
linkd.system.snmp.1.3.6 = server2

If the Enterprise OID of a node is 1.3.6.1.4.1.9.1.485 the icon with id server1 is used. If the Enterprise OID of a node is 1.3.6 the icon with id server2 is used. However, if the Enterprise OID of a node is 1.3.6.1.4.1.9.1.13 the icon with id server2 is used.

Linkd Topology Provider

The Linkd Topology Provider uses the Enterprise OID from each node to determine the icon of a vertex.

Change existing icon mappings

The easiest way to change an icon representation of an existing vertex is to use the Icon Selection Dialog from the vertex context menu in the topology map. This will create a custom icon key-to-icon id mapping in the topology-provider-specific icon mapping file. As icon key the vertex id is used. This lets each vertex have its own icon.

If you prefer a more generic approach, modify the icon mapping file manually.

Do not remove the default mappings and do not change the icon keys in the default mappings.

Add new icons

All available icons are stored in SVG files located in ${OPENNMS_HOME}/jetty-webapps/opennms/svg. To add new icons, either add definitions to an existing SVG file or create a new SVG file in that directory.

However you add new icons to OpenNMS it is important that each new icon id describes a set of icons, rather than a single icon. The following example illustrates this.

Example SVG file with a custom icon with id my-custom
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg id="icons" xmlns="http://www.w3.org/2000/svg">
  <g id="my-custom_icon"> (1)
      <g id="my-custom_active"> (2)
          <!-- rect, path, circle, etc elements, supported by SVG -->
      </g>
      <g id="my-custom_rollover"> (3)
          <!-- rect, path, circle, etc elements, supported by SVG -->
      </g>
      <g id="my-custom"> (4)
          <!-- rect, path, circle, etc elements, supported by SVG -->
      </g>
  </g>
  <!-- Additional groups ... -->
</svg>
1 Each icon must be in a SVG group with the id <icon id>_icon. Each SVG <icon id>_icon group must contain three subgroups with the ids: <icon id>_active, <icon id>_rollover, and <icon id>.
2 The icon to use when the vertex is selected.
3 The icon to use when the vertex is moused over.
4 The icon to use when the vertex is not selected or moused over (just visible).
It is important that each icon id is unique overall SVG files. This means there cannot be another my-custom icon id in any other SVG file.

If the new icons should be selectable from the topology map’s icon selection dialog, add an entry with the new icon id to the file ${OPENNMS_HOME}/etc/org.opennms.features.topology.app.icons.properties.

Snippet of org.opennms.features.topology.app.icons.list
access_gateway (1)
accesspoint
cloud
fileserver
linux_file_server
opennms_server
printer
router
workgroup_switch
my-custom (2)
1 Already existing icon ids
2 New icon id
The order of the entries in org.opennms.features.topology.app.icons.list determines the order in the icon selection dialog in the topology map.