- Zenoss, Inc.
- GNU General Public License, Version 2, or later
- ZenPack name
- More Information
- GitHub page/HomePage
- Git sources (for cloning)
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.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
- 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
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.
Latest released version is 1.1.0. It's currently under maintenance and will be available shortly with fixes.
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.
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.
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.
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.
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
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: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). --> <adapter factory=".connections_provider.NSXConnectionsProvider" for="ZenPacks.zenoss.NSX.NSXManager.NSXManager" provides="ZenPacks.zenoss.Layer2.connections_provider.IConnectionsProvider" /> </configure>
Another way to include adapters, is to put them in separate file, called for example
<?xml version = "1.0" encoding = "utf-8"?> <configure xmlns="http://namespaces.zope.org/zope" xmlns:zcml="http://namespaces.zope.org/zcml" > <adapter factory=".connections_provider.DeviceConnectionsProvider" for=".HyperVVSMS.HyperVVSMS" provides="ZenPacks.zenoss.Layer2.connections_provider.IConnectionsProvider" /> </configure>
and than include that file conditionally:
<include file="layer2.zcml" xmlns:zcml="http://namespaces.zope.org/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
zenpythoncollector process running.
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/192.168.1.1') # show only connections for given entity cat.show_content(connected_to='/zport/dmd/Devices/Network/Switch/devices/192.168.1.1') # 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
zenmapper builds network map properly by running it with
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
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> 126.96.36.199.188.8.131.52.2.0 SNMPv2-SMI::mib-184.108.40.206.0 = 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
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.
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.
Installing this ZenPack will add the following items to your Zenoss system.
- 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)
- Download the appropriate egg file for the version of Zenoss you are running.
- Ensure you are logged in as the zenoss user:
$ sudo su - zenoss
- Install the ZenPack:
$ zenpack --install ZenPacks.zenoss.Layer2-*.egg
- 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:
- Ensure you are logged in as the zenoss user:
$ sudo su - zenoss
- Start by cloning the upstream repository:
$ git clone https://github.com/zenoss/ZenPacks.zenoss.Layer2.git
- Next, perform the installation:
$ zenpack --link --install ZenPacks.zenoss.Layer2
- Finally, restart these serivices:
$ zenoss restart
New: Don't forget to add yourself to the Zenoss User Map!blog comments powered by Disqus