WmiConfiguration

From OpenNMS
Jump to navigation Jump to search

Contents

OpenNMS WMI Support

OpenNMS includes the ability to monitor Windows systems using WMI (Windows Management Instrumentation). WMI offers many more monitoring data points on a Windows system than the Microsoft SNMP agent does. Also, WMI allows for agent-less data collection from Windows systems as WMI is a native monitoring technology included by default.

Once WMI has been enabled, OpenNMS will collect and graph a variety of memory, disk, CPU, network and other system information from monitored Windows systems.

Prerequisites

The most challenging part of enabling WMI in OpenNMS is configuring Windows systems to allow OpenNMS to remotely query WMI information from them. The steps below outline how to perform this, both for manual one-off configurations and for automated network-wide configuration.

Create an account for WMI polling

The first step is to create a privileged account OpenNMS will use to query WMI information. The following user details are suggested values.

  • Create a domain account (e.g. "monitor") and place this account in the "Domain Admins" security group
    • Name: OpenNMS Monitor
    • Logon name: monitor
    • User cannot change password: Enabled
    • Password never expires: Enabled
    • Description: "account used by OpenNMS to gather WMI statistics (domain admin account)"
    • Member of: Domain Users, Domain Admins

Alternatively to being a domain administrator, the account can be a local administrator on the desired servers to be monitored or be a user with the capability of remote registry and DCOM component access.

Configure the Windows Firewall to allow incoming WMI traffic

By default, the Windows firewall will block WMI access. This needs to be changed to allow OpenNMS to query WMI data.

Automated firewall configuration using Group Policy (recommended approach)

The following group policy enables incoming WMI queries on the domain network profile (normal Windows authentication rules still apply) using the pre-built firewall rules for this, as well as allows network traffic from dllhost.exe, which is needed specifically by OpenNMS when it does WMI queries.

This policy is only supported by Windows 2008 or later.

  • Policy name: "Computer Config - Windows Firewall (allow incoming WMI traffic from OpenNMS) (Windows Server 2008 and later)"
  • Minimum client version: Windows Vista/Windows Server 2008
  • Computer Configuration > Policies > Windows Settings > Security Settings
    • Windows Firewall with Advanced Security > Windows Firewall with Advanced Security - LDAP...
      • Inbound Rules, New Rule...
      • Rule Type: Predefined
        • select "Windows Management Instrumentation (WMI)"
        • Next
      • Which rules would you like to create?
        • enable all three displayed WMI rules (the default)
        • Next
      • Action
        • leave "Allow the connection" selected
        • Finish

By default, the rules are enabled for all network profiles. To enhance security, edit each rule to only enable it for the "Domain" network profile.

  • Computer Configuration > Policies > Windows Settings > Security Settings
    • Windows Firewall with Advanced Security > Windows Firewall with Advanced Security - LDAP...
      • Inbound Rules
        • rule "Windows Management Instrumentation (ASync-In)" > Properties
          • Advanced tab
            • Profiles area > uncheck "Private" and "Public" so only "Domain" is left enabled
            • OK
        • rule "Windows Management Instrumentation (DCOM-In)" > Properties
          • Advanced tab
            • Profiles area > uncheck "Private" and "Public" so only "Domain" is left enabled
            • OK
        • rule "Windows Management Instrumentation (WMI-In)" > Properties
          • Advanced tab
            • Profiles area > uncheck "Private" and "Public" so only "Domain" is left enabled
            • OK

This additional rule was also needed to get remote WMI connections to work only from OpenNMS and the J-Interop Remote DCOM library it uses -- dllhost.exe (aka "COM Surrogate") is launched automatically on the WMI connection in the security context of the user used to make the WMI connection and has listening ports of its own that need to be network accessible; it closes automatically after the WMI call is complete. This rule is not necessarily needed for WMI access from other programs and should be evaluated on a case-by-case basis.

  • Computer Configuration > Policies > Windows Settings > Security Settings
    • Windows Firewall with Advanced Security > Windows Firewall with Advanced Security - LDAP...
      • Inbound Rules, New Rule...
        • Rule Type
          • select "Program"
          • Next
        • Program
          • This program path: enter "%SystemRoot%\system32\dllhost.exe" (without the quotes)
          • Next
        • Action
          • select "Allow the connection"
          • Next
        • Profile
          • uncheck "Private" and "Public" to leave only "Domain" selected
          • Next
        • Name
          • Name: "Custom - Allow connections to dllhost.exe for WMI incoming traffic from OpenNMS"
          • Description: (leave blank, or enter as desired)
        • Finish

Apply this group policy to the desired Active Directory organizational unit containing systems to monitor.

Manual firewall configuration

The following firewall rules can be manually enabled if the group policy approach is not used.

Start the "Windows Firewall" control panel applet

  • Click "Allow a program or feature through Windows Firewall"
  • Locate the rule set "Windows Management Instrumentation (WMI)" and then enable this rule in just the "Domain" profile by clicking the "Domain" box and then clicking OK
  • Click OK to close "Windows Firewall"

For reference, the following specific ports are opened:

  • Windows Management Instrumentation (ASync-In): TCP in on any port and only for listening sockets created by the program "%systemroot%\system32\wbem\unsecapp.exe"
  • Windows Management Instrumentation (DCOM-In): TCP in on port 135 and only for listening sockets created by the program "%SystemRoot%\system32\svchost.exe" and for the service "Remote Procedure Call (RPC)"
  • Windows Management Instrumentation (WMI-In): TCP in on any port and only for listening sockets created by the program "%SystemRoot%\system32\svchost.exe" and for the service "Windows Management Instrumentation"

The same change can be made from the command line. Run the commands below from an elevated command prompt.

REM enable the pre-existing domain profile firewall rules to allowing incoming WMI traffic
netsh advfirewall firewall set rule name="Windows Management Instrumentation (ASync-In)" profile=domain new enable=yes profile=domain
netsh advfirewall firewall set rule name="Windows Management Instrumentation (DCOM-In)" profile=domain new enable=yes profile=domain
netsh advfirewall firewall set rule name="Windows Management Instrumentation (WMI-In)" profile=domain new enable=yes profile=domain

And also one additional firewall rule needs to be created to get remote WMI connections to work from OpenNMS and the J-Interop Remote DCOM library it uses (see above for more).

Run the command below from an elevated command prompt.

netsh advfirewall firewall add rule name="Custom - Allow connections to dllhost.exe for WMI incoming traffic" dir=in protocol=TCP program="%SystemRoot%\system32\dllhost.exe" profile=domain localport=any action=allow

Registry key permissions change (Windows Server 2008 R2 or later, or Windows 7 or later only)

With Windows Server 2008 R2, Server 2012 R1 and R2, and Windows 7 (and presumably Windows 8), the default owner of the following registry key (for the "WBEM Scripting Locator" registry branch) needs to be changed from "TrustedInstaller" to the local machine "Administrators" group for OpenNMS to successfully query WMI.

Automated configuration using SetACL and a scheduled task (recommended approach)

A group policy preference can be used to centrally create a scheduled task that uses the SetACL utility to perform the necessary registry permission change on all desired servers.

Download and deploy SetACL

This is a command-line tool to set file and registry permissions. The license is "freeware".

  • Download the current version of the .exe version from http://helgeklein.com/download/
  • Extract the zip file and copy the x86 (32-bit) and x64 binaries to a centrally-accessible network share

For example, the following will copy the files to the NETLOGON share

  • Run from an elevated command prompt
mkdir "\\%USERDNSDOMAIN%\netlogon\SetACL"

copy "SetACL (executable version)\32 bit\SetACL.exe" "\\%USERDNSDOMAIN%\netlogon\SetACL\SetACLx86.exe"
copy "SetACL (executable version)\64 bit\SetACL.exe" "\\%USERDNSDOMAIN%\netlogon\SetACL\SetACLx64.exe"

The files need to readable by computer machine accounts as Group Policy runs under the local machine account. By default, the NETLOGON share provides read/read & execute access to the "Authenticated Users" group, which includes all machine accounts, so no special permissions need to be applied in this case.

Configure the group policy preference

Now create a group policy preference that creates a scheduled task to run the SetACL (64-bit or 32-bit version as appropriate) to set registry permissions to allow remote WMI calls from OpenNMS. It is only needed on Windows Server 2008 R2 or later or Windows 7 or later as it was in these versions that default permissions changed on the needed key.

  • Name: "Computer Config Pref - Scheduled Task (run SetACL.exe to set registry permissions to allow WMI access for OpenNMS)"

The first scheduled task is for 64-bit Windows systems.

  • Computer Configuration > Preferences > Control Panel Settings > Scheduled Tasks
    • right-click on Scheduled Tasks > New > Scheduled Task (Windows Vista and later)
      • General
        • Action: Update
        • Name: "Computer Config Pref - Scheduled Task (run SetACL.exe to set registry permissions to allow WMI access for OpenNMS) (64-bit Windows version)"
        • Description: "Run SetACL.exe to set registry permissions to allow WMI access for OpenNMS (only needed for Windows Server 2008 R2 or later, or Windows 7 or later) (64-bit Windows version)"
        • Security options:
          • When running the task, use the following user account: NT AUTHORITY\System
          • Do not enter any password for this user (just cancel the password prompt dialog box)
          • Run whether user is logged on or not: Enabled
          • Run with highest privileges: Enabled
        • Configure for: Windows 7 (which is also correct for Windows Server 2008 R2 systems -- leave at the 2008 level if 2008 R1 servers are to be monitored)
      • Triggers
        • New...
          • Begin the task: On a schedule
          • Settings: Daily
          • Start: 7:00:00 AM
          • Stop task if it runs longer than: 30 minutes
          • Enabled: enabled
          • OK
      • Actions
        • New...
          • Action: Start a program
          • Program/script:
            \\%USERDOMAIN%\netlogon\SetACL\SetACLx64.exe
            (note: %USERDNSDOMAIN% is not defined for the Local System account, only %USERDOMAIN%)
          • Add arguments(optional):
            -ot reg -on HKEY_CLASSES_ROOT\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6} -actn setowner -ownr "n:Administrators"
          • OK
        • New...
          • Action: Start a program
          • Program/script:
            \\%USERDOMAIN%\netlogon\SetACL\SetACLx64.exe
          • Add arguments(optional):
            -ot reg -on HKEY_CLASSES_ROOT\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6} -actn ace -ace "n:Administrators;p:full"
          • OK
      • Settings
        • Allow the task to be run on demand: Enabled (to allow the job to be run manually to test it)
      • Common
        • Stop processing items on this extension if an error occurs on this item: No
        • Run in logged-on user's security context (user policy option): No (we need this task to run under the SYSTEM user account)
        • Remove this item when it is no longer applied: No
        • Apply once and do not reapply: No
        • Item-level targeting: Yes
          • Targeting...
          • New Item > Operating System
            • Product: Windows Server 2008 R2
          • New Item > Operating System
            • Product: Windows Server 2012 Family
            • right-click the item > Item Options > Or
          • Add Collection
            • right-click the collection > Add Collection
              • right-click the sub-collection > Add Targeting Item > Operating System
                • Product: Windows 7
              • right-click the sub-collection > Add Targeting Item > Operating System
                • Product: Windows 8
              • right-click the "Windows 8" item > Item Options > Or
          • right-click the top-level collection > Add Targeting Item > WMI Query
            • Query: Select * from Win32_Processor where AddressWidth = '64'
            • Namespace: Root\cimv2
            • Property: (leave blank)
            • (Note: the WMI Query defaults to "AND" as desired)
          • right-click the top-level collection object itself > Item Options > Or
          • OK
        • Description: "Run SetACL.exe to set registry permissions to allow WMI access for OpenNMS (only needed for Windows Server 2008 R2 or later, or Windows 7 or later) (64-bit Windows version)"
        • OK

Edit the same group policy preference to add a second scheduled task for 32-bit Windows systems.

  • Computer Configuration > Preferences > Control Panel Settings > Scheduled Tasks
    • right-click on Scheduled Tasks > New > Scheduled Task (Windows Vista and later)
      • General
        • Action: Update
        • Name: "Computer Config Pref - Scheduled Task (run SetACL.exe to set registry permissions to allow WMI access for OpenNMS) (32-bit Windows version)"
        • Description: "Run SetACL.exe to set registry permissions to allow WMI access for OpenNMS (only needed for Windows 7 or later) (32-bit Windows version)"
        • Security options:
          • When running the task, use the following user account: NT AUTHORITY\System
          • Do not enter any password for this user (just cancel the password prompt dialog box)
          • Run whether user is logged on or not: Enabled
          • Run with highest privileges: Enabled
        • Configure for: Windows 7
      • Triggers
        • New...
          • Begin the task: On a schedule
          • Settings: Daily
          • Start: 7:00:00 AM
          • Stop task if it runs longer than: 30 minutes
          • Enabled: enabled
          • OK
      • Actions
        • New...
          • Action: Start a program
          • Program/script:
            \\%USERDOMAIN%\netlogon\SetACL\SetACLx86.exe
            (note: %USERDNSDOMAIN% is not defined for the Local System account, only %USERDOMAIN%)
          • Add arguments(optional):
            -ot reg -on HKEY_CLASSES_ROOT\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6} -actn setowner -ownr "n:Administrators"
          • OK
        • New...
          • Action: Start a program
          • Program/script:
            \\%USERDOMAIN%\netlogon\SetACL\SetACLx86.exe
          • Add arguments(optional):
            -ot reg -on HKEY_CLASSES_ROOT\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6} -actn ace -ace "n:Administrators;p:full"
          • OK
      • Settings
        • Allow the task to be run on demand: Enabled (to allow the job to be run manually to test it)
      • Common
        • Stop processing items on this extension if an error occurs on this item: No
        • Run in logged-on user's security context (user policy option): No (we need this task to run under the SYSTEM user account)
        • Remove this item when it is no longer applied: No
        • Apply once and do not reapply: No
        • Item-level targeting: Yes
          • Targeting...
          • Add Collection
            • right-click the collection > Add Collection
              • right-click the sub-collection > Add Targeting Item > Operating System
                • Product: Windows 7
              • right-click the sub-collection > Add Targeting Item > Operating System
                • Product: Windows 8
              • right-click the "Windows 8" item > Item Options > Or
          • right-click the top-level collection > Add Targeting Item > WMI Query
          • New Item > WMI Query
            • Query: Select * from Win32_Processor where AddressWidth = '32'
            • Namespace: Root\cimv2
            • Property: (leave blank)
            • (Note: the WMI Query and sub-collection boolean relationship defaults to "AND" as desired)
          • OK
        • Description: "Run SetACL.exe to set registry permissions to allow WMI access for OpenNMS (only needed for Windows 7 or later) (32-bit Windows version)"
      • OK

Deploy the group policy to an OU that contains the desired systems. Wait for the scheduled task to execute at the specified time.

Manual registry permission configuration using regedit

Launch "regedit.exe" using elevated permissions ("Run as Administrator")

  1. Find the following registry key: "HKEY_CLASSES_ROOT\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}" (this is the CLSID for "WBEM Scripting Locator")

First, take ownership of the key to be able to change permissions.

  1. Right-click the key and select "Permissions"
  2. Click the "Advanced" button
  3. Select the tab labeled "Owner"
  4. Change the owner from "TrustedInstaller" to the local machine "Administrators" group (it is not necessarily to replace ownership on subcontainers and objects)
  5. Click the "OK" button

Now allow local administrators to have full control of this key.

  1. highlight the local machine "Administrators" group and allow "Full Control" for this key
  2. Click "OK"

Now change the owner back to the original owner.

  1. Again, click the 'Advanced' button.
  2. Again, select the tab labeled 'Owner'
  3. Click the button labeled 'Other users or groups'
  4. In the 'Enter the object name to select' text field, enter 'NT Service\TrustedInstaller'
  5. Click the button labeled 'Check Names' and verify that the principal name validates
  6. Click 'OK' (dismissing 'Select User or Group' dialog window)
  7. Click 'Apply'
  8. Click 'OK'

Close regedit.

The steps above are tested repeatable against Windows Server 2008 R2 Enterprise with SP1 on x86_64 platforms.

Enable the Remote Registry service

The Remote Registry service must also be enabled. This should be the case by default already.

Test WMI access

After performing the configuration above, test that WMI access works.

Test local WMI access

On a sample server, start PowerShell and test to ensure local access to WMI is working (the current logon credentials are used for authentication).

Get-WmiObject Win32_BIOS | fl Status
 or
Get-WmiObject -query "select Status from Win32_BIOS"

Test remote WMI access from another Windows system

Now, test with the designated "monitor" user from a remote Windows system using PowerShell to ensure that remote access to WMI is working using the "monitor" account. Enter the monitor account password when prompted.

Get-WmiObject -Credential monitor -ComputerName (remote-hostname) Win32_BIOS | fl Status

This is the expected result for all tests:

Status : OK

Test from the OpenNMS server using the CheckWmi utility

The checkwmi utility makes a useful tool for verifying that your credentials are correct and that WMI is configured correctly on the target node. Starting in OpenNMS 1.8.4, a convenient shell wrapper called checkwmi exists in the OPENNMS_HOME/bin directory. Here's a quick, basic example using that wrapper:

  • Example for Debian/Ubuntu systems
/usr/share/opennms/bin/checkwmi -matchType all -wmiClass Win32_BIOS \
  -wmiObject Status \
  -op EQ -value OK -domain domain_name target_ip_address username password

If everything is right, the output will look like this:

Checking:  for Status Op: EQ Val: OK
Check results: OK (1)
Result for (1) Win32_BIOS\Status: OK

Troubleshooting WMI access

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.

Also, this FAQ is very thorough in troubleshooting WMI issues on various versions of windows: [1].

If you encounter issue when connecting to Windows Server 2012, try running the winmgmt /resetrepository on the system.

Enter WMI access credentials in wmi-config.xml

Now configure OpenNMS to query WMI using the "monitor" account created earlier by editing the file wmi-config.xml. The syntax is very similar to the equivalent file for SNMP authentication configuration snmp-config.xml.

Different accounts can be specified for different IP ranges if desired. If doing this, you have to specify a definition for an IP range or a specific IP. Not specifying a definition does not imply scan everything automatically.

vi /etc/opennms/wmi-config.xml
<?xml version="1.0"?>
<!-- The opening element contains the default user information -->
<wmi-config retry="2" timeout="1500"
        username="monitor" domain="enter-domain-name" password="enter-account-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>

Warning: The account password is stored in plain text in the file. Ensure appropriate security controls over who can access this file.

Enable WMI data collection in collectd-configuration.xml

Now change the existing WMI status attribute from "off" to "on" to enable WMI. The following example also sets two retries and a longer (30 second) timeout. Some WMI values are slow to query (for example, asking for disk space statistics from a floppy disk drive device).

vi /etc/opennms/collectd-configuration.xml
...
    <package name="example1">
... 
        <!-- Customization: enable WMI data collection by changing the status attribute to "on" -->
        <service name="WMI" interval="300000" user-defined="false" status="on">
            <parameter key="collection" value="default"/>
            <parameter key="thresholding-enabled" value="true"/>
            <parameter key="retries" value="2"/>
            <parameter key="timeout" value="30000"/>
        </service>
...

Enable automatic discovery of WMI using capsd

Note: In OpenNMS 1.12.x, capsd is disabled by default. It needs to be uncommented in /etc/opennms/service-configuration.xml and have the value org.opennms.provisiond.enableDiscovery set to false in /etc/opennms/opennms.properties for capds to function as per below. If the node that should have WMI already exists in OpenNMS, it needs to be deleted and re-discovered by capsd as well.

Add this after the last existing "protocol-plugin" definition

vi /etc/opennms/capsd-configuration.xml
...

    <!-- Customization: enable automatic discovery WMI services -->
    <protocol-plugin protocol="WMI" 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_ComputerSystem" />
        <property key="wmiObject" value="Status" />
        <property key="compareOp" value="EQ" />
        <property key="compareValue" value="OK" />
        <property key="service-name" value="WMI" />
    </protocol-plugin>
...

Enable automatic discovery of WMI using provisiond

Provisiond is the default system for handling new node discovery in OpenNMS 1.12.x (instead of capsd).

  • TODO for how to discovery WMI with provisiond instead of capsd

Enable ongoing monitoring of already discovered WMI services in poller-configuration.xml

Add this after the last existing "service" definition in the "package" definition named "example1". The following example also sets two retries and a longer (30 second) timeout.

vi /etc/opennms/poller-configuration.xml
...

    <!-- Customization: enable monitoring that already discovered WMI services are still running -->
    <service name="WMI" interval="300000" user-defined="false" status="on">
      <parameter key="retry" value="2" />
      <parameter key="timeout" value="30000" />
      <parameter key="matchType" value="all"/>
      <parameter key="wmiClass" value="Win32_ComputerSystem" />
      <parameter key="wmiObject" value="Status" />
      <parameter key="compareOp" value="EQ" />
      <parameter key="compareValue" value="OK" />
      <parameter key="service-name" value="WMI" />
    </service>

Add this after the last existing "monitor" definition in the "poller-configuration" definition

vi /etc/opennms/poller-configuration.xml
...

  <!-- Customization: enable monitoring that already discovered WMI services are still running -->
  <monitor service="WMI" class-name="org.opennms.netmgt.poller.monitors.WmiMonitor" />

...

Increase WMI timeouts if needed

When monitoring WMI over low bandwidth or saturated network links, increasing timeouts is recommended. These are set in wmi-config.xml, collectd-configuration.xml, and poller-configuration.xml.

Enable WMI data thresholding in threshd-configuration.xml

If thresholding on WMI data is desired, set this up as follows.

Add this package definition to hold WMI-based threshold definitions after the last existing "package" element.

vi /etc/opennms/threshd-configuration.xml
...
        <!-- Customization: create a package for WMI-based threshold definitions -->
        <package name="wmi-thresholds">
                <filter>IPADDR != '0.0.0.0'</filter>
                <include-range begin="1.1.1.1" end="254.254.254.254"/>
                <include-range begin="::1" end="ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" />

                <service name="WMI" interval="300000" user-defined="false" status="on">
                        <parameter key="thresholding-group" value="wmi-thresholds"/>
                </service>
        </package>
...

A sample disk space threshold is given as an example.

vi /etc/opennms/thresholds.xml
...
    <!-- Customization: create a threshold group for WMI-based threshold definitions -->
    <group name="wmi-thresholds" rrdRepository="/var/lib/opennms/rrd/snmp/">
        <threshold
            description="Customization: Trigger an alert when the percentage of free disk space used on any disk reaches or goes below 10% for two measurement intervals (by default, five minutes each)"
            type="low" ds-type="wmiLogicalDisk" value="10.0"
            rearm="11.0" trigger="2" ds-label="wmiLDName"
            filterOperator="or" ds-name="wmiLDPctFreeSpace">
            <resource-filter field="wmiLDName">^\w\:$</resource-filter>
        </threshold>
    </group>
...

Restart OpenNMS

Restart OpenNMS for WMI changes to take place.

service opennms restart

WMI detection

To detect WMI on servers, manually force a rescan of each node or wait for automatic capability rescans that occur every 24 hours.

Verification

  • "WMI" should appear in the list of detected node services
  • The node's resource graphs should show a number of new graphs for collected WMI data

OpenNMS WMI reference material

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.

Namespace

Every WMI class exists in a namespace. The default namespace for most common classes is root/cimv2 (sometimes also written with more slashes or with slashes going the other way). From OpenNMS 1.12.2, it's possible to refer to WMI objects from other namespaces such as root/MicrosoftActiveDirectory as follows:

Capsd WmiPlugin and Provisiond WmiDetector 
Add a parameter called wmiNamespace below the protocol-plugin or detector parent element
Poller WmiMonitor 
Add a parameter called wmiNamespace below the service parent element
WmiCollector 
Add a wmiNamespace attribute to the wpm XML element

OpenNMS WMI architecture

The WMI Manager

The WMI Manager system is at the core of the WMI detector, poller, and collector classes. 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 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="wmiNamespace" value="root/cimv2"/> <!-- Requires OpenNMS 1.12.2 or newer -->
      <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="wmiNamespace" value="root/cimv2"/> <!-- Requires OpenNMS 1.12.2 or newer -->
      <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

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. You may also find additional information on the WMI Data Collection page.

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. WmiExplorer is a nice alternative based on PowerShell.

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.