Linkd

From OpenNMS

Linkd!

Linkd is layer 2 iso/osi model network topology discovery daemon.

Availability

This feature is available in the "trunk" first appears in the 1.3.2 unstable release. This notes apply for 1.3.8 unstable release.

Quick Start

Opennms by default has linkd disabled, so you should enable it.

To enable linkd follow these simple steps:

Go to service-configuration.xml and uncomment the following lines:

 <service>
        <name>OpenNMS:Name=Linkd</name>
        <class-name>org.opennms.netmgt.linkd.jmx.Linkd</class-name>
                <invoke at="start" pass="0" method="init"/>
                <invoke at="start" pass="1" method="start"/>
                <invoke at="status" pass="0" method="status"/>
                <invoke at="stop" pass="0" method="stop"/>
 </service>

Restart openNMS, you can follow the progress of Linkd in the link.log

The inital Linkd discovery will take a bit as each nodes topology is discovered. The linkd daemon collects a lot of data from nodes to perform the network topology discovery, this should affect performance, so if you are running opennms with default memory allocation remeber to increase JAVA_HEAP_SIZE by 64Mbyte for each 5 threads used. By default linkd uses 5 thread to do the work.

Links and data collected by Linkd can be visualized in maps and in WEB UI element section.

Concept

Linkd Daemon is controlled by a '"Configuration File linkd-configuration.xml (located in the $OPENNMS_BASE/etc directory.) and do its work in two steps:

A) Performs SNMP data collection from nodes (Java Class SnmpCollection) for each node included in packages for each package

B) Discover layer 2 network topology using SNMP collected data (Java Class DiscoveryLink) for each packages among node included in package.

The SNMP data collection regards the following MIBS:

.iso.org.dod.internet.mgmt.mib-2.ip.ipRouteTable

Snmp Table that holds node's ip routing tables. These informations are saved by default in Database table ipRouteInterface

.iso.org.dod.internet.mgmt.mib-2.ip.ipNetToMediaTable

Snmp Table that contains node's ip address to mac address binding. These informations are saved by default in Database table atInterface

.iso.org.dod.internet.private.enterprises.cisco.ciscoMgmt.ciscoCdpMIB.ciscoCdpMIBObjects.cdpCache.cdpCacheTable Snmp Table that contains node's Cisco Discovery Protocol cdp Cache Table with all the data about Cisco neighbourgh devices.

For the nodes whose sysoid matches the sysoids supported and listed in the configuration file is collected the Snmp Vlan table that holds information on Vlans.

.iso.org.dod.internet.mgmt.mib-2.dot1dBridge.dot1dBase

.iso.org.dod.internet.mgmt.mib-2.dot1dBridge.dot1dStp

These MIBS have information about node's Bridge and Spanning Tree Protocol. The data collected regards information about nodes and its interfaces. This data is collected for each active and operative Vlan for Cisco and intel switches to support multi vlan STP.

The node's general data is saved by default in Databasetable StpNode and the node's interface data is saved by default in Database table StpInterface.

.iso.org.dod.internet.mgmt.mib-2.dot1dBridge.dot1dTp

This MIBS contains information on Bridge forwarding tables. That means how the bridge forward a packet looking at destination mac address. This table mantains informations on which switch port a packet must be forwarded. It's an association among bridge ports and mac addresses. This data is collected for each active and operative Vlan for Cisco and intel switches to support multi vlan STP.

Extreme Network switches put the bridge forwarding table under another tree MIB. Linkd in case the dot1dTp is clear try to download the QBridgeDot1dTp using the following Root OID: .1.3.6.1.2.1.17.7.1.2.2 Collection to collect specific snmp data (that we'll see depends on the package configuration). For each Package is scheduled a thread that uses DiscoveLink to find links among nodes.

The Discovery Link process find links among nodes using several option and configuration, the default link discovery uses the following steps:

Try to use Cisco Discover Protocol Cache Table to get links among Cisco Nodes. For nodes found on ethernet segments there is a test to be sure that the link is a true link (in fact for non CDP devices CDP acts as multicast so it's broadcasted on all ports). For example: you have a Cisco Router Ethernet port connected with a 3Com Switch that is connected to a Switch Cisco Catalyst, the CDP cache table of the Router and of the switch too should have an entry that says that they are nearest CDP devices. From the CDP point of view this information is correct but from network topology discovery this is wrong becouse the link is between Cisco Router and 3Com and between 3Com and Cisco Switch. So DiscoveryLink verify that the guessed link did not have other devices between. This is done just looking to the intersection of the Bridge Forwarding Table on the two bridge ports, if this intersection doesn,t contains a recognized bridge mac address the link is accepted.

Try to use the Bridge Snmp Info and the IpNetToMediaTable to find links on Ethernet LAN segments. This process starts using Spanning Tree Protocol node tables to find links among switches. Againg STP is like CDP a multicast protocol so if you have two STP enabled connected via a non STP enabled device the information you get from is of a link between the two STP devices. So again verify that the guessed link did not have other devices between. After STP link discovery the bridge forwarding table is used to find links. In such a manner you get all the mac addresses that are "linked" to a bridge port. Using the IpNetToMedia tables you find the ip address that is binded to mac address. From the Ip address you get the nodeid. A lot of special cases appears all related to the specific network configuration. For example you can have unmanaged devices connected to managed Snmp devices, DiscoveryLink finds all the nodes connected on the unmanaged device to the Bridge port on which the device is connected to the managed once.

Try to use Ip Routing Tables to find not ethernet links among nodes

DiscoveryLink process save discovered links (the topology) into database table datalinkinterface.

Each db table (atInterface, stpNode, stpInterface,vlan, ipRouteInterface, DataLinkInterface) row has a status tag that signify the status of the row.

"A" means Active (that means that linkd has this information updated)

"N" means Not Polled(that means that linkd has this information but was not lastly updated)

"D" means Deleted (that means that linkd has not more this information)

TIPS

Network topology discovery on ethernet Lans is done using the bridge and ipnettomedia tables. So if a complete discovery is needed it's necessary to have all these data. The bridge table is achieved just managing and enabling SNMP protocols on each layer 2 device. The information on ipnettomedia is shared by nodes on the network. Usually a almost complete table is found on the lans default gateway.

'To full discovery network topology it's recommended that every network device in the area network works using SNMP.

In an multivlan enrivirroment to resolve ip to mac address it is required that layer 3 switches shold be accessed via SNMP.

It is also suggested to enable SNMP on OpenNMS server to get ip to mac addresses ipnettomedia table.

Daemon Configuration

The Linkd daemon is controlled by The Linkd Configuration File linkd-configuration.xml (located in the $OPENNMS_BASE/etc directory.)

Here you see the default configuration distributed.

<?xml version="1.0" encoding="ISO-8859-1"?>
<linkd-configuration threads="5" initial_sleep_time="3600000"
                     snmp_poll_interval="18000000" discovery_link_interval="300000">
    
    
    <!--
    
    Here is a list of sys oids and corresponding classes to get 
    SNMP vlan info from nodes.  
    Verify that your switch devices sys oids are in the following lists
    if you want to get informations on Vlans!
    Otherwise:
    Put your own sys oids in the proper vendor tag and specify sys oid
    using <specific> and <include-range> tags 
    
    -->
    
    <vlans>

        <vendor vendor_name="3Com" sysoidRootMask=".1.3.6.1.4.1.43"
                class-name="org.opennms.netmgt.linkd.snmp.ThreeComVlanTable">
            <specific>1.9.13.3.1</specific>
            <specific>10.27.4.1.2.2</specific>
            <specific>10.27.4.1.2.4</specific>
            <specific>10.27.4.1.2.11</specific>
            <specific>1.16.4.3.5</specific>
            <specific>1.16.4.3.6</specific>
        </vendor>

        <vendor vendor_name="3Com3870" sysoidRootMask=".1.3.6.1.4.1.43.1"
                class-name="org.opennms.netmgt.linkd.snmp.Dot1qStaticVlanTable">
            <specific>8.43</specific>
        </vendor>

        <vendor vendor_name="Nortel" sysoidRootMask=".1.3.6.1.4.1.45.3"
                class-name="org.opennms.netmgt.linkd.snmp.RapidCityVlanTable">
            <specific>61.1</specific>
            <specific>35.1</specific>
            <specific>53.1</specific>
        </vendor>

        <vendor vendor_name="Intel" sysoidRootMask=".1.3.6.1.4.1.343.5"
                class-name="org.opennms.netmgt.linkd.snmp.IntelVlanTable">
            <specific>1.5</specific>
        </vendor>

        <vendor vendor_name="HP Networks" sysoidRootMask=".1.3.6.1.4.1.11.2.3.7"
                class-name="org.opennms.netmgt.linkd.snmp.Dot1qStaticVlanTable">
            <specific>11.1</specific>
            <specific>11.3</specific>
            <specific>11.13</specific>
            <specific>11.14</specific>
            <specific>11.18</specific>
            <specific>11.19</specific>
            <specific>11.20</specific>
            <specific>11.27</specific>
            <specific>11.23</specific>
            <specific>11.29</specific>
            <include-range begin="11.6" end="11.11"/>
        </vendor>

        <vendor vendor_name="cisco" sysoidRootMask=".1.3.6.1.4.1.9"
                class-name="org.opennms.netmgt.linkd.snmp.CiscoVlanTable">
            <specific>1.217</specific>
            <specific>1.218</specific>
            <specific>1.221</specific>
            <specific>1.247</specific>
            <specific>1.248</specific>
            <specific>1.283</specific>
            <specific>1.300</specific>
            <specific>1.324</specific>
            <specific>1.366</specific>
            <specific>1.367</specific>
            <specific>5.46</specific>
        </vendor>

        <vendor vendor_name="Extreme Networks" sysoidRootMask=".1.3.6.1.4.1.1916"
                class-name="org.opennms.netmgt.linkd.snmp.ExtremeNetworkVlanTable">
            <specific>2.11</specific>
            <specific>2.14</specific>
            <specific>2.28</specific>
            <specific>2.63</specific>
        </vendor>

    </vlans>

    <!--
    It's possible in packages to overwrite all properties - (thread and initial_sleep_time) 
    in the linkd-configuration
    -->
    
    <package name="example1">
		<filter>IPADDR != '0.0.0.0'</filter>
		<include-range begin="1.1.1.1" end="254.254.254.254"/>
    </package>
    
    <!-- Use more packages with huge network-->

    <!-- here is a configuration that is valid on ethernet LANs -->
    <!-- 
    <package name="LAN" use-ip-route-discovery="false">
		<filter>IPADDR != '0.0.0.0'</filter>
		<include-range begin="10.1.1.1" end="10.1.1.254"/>
    </package>
	-->

	<!-- here is a configuration valid on WAN where linkd try to get
	     links using cisco discovery protolol first and then routers ip route tables -->
	 <!--
    <package name="WAN" use-bridge-discovery="false">
		<filter>IPADDR != '0.0.0.0'</filter>
		<include-range begin="10.1.1.1" end="10.1.1.254"/>
    </package>
	-->
	<!-- here is a configuration in which you have to find links when using cross ethernet cables 
		among router. Linkd by default finds links on LAN using bridge forwarding table becouse it 
		guess that the node is linked to a switch port. By the way there are situations in which
		you can have some routers connected via cross ethernet cables. So this is a way to find that links.
	-->
	<!--
    <package name="LINUX-ETHERNET-ROUTERS" force-ip-route-discovery-on-ethernet="true">
		<filter>IPADDR != '0.0.0.0'</filter>
		<include-range begin="10.1.1.1" end="10.1.1.254"/>
    </package>
  	-->
    <!-- do you want that linkd send a new suspect event for each ip address found on devices? -->
    <!-- 
    <package name="AUTODISCOVERY" auto-discovery="true">
		<filter>IPADDR != '0.0.0.0'</filter>
		<include-range begin="10.1.1.1" end="10.1.1.254"/>
    </package>
    
     -->    
</linkd-configuration>

Let's take a look at the configuration parameters:

Linkd uses packages as usual opennms daemon like poller and collectd. Each package has its own set of ip addresses and special configuration attributes.

There are four main required configuration attributes:


<attribute name="threads" type="int" use="required">
The max number of threads used for snmp data collection on devices and discovery links.
This means that the linkd daemon has max 5 threads active performing basic operation.
This is only global setting.


<attribute name="initial_sleep_time" type="long" use="required">
The initial sleep time in mill seconds before starting any operation.
This is only global setting.

<attribute name="snmp_poll_interval" type="long" use="required">
This is the interval in mill seconds from two Snmp Collection on a node.
If specified in package overwrites attribute in root tag.

<attribute name="discovery_link_interval" type="long" use="required">
Time interval in mill seconds from last snmp collection and link discovery.
If specified in package overwrites attribute in root tag.

Threads, Snmp_poll_interval and discovery_link_interval values are each other correlated and depends on the number of collection. If you have a lot of Snmp Collection you should increase threads otherwise increase snmp_poll_interval and discovery_link_interval. The last value should be setted according to the fact that a discovery of links should be done when data collection is finished. The snmp_poll_interval indicates how many times is network topology discovery is done.

Use for packages is strongly recommended especially for etherogeneus networks.

For example, becouse WAN topology is substantially static you should calculate topology once a day. In Lans maybe you want to run topology discovery every four hours.

Let's try to do some simple consideration on the definition of the previus attributes.

For example: consider a LAN with 10 switches and a router (default gateway), to get links you need to perform snmp data collection on 11 nodes. Suppose data collection requires 1 minute on each node. And suppose you want to run topology discovery every hour. Let suppose threads=5, then you can collect data for 5 nodes in 1 minutes. Becouse you want to collectd all the data before linkdiscovery starts you have to be sure that the data collection is finished in "discovery_link_interval" you need to increase discovery_link_interval to 300000 (5 minutes). But with our guess we can collect data for 25 nodes.

So following settings should be safe:


<linkd-configuration threads="5" initial_sleep_time="600000"
                     snmp_poll_interval="3600000" discovery_link_interval="300000">

If we consider an envirroment with at least 100 switches and several routers we should increase threads or discovery_link_interval.

So the number of thread is just given by a simple formula: threads = (SnmpNodes) * (mean time to collect snmp data on node) / (discovery_link_interval)

In this case we have: 100 * 60000/300000 = 100/5=20

So a safe value for threads is "20". Otherwise you can increase discovery_link_interval to 600000!

Using a reverse formula we can calculate the number of nodes on which collect data from default configuration:

SnmpNodes= threads * discovery_link_interval / (mean time to collect snmp data on node) Guessing (mean time to collect snmp data on node) = 60000ms (1 minute) a simple calculation gives: nodes = 25

Of course it is recommended that discovery_link_interval < snmp_poll_interval.

If your network is slow you should increase "mean time to collect snmp data on node", If your network is fast you can decrease "mean time to collect snmp data on node".

Remember that increasing threads requires an increment of JAVA_HEAP_SIZE as previously discussed.

Let's see what other option are configurable, everyone is optional in the configuration file but has a default value. If you need to overwrite the default values add the attribute in the configuration file. Here is listed the xsd file with the default value. You can find a brief description of what is done.


<attribute name="auto-discovery" type="boolean" use="optional" default="false">
Whether Linkd should generate newSuspect events for ip addresses unknown to OpenNMS found on nodes snmp tables.

<attribute name="enable-discovery-download" type="boolean" use="optional" default="false">

Whether Discovery Link should try to get 
specific snmp bridge info probably lost in snmp data collection.
Should be enabled only in very complex network
where snmpCollection often fails.
Enabling this flags slows the discovery process a lot.   
(The main fact about this flag is that DiscoveryLink uses SnmpGet against SnmpWalk used by SnmpCollection,
 this is useful when there are some non standard response from Snmp Agent)

<attribute name="enable-vlan-discovery" type="boolean" use="optional" default="true">
Whether SnmpCollection has to collect snmp Vlan tables on devices.
The Vlan Table data collection is made using the classes defined in vlans elements. 

<attribute name="use-cdp-discovery" type="boolean" use="optional" default="true">
Whether links discovery process should use 
cisco discovery protocol snmp tables.

<attribute name="use-ip-route-discovery" type="boolean" use="optional" default="true">
Whether links discovery process should use ip route tables.

<attribute name="use-bridge-discovery" type="boolean" use="optional" default="true">
						Whether links discovery process should use
						snmp bridge and spanning tree tables.

<attribute name="save-route-table" type="boolean" use="optional" default="true">
Whether Linkd has to save snmp ip route tables to database

<attribute name="save-stp-node-table" type="boolean" use="optional" default="true">
Whether Linkd has save bridge base informations to database.

<attribute name="save-stp-interface-table" type="boolean" use="optional" default="true">
Whether Linkd has to save to database bridge interfaces informations to database.

<attribute name="force-ip-route-discovery-on-ethernet" type="boolean" use="optional" default="false" >
Whether Linkd has to find links using ip route tables on ethernet interfaces.
By default discovery process skips ip route table for ethernet interfaces.

Finally we consider the vlans element that maps Vendor Devices Sysoid with the specific class to use to get snmp Vlan table.

In fact each vendor has its own specific snmp vlan table where to get vlan setting.


<element ref="this:vlans" minOccurs="1" maxOccurs="1">
A section to get specific Vendors Vlan
informations that are used to get vlan tables on nodes.

Once the general settings are in place the only thing left to tell the linkd is for which sysoids try to collects vlan and bridging infos. This is controlled by tags:

vlans: specify a list of sysoids for which download SNMP vlan table.
vendor: Allow you to specify a set of sysoids whose root is set by a vendor sysoidrootmask attribute and using the following tags.
include-range: <begin>start-sub-oid</begin><end>end-sub-oi</end>
specific: sub-oid
exclude-range: <begin>start-sub-oid</begin><end>end-ip-address</end>

The vendor tags in the default configuration file are tested. If you have switches with different sysoid you have to find an appropriate vlan class to get Vlans and add a vendor tag for this.

For example consider that you have a Cisco catalyst295024 whose sysoid is: 1.3.6.1.4.1.9.1.324

And you want to get Vlan info on that device. You should look under Cisco vendor tag if this sysoid is in place:

  <vendor vendor_name="cisco" sysoidRootMask=".1.3.6.1.4.1.9"
                class-name="org.opennms.netmgt.linkd.snmp.CiscoVlanTable">
            <specific>1.217</specific>
            <specific>1.218</specific>
            <specific>1.221</specific>
            <specific>1.247</specific>
            <specific>1.248</specific>
            <specific>1.283</specific>
            <specific>1.300</specific>
            <specific>1.324</specific>
            <specific>1.366</specific>
            <specific>1.367</specific>
            <specific>5.46</specific>
        </vendor>

and you see is in place.

if you want Vlan on cat6506 whose sysoid is: 1.3.6.1.4.1.9.1.282 you should add to cisco vendor tag:

<specific>1.282</specific>

REMARK AutoDiscovery

AutoDiscovery Let linkd send a newSuspectEvent when an unknown ip address is found. For an issue, in 1.3.8 it is enabled by default. So if you don't need autodiscovery enabled you have to set auto-discovery="false" in linkd-configuration.xml. This notes applies only for 1.3.8. By default in following release autodiscovery is disabled.

WEB User interface

There are some JSP (like box in includes dir and pages in element dir) to take a look at the infos saved in db tables. Here you see the complete list of what is going to do:

A. mac address search in element/index.jsp
B. Include mac address info for element/interface.jsp
C. Include link to element/linkednode.jsp in element/node.jsp
D. Include link to element/routeipnode.jsp in element/node.jsp
E. Include link to element/bridgenode.jsp in element/node.jsp
F. Include box includes/nodebridge-box.jsp in element/node.jsp
G. Include box includes/noderouteInfo-box.jsp in element/node.jsp
H. Include box includes/nodeStpint-box.jsp in element/node.jsp
I.   Include box includes/interfaceLink-box.jsp in element/interface.jsp
L.  Include box includes/interfaceStp-box.jsp in element/interface.jsp

Links should also be visualized on maps

Troubleshooting

Link is not discovered

is the sysoid of your device included in the configuration described above? Some devices using non-standard mib tables won't work. If the sysoid is not included but a similar device from the same vendor is referenced in the config try to add the sysoid of your device. If it works open an enhancement bug to get it included in future releases.

is the ip address of your device included in a range in the configuration described above?

is the snmp community configured in opennms? Go to the node page of your device in opennms and check if "SNMP Attributes" is visible on the node page

can you snmp walk your device from your opennms server?

If you can do an snmp walk grep in the output from the snmp walk for the MAC address of the device on the other side of the missing link. If the MAC is in there, and opennms has the snmp values of the device, linkd should discover the link.

What is your intervall for linkd to run? Maybe you just have to wait for the next run of linkd. Check the log files when it is running.

Is the device on the other end of the missing link always busy talking? If it is "quiet" while linkd collects the snmp tables it depends on the timeouts of the device where linkd tries to get the MAC tables - if the timeout for the MAC tables is too short the MAC will be thrown away and linkd can't find anything.