Managing NetVoyant through Web Services

Web services can be used to manage NetVoyant devices.  I've had at least one customer who built auto-provisioning of NV monitoring through web services.  It can be a headache, but it is possible.  I won't go into details about how to actually automate the use of the web services; go take a class for that.  This practice actually goes against my preferred method of adding all devices to NV and using class designations, auto-discovery rules, and auto-enable rules to manage what gets monitored.  However, in some cases, that can't be done.  Here are the details on the web services.

In any distributed system, there are two types of systems: NV Master Console and NV Poller.  NV uses scopes to manage the devices to be monitored.  Each scope details an IP address to be monitored, a subnet mask, and the poller responsible for monitoring it.  The process of adding and removing devices from NV involves manipulating the scope that corresponds to the device to be added or removed.

Adding a device to NetVoyant

If you are using web services to add devices to a distributed NetVoyant system, you'll either want to add the device to the poller responsible for polling all the devices in that region OR you'll want to add it to the poller that is least loaded (in terms of total number of devices).  It's also possible that you may have multiple pollers covering a single region and need to determine which poller is least loaded.In order to find out the number of devices on each poller, the GetDeviceCount operation of the NetVoyantService should be invoked on each poller (and not the master console).
The NetVoyantService can be found at /pollerwebservice/NetVoyantService.asmx?WSDL on each poller.  By invoking this procedure without any arguments, the result will be XML indicating how many devices total are on that particular poller.  Unfortunately, this must be run against each poller to get that poller's count.  Below is shown a sample output.

<?xml version="1.0" encoding="utf-8" ?>
<int xmlns="http://netqos.com/NetVoyantWS/">41</int>


This procedure can be built into the logic required for deciding to which poller the new device will be added.

Topology Service - Adding a Device to the Discovery Scopes

Adding a device to NV (whether manually or by using a web service) involves two processes that NV must execute: adding the device to the discovery scope and initiating device discovery. One web service operation initiates both of these actions.  The operation is called DiscoverDevice and is part of the Topology service.  The only argument required is the IP address of the device to be discovered.  The operation should be invoked on the poller with the fewest number of devices (as determined by using the service described in the previous section).  If the administrator would rather have the device polled using a name instead of an IP address, a FQDN can be entered instead, assuming the NV poller can translate that name to an IP address at poll time.  Extended discovery should usually be set to false.  This feature instructs NV to poll the target device for its neighbors and attempt to poll the neighbors.
The topology service can be found at /pollerwebservice/TopologyService.asmx?WSDL on every poller.  The IP address of the device to be added is passed as an argument to the web service through XML.  The response from the web service will be XML indicating true or false.  This boolean indicates whether or not the IP address was successfully added to the scope.  It doesn't indicate whether discovery was successful or not, it only indicates whether or not the IP was successfully added to the scope.

Verifying Polling of a Device

When NV begins discovery on a device, one of three outcomes is possible: (1) the device is reachable via ICMP and pollable via SNMP, (2) the device is reachable via ICMP but not responding to SNMP requests (bad community string, ACL preventing access, etc.), or (3) the device is not reachable via ICMP. In case 1, the device will be discovered and begin polling according to NV’s current configuration. In case 2 and 3, a device record will be created in the NV database, the device will be classified as ‘Other’, and NV will try again during the next full or partial discovery to discover the device. During the next full or partial discovery, NV will attempt to contact the device via ICMP. If the ping is successful, NV will attempt to poll the device via SNMP as in case 1.

Case 1: Pingable and Pollable

In order to verify that a device is being monitored in NV, the DeviceList operation of the PollerService web service may be invoked. The DeviceList operation returns XML containing a list of all the discovered interfaces in NV, as they relate to their parent device. Only interfaces from SNMP capable devices will be returned. If an interface exists in this list, NV has successfully discovered that interface’s device. Each interface results in an XML table containing the parameters of the parent to which the interface belongs. Unique DeviceID, Name, and Alias fields can then be found in the table by filtering the IPAddress field by the IP address of the device; that data can then be stored in the Performance Database within the CMDB.

Cases 2 & 3: Not Pingable or Not Pollable

If a device does not appear in the DeviceList, NV may have been able to ping the device but not poll the device. If a device ID cannot be located using the method described above, the device was not successfully discovered either because NV cannot reach the device via ICMP or NV cannot poll the device via SNMP. In either of these cases, the administrator should troubleshoot NV’s inability to ping/poll the device.


The PollerService can be found at /pollerwebservice/PollerService.asmx?WSDL on every poller, and can be executed on the Master Console or the specific poller on which the device in question resides.  Invoking this web service will result in XML returned detailing the information about every device in the database on the poller queried.  By analyzing this output, it is fairly easy to determine if the device was polled.  Below is an excerpt from the output of a sample call to a test server.

<Table diffgr:id="Table15" msdata:rowOrder="14">
    <DeviceID>30</DeviceID>
    <Name>Server1</Name>
    <Alias>Server1</Alias>
    <SysName>Server1</SysName>
    <Description>Windows Version 6.1 (Build 7601)</Description>
    <SnmpCapable>2</SnmpCapable>
    <DeviceClass>Servers</DeviceClass>
    <ModelName>Windows NT Workstation</ModelName>
    <InterfaceID>1624</InterfaceID>
    <IPAddress>192.168.1.146</IPAddress>
    <Mask>255.255.255.0</Mask>
    <AddressName>192.168.1.146</AddressName>
    <ifIndex>11</ifIndex>
    <InterfaceDescription>PCIe FE Controller</InterfaceDescription> 

 </Table>

This portion of the output indicates an interface on a device that is fully reachable via ICMP and via SNMP. This is indicated by the <SnmpCapable> tag value of 2.  If you are trying to verify the successful discovery of a device given the IP address, simply look for the IP address within the <IPAddress> tags.

Removing a device from NetVoyant

To remove a device from NV, an administrator needs to remove the device’s IP address from the discovery scopes. This will indicate to NV that it should discontinue polling the device. At this point, the administrator has two options: he can explicitly delete the device record (along with all the historical data for that device) or he can allow NV to perform this task after a specified number of days in response to the deletion of the device’s scope. It is recommended to allow NV to perform this deletion thereby removing the possibility for human error. This operation also precludes any type of manual intervention.

The global setting ‘Device Expiration’ is defined in the master console and determines the number of days a device (and its historical data) will remain in the database after NV has determined that the device is out of scope. The default is 28 and can be set to whatever timeframe the administrator would like, even zero days, which would result in semi-immediate deletion of the device.

NV will not notice that the device is out of scope until it runs the next partial or full discovery, which is usually scheduled for every 24 hours and every 7 days, respectively. During discovery the expiration timer begins counting down from the number of days set in the ‘Device Expiration’ parameter. Once the countdown timer reaches zero, the device and all its historical data is deleted permanently.

TopologyService – DeleteScope

The removal of a scope from a particular NV poller can be accomplished by invoking the DeleteScope operation of the TopologyWebService, which can be found at /pollerwebservice/TopologyService.asmx?WSDL on every poller. The only required parameter is the scope, a string containing the IP address of the device to be deleted and the corresponding mask. If the strategy for NV has been to add one scope per device, the corresponding mask should always be 255.255.255.255. Therefore, to remove a device with IP address 10.1.2.3, the scope would be 10.1.2.3/255.255.255.255. The scope must exist for it to be deleted.
The response from the server will be XML containing a boolean indicating whether or not the scope was found and deleted.