WmiConfiguration
Subscribe

From OpenNMS

Jump to: navigation, search

Contents

OpenNMS WMI Support

OpenNMS WMI Summary

Terms

WMI Class

This is the class of instances within WMI. An example of this would be the Win32_ComputerSystem class. This class contains objects representing properties and methods available.

WMI Object

A WMI Object is technically a member of a WMI property set. Using the previous example of Win32_ComputerSystem this class contains a variety of properties that we can look at and poll. The default "WMI" service uses the "Status" property to determine if the system is running and if WMI is available.

WMI InstanceOf

The "InstanceOf" method is the most common usage of WMI within OpenNMS. This gets a set of instances of WMI classes. When you specify a WMI Class and a WMI Object this is the behavior that WMI will default to. For example Win32_ComputerSystem is a single instance but Win32_Service is a set of instances representing every Windows service installed on your target system.

WMI WQL

Microsoft WMI also implements an "ExecQuery" method which is more common in Windows scripting but less common in OpenNMS polling and monitoring. WQL, which stands for "SQL For WMI" according to Microsoft, is a simple SQL-like syntax for querying WMI classes, properties and instances. Here's an example of a WQL query that you could use to discover whether a Windows service is running: 

Select State From Win32_Service Where Name='Server'

WMI Instances

In WMI when you query for information you always receive a set of objects (WMI Class instances) back from the target. In some cases these are classes which the system has only one possible representation (a specific host will always be only one Win32_ComputerSystem, at least for now.) But there are several classes represented in WMI which will return multiple instances. Here's a quick list of some common multi-instance classes. Upon seeing them you will understand better:

  • Win32_Service
  • Win32_Process
  • Win32_PhysicalDisk
  • Win32_LogicalDisk
  • Win32_NTLogEvent

Compare Operation

The "compare operation" is how you tell the OpenNMS WMI poller plugins how to verify the nature (up, critical) of a specific property within WMI. In the event of unequal comparisons the system will always have the WMI value (as retrieved from the target) on the left. Available compare operations are:

  • EQ (Equals)
  • NEQ (Not Equals)
  • GT (Greater Than)
  • LT (Less Than)
  • NOOP (No Operation)

The NOOP operation is a special case in which the Manager will always return a result code of "OK." This is typical used in scenarios where the existence of a class or property is more interesting than the contents of the property. We use this in the collector to check and ensure that WMI is available before attempting to collect data.

Match Type

The match type configuration tells the OpenNMS WMI system how you want to cope with multiple instance results. Available match types are:

  • all - all instances must comply to the compare operation.
  • none - no instances should comply with the compare operation.
  • some - only some (1 or more) must comply with the compare operation.
  • one - only one instance can comply with the compare operation.

The WMI Manager

The WMI Manager system is at the core of the WMI polling plugins. It embodies the logic of taking parameters, retrieving them, and then comparing them to appropriate values to determine whether the service is available. The WMI manager requires a certain amount of information before it can appropriately do its job. You will need to provide it a domain name, a user name, a password, a match type, a compare operation, a compare value and finally WMI target information. You can provide it target information in the form of a WMI Class name and a WMI Object name (at which point it will assume you want to do an InstanceOf) or you can provide it a WQL string and a WMI Object name (at which point it will assume that you want to do an ExecQuery.)

WMI Configuration

Before beginning to use the WMI plugin you will need to configure it appropriate by editing the wmi-config.xml and providing it with information about your Windows environment. WMI will require a domain administrator, a local administrator or a user with the capability of remote registry and DCOM component access. The Remote Registry service must also be enabled. The J-Interop (the supporting library that made WMI possible within OpenNMS) documentation has some suggestions on properly enabling WMI access: J-Interop Remote DCOM FAQ.

You will have to configure the WMI configuration file which, if you're familiar with the SNMP equivalent, is very simple. Here is an example of what a configuration may look like: 

<?xml version="1.0"?>
<!-- The opening element contains the default user information -->
<wmi-config retry="2" timeout="1500"
        username="Administrator" domain="WORKGROUP" password="password">
    
    <!-- This definition shows how to specify a user for a range of IP addresses. -->
    <definition username="DomainUserA" domain="MYDOMAIN" password="unsecurepwd">
        <ns1:range xmlns:ns1="http://xmlns.opennms.org/xsd/types"
            begin="192.168.1.1" end="192.168.1.10"/>
    </definition>
    
    <!-- This definition shows how to specify a user for a specific IP address -->
    <definition  username="BobVilla" domain="MYMACHINENAME" password="buildahouse">
        <specific xmlns="">192.168.1.12</specific>
    </definition>        
</wmi-config>

WMI Capability Plugin

The OpenNMS WMI support provides two methods to work with WMI: InstanceOf or WQL. The path to use these isn't as explicit as they would be if you were using the WmiClient code directly as we'll configure this in the XML files. If you're using InstanceOf you will need to provide a WMI Class and a WMI Object. If you're configuring WQL you will need a WQL string as well as a WMI Object.

It is important to note that you must use the WQL configuration style if you want instance-specific granularity. If you simply provide the plugins with an object and class it will uniformly perform comparisons on all resulting instances.

capsd-configuration.xml - InstanceOf-style 

    <protocol-plugin protocol="WMI-BIOS-Status" class-name="org.opennms.netmgt.capsd.plugins.WmiPlugin" scan="on" user-defined="false">
        <property key="timeout" value="2000" />
        <property key="retry" value="1" />
        <property key="matchType" value="all"/>
        <property key="wmiClass" value="Win32_BIOS" />
        <property key="wmiObject" value="Status" />
        <property key="compareOp" value="EQ" />
        <property key="compareValue" value="OK" />
        <property key="service-name" value="WMI-BIOS-Status" />
    </protocol-plugin>

capsd-configuration.xml - WQL-style 

    <protocol-plugin protocol="WMI-Service-pgsql82" class-name="org.opennms.netmgt.capsd.plugins.WmiPlugin" scan="on" user-defined="false">
        <property key="timeout" value="2000" />
        <property key="retry" value="1" />
        <property key="matchType" value="all"/>
        <property key="wql" value="Select State From Win32_Service Where Name='pgsql-8.2'" />
        <property key="wmiObject" value="State" />
        <property key="compareOp" value="EQ" />
        <property key="compareValue" value="Running" />
        <property key="service-name" value="WMI-Service-pgsql82" />
    </protocol-plugin>

WMI Poller Monitor

The poller plugin is configured almost identically to the capability plugin. To skip to the chase here are two example configurations:

poller-configuration.xml - WQL style 

    <service name="WMI-Service-pgsql82" interval="300000" user-defined="false" status="on">
      <parameter key="retry" value="2" />
      <parameter key="timeout" value="3000" />
      <parameter key="matchType" value="all"/>
      <parameter key="wql" value="Select State From Win32_Service Where Name='pgsql-8.2'" />
      <parameter key="wmiObject" value="State" />
      <parameter key="compareOp" value="EQ" />
      <parameter key="compareValue" value="Running" />
      <parameter key="service-name" value="WMI-Service-pgsql82" />
    </service>
<!-- ... -->
<monitor service="WMI-Service-pgsql82" class-name="org.opennms.netmgt.poller.monitors.WmiMonitor" />


poller-configuration.xml - InstanceOf style 

    <service name="WMI-BIOS-Status" interval="300000" user-defined="false" status="on">
      <parameter key="retry" value="2" />
      <parameter key="timeout" value="3000" />
      <parameter key="matchType" value="all"/>
      <parameter key="wmiClass" value="Win32_BIOS" />
      <parameter key="wmiObject" value="Status" />
      <parameter key="compareOp" value="EQ" />
      <parameter key="compareValue" value="OK" />
      <parameter key="service-name" value="WMI-BIOS-Status" />
    </service>
<!-- ... -->
<monitor service="WMI-BIOS-Status" class-name="org.opennms.netmgt.poller.monitors.WmiMonitor" />

WMI Collector

The OpenNMS WMI collector is capable of both single and multi-instance collections. You will first need to enable the capability plugin and poller monitor to identify the WMI service by uncommenting the "WMI" service configurations. Next you will need to edit collectd-configuration.xml and change the WMI service's status from "off" to "on."

Once this step is complete you can restart OpenNMS and assuming you have your WMI configured correctly so that OpenNMS has users capable of speaking to your remote Windows hosts you will begin collecting WMI performance data as delivered stock.

However your next question is going to be "how do I collect xyz information?" Here you will be provided with an example of collecting some VMware Server performance metrics.

Background Information

This sample is assuming that you have a properly configured Windows XP or Windows 2003 machine with VMware Server installed and running. The interesting WMI Class in this example is Win32_PerfFormattedData_VMware_VMware. Upon inspecting this class with WMI Studio you will see that there are a handful of very interesting properties available:

  • Memory Information
    • GuestLockedMemoryBytes
    • GuestVirtualPhysicalMemoryBytes
  • Disk Information
    • VirtualDiskBytesReadPersec
    • VirtualDiskBytesTransferredPersec
    • VirtualDiskBytesWrittenPersec
    • VirtualDiskReadsPersec
    • VirtualDiskTransfersPersec
    • VirtualDiskWritesPersec
  • Network Information
    • NetworkBytesReceivedPersec
    • NetworkBytesSentPersec
    • NetworkBytesTransferredPersec
    • NetworkPacketsReceivedPersec
    • NetworkPacketsSentPersec
    • NetworkReceiveErrorsPersec
    • NetworkSendErrorsPersec
    • NetworkTransferErrorsPersec
    • NetworkTransfersPersec

Note that WMI Studio is a rather dated tool, it's an ActiveX plugin for Internet Explorer, and does not appear to work with IE8. A good modern alternative is to use Windows PowerShell and the Get-WmiObject command to explore the WMI tree and test sample counters.

A Word About Security

Server editions of Windows since Server 2003 are configured by default to require SMB signing, meaning the server will not negotiate cleartext exchange of password information. The Windows NT security model is challenging to understand and its implementation proprietary, so it's impossible to predict with certainty the security implications of using this functionality. Users are encouraged to perform their own security analysis.

One user whose security operations team performed an analysis of a packet capture taken during OpenNMS WMI data collection reports: 

The auth method is using NTLMv2. This behaves similarly to RADIUS auth. In this case,
the account UPN [User Principal Name] info can be decoded but the password is 
(one-way) hashed.
Retrieved from "http://www.opennms.org/wiki/WmiConfiguration"