Difference between revisions of "ZenPack:Layer2"

From Zenoss Wiki
Jump to: navigation, search
(release 1.1.0)
Line 15: Line 15:
|Release date=2015/11/20
|Release date=2015/11/20
|Compatible with=Zenoss Core 4.2.x, Zenoss Core 5.0.x, Zenoss Resource Manager 5.0.x
|Compatible with=Zenoss Core 4.2.x, Zenoss Core 5.0.x, Zenoss Resource Manager 5.0.x
Line 349: Line 349:
* Initial release
* Initial release

Revision as of 14:47, 23 November 2015

Zenoss, Inc.
GNU General Public License, Version 2, or later
ZenPack name
More Information
GitHub page/HomePage
Git sources (for cloning)

Layer2 ZenPack

Monitoring of OSI Layer 2 networking infrastructure.


The ZenPack Catalog has moved to its new home at https://www.zenoss.com/product/zenpacks as of January 17, 2017. The following information may be out of date, and this page will eventually be removed.


This is an Open Source ZenPack developed by Zenoss, Inc. Enterprise support for this ZenPack is available to commercial customers with an active subscription.


Version 1.0.3- Download
Released on 2015/07/31
Requires PythonCollector ZenPack
Compatible with Zenoss Core 4.2.x, Zenoss Core 5.0.x, Zenoss Resource Manager 4.2.x, Zenoss Resource Manager 5.0.x
Version 1.1.0- Download
Released on 2015/11/20
Requires PythonCollector ZenPack
Compatible with Zenoss Core 4.2.x, Zenoss Core 5.0.x, Zenoss Resource Manager 5.0.x


This ZenPack provides support to model OSI Layer 2 (or data link layer) topology. Than that topology information is used to suppress events from devices connection to which was lost because they are connected to broken devices. Data collection is performed using SNMP.



The features added by this ZenPack can be summarized as follows. They are each detailed further below.

  • Discovery and periodic remodeling of Neighbor Switches using CDP/LLDP.
  • Discovery and periodic remodeling of MAC address or forwarding tables.
  • Event suppression based on discovered forwarding table information.

Discovered Components

Assigning the zenoss.snmp.CDPLLDPDiscover modeler plugin to device(s) will result in SNMP discovery of neighbor switches using a combination of CISCO-CDP-MIB and LLDP-MIB. The discovered neighbor switch information will be shown as Neighbor Switches in the device's component list.

Assigning the zenoss.snmp.ClientMACs modeler plugin to device(s) will result in SNMP discovery of the device's forwarding tables using BRIDGE-MIB. This information will be stored on existing Network Interfaces, and won't result in any new components being created.


This ZenPack performs no monitoring.

Event Suppression

The forwarding table information gathered by the zenoss.snmp.ClientMACs modeler is used to automatically perform event suppression in the case of switch failure.

If Zenoss has modeled the forwarding tables of a server's upstream switches, and those switches fail resulting in the server becoming unreachable, the server failure events will be suppressed while the root cause failures of the switches will be shown.

To determine connectivity of device to zenoss instance, this ZenPack needs to know where on the network map zenoss instance is located. It is described on Configuration properties of devices class in zZenossGateway zproperty. At ZenPack installation it populated with value found in /proc/net/route. If required, you may manually put there id of the zenoss device, or device to which it is connected.

Network map

Network map

To inspect interconnections between devices it is possible to use a network map page which is accessed by "Infrastructure" -> "Network Map" tab or "Network Map" menu item of the opened device. It shows connections between devices, interfaces, networks and other entities. In addition, it shows device status (Color of the event with the highest severity for that device).

To display a network map the form on the left side of network map should be filled. "Device ID" field with name or ID of the device starting from which the map will be explored. The depth of the map means how many hops to do when exploring the map. Also, it is possible to select network layers which should be visible on the map. By default all of them will be displayed. To apply changes or create new network map, press "Apply" button at the bottom of the form.

Right mouse click above node opens context menu with options available. 'Pin down' option allows to unpin chosen node. Detailed information about device is available by clicking on 'Device Info' option from context menu. To draw network map in scope of another node please choose 'Put map root here' option from context menu. It is possible to open device or device component by clicking on corresponding target of network map.

Map could be zoomed using mouse wheel, and panned using mouse. If it disappears from the view, it could be brought back, using "Center" button in the top right corner of the map. There is also zoom level indicator, and color legend.


Network map could have edges that belong not only to Layer2 in general, but to some VLAN. This is links from VLAN-aware switch to its interfaces, and to it's client MAC addresses. This edges could be filtered by their VLAN.

When you select some VLANs on Layers panel, edges that belong to VLANs not included in selection will be removed from map. Layer2 edges without VLAN or edges that have VLAN that is selected will be shown.

zenmapper daemon

To update catalog with connections for network map, zenmapper daemon is used. It runs every 5 minutes by default, but this option could be changed by passing desired number of seconds to the --cycletime argument.

zenmapper connects to the ZODB and indexes all the connections provided from providers in ZODB catalog. On 4.2.x RM, running zenmapper on the remote collectors will do nothing because zenmapper runs against the hub. If desired, the additional zenmapper can be disabled by updating /opt/zenoss/etc/daemon.txt on the remote collector.

Writing your own connection provider

Imagine, for example that we want to display on the network map connections of VMware NSX components. They are modeled in NSX ZenPack.

We need to create new class, called for example NSXConnectionsProvider, which inherit from BaseConnectionsProvider, like this:

# our provider will inherit from this:
from ZenPacks.zenoss.Layer2.connections_provider import BaseConnectionsProvider
# and will yield this:
from ZenPacks.zenoss.Layer2.connections_provider import Connection
class NSXConnectionsProvider(BaseConnectionsProvider):
    def get_connections(self):
        # self.context is a entity for which we will provide connections
        for switch in self.context.nsxvirtualSwitchs():
            # so, our device is called NSXManager, and it has switches
            # yield connections to the switches
            yield Connection(self.context, (switch, ), ('layer3', 'nsx'))
            # each switch has interfaces:
            for i in switch.nsxinterfaces():
                # yield connection to the interfaces
                yield Connection(switch, (i, ), ['layer3', 'nsx'])
                # and each interface has many to one connection to edges:
                yield Connection(i, (i.nsxedge(), ), ['layer3', 'nsx'])

So, we described how to get connections, now we need to tell zenoss, that this will be connections provider for any NSXManager devices. We do it by registering adapter in our ZenPack's configure.zcml:

<configure zcml:condition="installed ZenPacks.zenoss.Layer2.connections_provider">
    <!-- Add this adapters only when module connections_provider is possible to import
         (Which means that there is installed recent version of Layer2). -->

Another way to include adapters, is to put them in separate file, called for example layer2.zcml:

<?xml version = "1.0" encoding = "utf-8"?>

and than include that file conditionally:

    <include file="layer2.zcml"
             zcml:condition="installed ZenPacks.zenoss.Layer2.connections_provider" />

To test connections that your provider yields, you could run

zenmapper run -v10 -d <name or id of your modeled device>

And then look it up on the network map.


This ZenPack has two separate capabilities. The first is to collect clients connected to switch ports so that event suppression can be done when the switch fails, and the second is to discover neighbor relationships between network devices using the CDP (Cisco Discovery Protocol) and LLDP (Link Layer Discover Protocol).

Collecting Switch Port Clients

To enable discovery of clients connected to switch ports you must enable the zenoss.snmp.ClientMACs modeler plugin for the switch devices. There is no need to enable this plugin for hosts, servers, or other endpoint devices. It is recommended to only assign the modeler plugin to access switch to which monitored servers are connected.

The discovery is done using BRIDGE-MIB forwarding tables, so it's a prerequisite that the switch supports BRIDGE-MIB.

Collecting Network Device Neighbors

To collect neighbor information from network devices that support CDP or LLDP, you must enable the zenoss.snmp.CDPLLDPDiscover modeler plugin for the devices.

This ZenPack has the following requirements.

PythonCollector ZenPack
This ZenPack depends on PythonCollector being installed, and having the associated zenpython collector process running.

Service Impact

When combined with the Zenoss Service Dynamics product, this ZenPack adds built-in service impact capability based on Layer 2 data. The following service impact relationships are automatically added. These will be included in any services that contain one or more of the explicitly mentioned entities.

Service Impact Relationships
  • Device impacted by upstream switch device.



If you are re-installing or updating this ZenPack on Europa, you should first check in control center that zenmapper daemon is stopped, and if not - stop it. It should be stopped automatically, but while this issue is not fixed, you should do that by hand.

Debugging network map

This ZenPack gathers information about connections on different layers of network, and displays it on network map. If you see some connections that should not be there, or are missing, first you could check if network map is rendered from proper model - connections catalog.

To do that, install tabulate python package (pip install tabulate), start zendmd shell and run:

    from ZenPacks.zenoss.Layer2.connections_catalog import CatalogAPI
    cat = CatalogAPI(zport)
    # example queries
    cat.show_content() # show all catalog
    cat.show_content(entity_id='/zport/dmd/Devices/Network/Switch/devices/') # show only connections for given entity
    cat.show_content(connected_to='/zport/dmd/Devices/Network/Switch/devices/') # show what is connected to this entity
    cat.show_content(layers=['layer2']) # show only connections on some layer

If you don't see connections you expecting to see, you could check if zenmapper builds network map properly by running it with high verbosity:

zenmapper run -v10
zenmapper run -v10 2> zenmapper.log # to redirect it to file

Then you will see following log entries:

2015-09-14 13:14:58,521 DEBUG zen.Layer2: Connection from ... to ... on layers ... added to connections_catalog

When connections that reported by that log are erroneous, then probably there are errors in connections providers for your device, or in device model itself.

Layer2 forwarding table

Let's discuss Layer2 connections in particular.

The essential mechanism that distinguishes network switches from network hubs is the MAC forwarding table. Instead of broadcasting incoming link layer frames to all it's interfaces, as hubs do, switches look into the forwarding table to find out which particular interface is connected to the destination device. The switch learns which devices are connected to which interface by looking at the source MAC address of incoming frames. Those MAC addresses are called "client MAC addresses".

For zenoss to discover Layer 2 connection between some devices, MAC address of some interface of one device should be equal to client MAC address of some interface of other device. You could check if client MAC addresses for interface are modeled by looking at it's "Clients MAC addresses" display. It there are none, check that zenoss.snmp.ClientMACs modeler plugin is bound to device, and remodel device.

It is also possible that there are no MAC address required to discover connection in forwarding table. To check that, you could run debug utility bridge_snmp.py:

    python bridge_snmp.py clientmacs -c <community_string> <host>

and see if your client mac address is visible at switch at all.

Records in forwarding table are aged pretty fast, by default in 5 minutes. So, when there were no network activity on connection for more than 5 minutes, entry will be removed from switch forwarding table. You could check dot1dTpAgingTime object to know exact timeout period in seconds:

$ snmpget -v2c -c <community_string> <host>
SNMPv2-SMI::mib- = INTEGER: 300


This ZenPack also adds impact relation for layer2 connections. Switches impact devices connected to them. But this will work only when such connection is present on network map (see two previous sections for guide on troubleshooting that).

If there is connection on network map, but still, no impact relation, than, probably impact relations were not rebuilt. You could do that by indexing device, for example by changing some field on overview and saving it. Or modeling device again.


There are no client MACs data on interfaces modeled for the first time. This happens because zenoss.snmp.ClientMACs plugin runs before interfaces are modeled by another network modeler plugin (for example cisco.snmp.Interfaces or zenoss.snmp.InterfaceMap), so there is no entities to save this attribute on. Currently it is not possible to define order of modeler execution, so this remains a limitation.

Possible workaround is to wait for next model cycle or just model the device again manually.

More information

If you cannot find the answer in the documentation, then Resource Manager (Service Dynamics) users should contact Zenoss Customer Support. Core users can use the #zenoss IRC channel or the community.zenoss.org forums.

Installed Items

Installing this ZenPack will add the following items to your Zenoss system.

Modeler Plugins

  • zenoss.snmp.CDPLLDPDiscover
  • zenoss.snmp.ClientMACs


  • zZenossGateway


  • zenmapper


  • When filtering by VLAN show also layer2 links that are VLAN-unaware (ZEN-20946)
  • Add checkbox that allows to show full map
  • Fix Cisco community string indexing in ClientMACs modeler plugin.
  • Fix issue getting client MAC address from labeled VLAN interfaces. (ZEN-19874)
  • Fix Network Map - Missing link from Cisco device to subnet on depth 2,3,4 (ZEN-18603)
  • Make Impact use new connections catalog instead of macs catalog (ZEN-18636)
  • Fix Broken link for Subnet node in Network map (ZEN-20749)
  • Remove macs_catalog when removing the ZenPack. (ZEN-17967)
  • Replace Layer2Info template with ClientMACs modeler plugin.
  • Fix modeling of CDP neighbor switches with IPv6 addresses. (ZEN-17248)
  • Avoid community@VLAN context querying for non-Cisco switches. (ZEN-17258)
  • Change default cycletime for Layer2Info from 30 minutes to 12 hours. (ZEN-17031)
  • Fix device overview links error. (ZEN-14063)
  • Remove add/remove from catalog logging. (ZEN-15465)
  • Fix usage of incorrect community VLAN suffixes on BRIDGE-MIB queries. (ZEN-16951)
  • Fix looping of impact relationships between switches. (ZEN-17020)
  • Fix incorrect modeling of neighbor switches and improve modeling time. (ZEN-17023)
  • Stop binding Layer2Info template to /Network by default. (ZEN-17035)
  • Initial release


Normal Installation (packaged egg)

  1. Download the appropriate egg file for the version of Zenoss you are running.
  2. Ensure you are logged in as the zenoss user:
    $ sudo su - zenoss
  3. Install the ZenPack:
    $ zenpack --install ZenPacks.zenoss.Layer2-*.egg
  4. Restart these services:
    $ zenoss restart

Developer Mode Installation

In order to do a development mode installation you will want to clone the existing git repository, and then use the --link flag with the zenpack command:

  1. Ensure you are logged in as the zenoss user:
    $ sudo su - zenoss
  2. Start by cloning the upstream repository:
    $ git clone https://github.com/zenoss/ZenPacks.zenoss.Layer2.git
  3. Next, perform the installation:
    $ zenpack --link --install ZenPacks.zenoss.Layer2
  4. Finally, restart these serivices:
    $ zenoss restart


Purplemarker.png New: Don't forget to add yourself to the Zenoss User Map!

blog comments powered by Disqus