1.4. Release Notes 2.1.0

1.4.1. NetSpyGlass v2.1.0

This is the first release in the v2.1.x series. Key highlights:

  • many improvements in the UI, such as display of the historical network maps, filters that can be applied to existing maps, ability to build network maps in the UI, support for changing time display format and timezone setting in the UI
  • a “universal search” widget in the UI can be used to find devices and interfaces by name, IP address, MAC address, device serial number or device model name
  • support for SNMPv3
  • integration with netflow data collection and analysis service by Kentik ( https://www.kentik.com/ ). See Integration with Kentik
  • integration with data collection and monitoring by DataDog ( https://www.datadoghq.com/ ). See Data Export to DataDog
  • Support for discovery of the network configuration, basic hardware components, virtual servers and server pools for F5 BigIp devices.
  • NsgQL, an SQL-like language and API support that can be used to match and select attributes of monitoring variables, devices, interfaces, maps, alerts and silences in NetSpyGlass server. NsgQL queries can be sent to the server using REST API call or with the help of a command line script nsgql.py. See NetSpyGlass Server Query Language for more details.

Important

You need to clear contents of the directory /opt/netspyglass/home/data/zookeeper/ before starting the server after upgrade to this version.

Important

If you run your NetSpyGlass server with MySQL, then NetSpyGlass v2.1 requires MySQL v5.7.x. If you have older version, upgrade your MySQL server before upgrading NetSpyGlass.

Important

Configuration file parameter network.display.time have been deprecated and replaced with network.display.timeZones and network.display.timeFormats. Both of these new configuration parameters are lists of time zones and time formats, respectively, the UI presents to the user in the “Settings” dialog, tab “Time Format”. By default the UI uses the first time zone and the first time format from each list until the user changes this in the dialog.

1.4.2. Improvements, Important Changes and New Features

1.4.2.1. General

  • This version introduces integration with DataDog. NetSpyGlass can send time series and events to DataDog. See Data Export to DataDog
  • This version introduces integration with netflow collection and analytics service by Kentik Technologies ( https://www.kentik.com/ ) See Integration with Kentik
  • NET-1441: upgrade hibernate to 5.2.6.Final; fix schema validation problems and inconsistencies
  • NET-1116: upgrade Zookeeper package to v3.5.3-beta to make it work with ipv6 addresses.
  • There are two ways to pass access token with API requests: 1) as query string parameter access_token or 2) as HTTP header with name X-NSG-Auth-API-Token
  • the “phone home” function reports the following information: server’s unique UUID, number of devices in the configuration file, license ID and the name it is registered to.
  • User authentication is now possible with local user accounts or against external LDAP server

1.4.2.2. UI

  • This version introduces support for historical maps. Click on the icon in the upper right corner of the network map switches it to the historical mode and the time line control appears at the bottom. To exit historical map mode, click the same icon again.

  • This version adds support for filters in maps. The user can apply a filter to devices and links in a map, the filter can match devices by name, address or tags and network interfaces by name or tags. Devices that do not match the filter “fade out” in the map. The user can give a filter a name and save it to the database. Filters belong to users who create them but owner can share a filter with other users. Filter consists of two parts: device matching rule and interface matching rule. First, device matching rule is applied and devices that do not match are marked. Then, interface matching rule is applied if it is defined. A link between two devices appears in the map if at least one end matches interface matching rule. An empty device or link matching rule is considered to always match everything. This means if the interface matching rule is empty, then all links in the map remain. Monitoring variables for devices in the map appear only for the devices that match the filter. Monitoring variables associated with interfaces appear as link-end labels only for the links that match the filter.

  • UI: we have added ability to move devices in groups in network maps. Click device icons in the map while holding Shift keyboard key. To select multiple devices this way, continue clicking their icons while holding Shift. Map layout menu actions (“Pin devices”, “Unpin devices”) can now act on selected groups of devices.

  • This version introduces support for the interactive network maps that can be built in the UI. Maps built with the aid of Python scripts still remain, but now the user can click large [ + ] in the tiles page to create new map. Maps created this way are owned by the user who created them, however the user can share them with others by clicking “Share” icon in the tile or in the map page. To edit a map like this, click “Edit” button in the tile or in the map page.

  • UI does not try to render maps with too many devices. The threshold is configured in the nw2.conf file using parameter network.display.map.deviceCountLimit. Default threshold value is 200.

  • Time display format and choice of the time zone are now available in the UI dialog “Settings”. Configuration file parameter network.display.time` have been deprecated and replaced with network.display.timeZones and network.display.timeFormats. Both of these new configuration parameters are lists of time zones and time formats, respectively, the UI presents to the user in the “Settings” dialog, tab “Time Format”. By default the UI uses the first time zone and the first time format from each list until the user changes this in the dialog. Configuration parameter network.display.tz is used to set the time zone in which the server is located. The server uses this setting whenever it needs to convert internal timestamp to a date/time display string, for example, when it sets “active since” time in an alert.

  • We have added a “universal search” component in the UI. NetSpyGlass can quickly find devices, network interfaces or maps by matching the following attributes against the search term entrered by the user:

    • device name, interface name or a map name (sub string match)
    • IP address of the device or interface
    • MAC address of an interface
    • device serial number
    • device model (substring match)

1.4.2.2.1. Monitoring

  • monitoring variables created for clusters (aggregates) retain only the tags that are common across all of the underlying regular variables

1.4.2.3. Configuration

  • we have added command line parameters that can be used to set address and port for the embedded Zookeeper. See Command line parameters

  • the following configuration parameters have changed:

    • graphingWorkbench – this configuration dictionary controls the appearance of variables in the Graphing Workbench
    • monitor.storage.variables – this parameter controls which variables are sent to TSDB for storage
    • subscription.filter – this parameters acts as a filter that is applied to variables the server is allowed to subscribe from other servers.

    There is new list “categoies” inside of graphingWorkbench:

    graphingWorkbench {
    
      # all variables that belong to the categories listed here will appear in the graphing workbench
      # even if their names do not appear in the list `graphingWorkbench.variables` below
      categories = [
         Alerts
      ]
    
      # limit number of variables shown in the data table. User is expected to use filter
      # when total number of variables is greater than this
      maxDataTableSize = 500
    
      variables = [
        ifAlias,
        ifOperStatus,
    

    Parameter graphingWorkbench.categories can be used to make all variables in a given category appear in the Graphing Workbench even if actual variable names are unknown. This is used to add alert variables by default.

    Parameters “monitor.storage.variables” and “subscription.filter” can have the following values:

    • “default” - this value corresponds to the same set of variables that appear in Graphing Workbench.
    • “*” - all variables
    • explicit list of variable names

1.4.2.4. Alerts

  • new self-monitoring variable alertNotificationErrorsRate (category “Monitor”) can be used to detect alert notification stream errors. Whenever alert notification delivery connector encounters an error, it increments internal counter. The value of the variable alertNotificationErrorsRate reflects the change in the value of this counter during the latest polling cycle. This variable can be used to build alert tracking other alert notification errors.

Note

The error counter increments in response to “soft” errors that trigger retry, so it may show non-zero error rates even when notifications could be delivered after retry.

1.4.2.5. Support for New Hardware Vendors and Devices

  • Added support for discovery of the network configuration and basic hardware components for F5 BigIp devices (memory, cpu, temperature sensors, power supplies and fans)

  • Added support for the discovery of virtual servers and server pools for F5 BigIp devices. The following monitoring variables are created by default:

    • ltmVsStatusEnabledState : The activity status of the specified virtual server, as specified by the user
    • ltmVsStatusAvailState : The availability of the specified virtual server
    • ltmPoolMemberCnt : The total number of members in the specified pool.
    • ltmPoolStatusEnabledState : The activity status of the specified pool, as specified by the user
    • ltmPoolStatusAvailState : The availability of the specified pool

1.4.2.6. Support for SNMPv3

This version introduces support for SNMPv3 in NetSpyGlass. This also required changes in the format of the device definition section of the configuration file. Devices are still added in the section network.devices, which is a list of dictionaries as before, however the structure of the dictionary that describes device has changed. Each device record consists of the following items:

  • address: this parameter defines ip address we use to talk the device. This can be either bare ip address or device name.
  • name: this optional parameter can be used to assign a name to the device object when it is identified by ip address, does not respond to SNMP queries (so its host name can not be determined) and when there is no DNS PTR record for its ip address
  • polling: a name of one of the polling configurations from the section network.polling or a string that consists of a comma-separated list of such names. If the value is just a single configuration name, then corresponding polling configuration is used. If the value of this parameter is a list of words, the server tries them in turn, assuming each word is a name of the polling configuration in the section network.polling. The server tries them at the beginning of the discovery process and uses the one that works.
  • snmpCommunity: This is a legacy parameter, it is ignored if parameter polling (see above) is used. The value of this parameter is R/O snmp community. Note that devices can have different community strings. If the value of this parameter is a blank string (e.g. snmpCommunity = “”“), then device is not going to be discovered or polled but will appear in maps if L3 link to it could be constructed from another device
  • snmpVersion: This is a legacy parameter, it is ignored if parameter polling (see above) is used. The value of this parameter is SNMP version that should be used for this device. Supported versions are 1 and 2. The value of this parameter should be a number as shown in the example below. If this parameter is missing, NetSpyglass uses SNMP version 2. Use parameter snmp if you need SNMPv3.

Device configuration dictionary refers to the polling configuration by name; actual polling configurations are defined in the section network.polling. Each entry in this section is a dictionary with the following items:

  • protocol: must be “snmp”
  • version: SNMP version (1, 2, 3)
  • community: used with versions 1 and 2. If the value of this parameter is a blank string (e.g. community = “”), devices using this SNMP configuration are not going to be discovered or polled but will appear in maps if L3 link to it could be constructed using information collected from another device
  • user: used with SNMP v3
  • password: corresponding password
  • secLevel: This is a string that defines security level for SNMPv3. The following levels are recognized: noAuthNoPriv, authNoPriv, authPriv
  • auth: authentication. MD5 and SHA are supported.

Default configuration file defines the following polling configurations:

polling = {

    v1public : {
        protocol : snmp,
        version : 1,
        community : public
    },

    v2public : {
        protocol : snmp,
        version : 2,
        community : public
    },

    v3md5public : {
        protocol : snmp,
        version : 3,
        secLevel : authNoPriv,
        auth : MD5,
        user : snmpuser,
        password : public
    },

}

Note

Limitations in SNMPv3 support in the current version of NetSpyGlass:

  • only USM security model is supported
  • in case security model authPriv is used (both authentication and privacy are turned on), the same password is used for both, and privacy is always set to DES (des56)

1.4.2.7. ‘Discovery’ of the polling configuration

Attribute polling of a device can list several polling configuration names. For the following example device is configured with two polling configurations, v2test and snmpv3_1:

devices = [

     { address = "10.0.15.228",  polling = "v2test,snmpv3_1"  },

]

In the case like this, NetSpyGlass tries listed polling configurations one by one to see which one works and stores the name of the working one with the internal object that represents this device. Working polling configuration is used to do SNMP queries to collect monitoring data. Polling configuration “discovery” is only done as part of the network discovery sequence. Data collector always uses recorded polling configuration that was found to be working during the latest network discovery process. If you change SNMP polling configuration on the device, NetSpyGlass can find it and update its internal model during the next network discovery run.

1.4.2.8. Changes and Improvements in Network Discovery

  • When NetSpyGlass discovers BGP4 peering sessions, it can match them to the peering interfaces using static routing entries. This helps find interfaces when the peering is configured using an address assigned to the loopback interface, with /32 or /31 static routing entry pointing to the peer’s address

  • NET-1665 discover interface descriptions on Juniper SSG devices

  • device is not getting role “Router” if it has only one non-loopback interface, even if ip forwarding is enabled or its sysServices OID has bit 4 set

  • NET-1696 Do not add role “Router” when host has only one interface even when ip forwarding is enabled

  • NetSpyGlass discovers and automatically begins to monitor the operational status of hardware components on devices that support ENTITY-STATE-MIB. This has been tested with Arista and Hewlett Packard devices. Monitoring variable entStateOper has the following values:

    • 1 - unknown
    • 2 - disabled
    • 3 - enabled
    • 4 - testing
  • NetSpyGlass discovers and automatically begins to monitor the operational status of hardware components that have class module on Cisco devices if the device responds to the OID cefcModuleOperStatus in CISCO-ENTITY-FRU-CONTROL-MIB. The server creates variable cefcModuleOperStatus for this. Its values come from the MIB and describe one of 27 different states the component can be in.

  • A new monitoring variable hwOperState is created as a normalization of the values taken from entStateOper and cefcModuleOperStatus. Values of hwOperState are consistent with other variables used to track operational state of fans and power supplies. Value “1” indicates state “ok” and value of “0” indicates any kind of failure. This variable is suitable for building vendor-independent alerts.

1.4.2.9. NsgQL

This version introduces NsgQL, an SQL-like language and API support that can be used to match and select attributes of monitoring variables, devices, interfaces, maps, alerts and silences in NetSpyGlass server. NsgQL queries can be sent to the server using REST API call or with the help of a command line script nsgql.py. See NetSpyGlass Server Query Language for more details.