# WsManCollector

The WsManCollector collects peformance metrics using the Web Services-Management (WS-Management) protocol.

Web Services-Management (WS-Management) is a DMTF open standard defining a SOAP-based protocol for the management of servers, devices, applications and various Web services. Windows Remote Management (WinRM) is the Microsoft implementation of WS-Management Protocol.

## Collector Facts

 Class Name `org.opennms.netmgt.collectd.WsManCollector` Package core Supported on Minion `Yes`

## Collector Parameters

Use these parameters in the collectd-configuration.xml file.

Table 1. Collector-specific parameters for the WsManCollector
Parameter Description Required Default value

`collection`

The name of the WS-Man Collection to use.

required

## WS-Management Setup

Before setting up Meridian to communicate with a WS-Management agent, you should confirm that it is properly configured and reachable from the Meridian system. If you need help enabling the WS-Management agent, consult the documentation from the manufacturer. Here are some resources that could help:

We suggest using the Openwsman command line client to validate authentication and connectivity. Packages are available for most distributions under `wsmancli`.

For example:

``wsman identify -h localhost -P 5985 -u wsman -p secret``

Once validated, add the agent-specific details to the Meridian configuration, defined in the next section.

### Troubleshooting and Commands

For troubleshooting there is a set of commands you can use in Powershell verified on Microsoft Windows Server 2012.

Enable WinRM in PowerShell
``Enable-PSRemoting``
Set up Firewall for WinRM over HTTP
``netsh advfirewall firewall add rule name="WinRM-HTTP" dir=in localport=5985 protocol=TCP action=allow``
Set up Firewall for WinRM over HTTPS
``netsh advfirewall firewall add rule name="WinRM-HTTPS" dir=in localport=5986 protocol=TCP action=allow``
Test WinRM on local Windows Server
`winrm id`
Show WinRM configuration on Windows Server
`winrm get winrm/config`
Show listener for configuration on Windows Server
`winrm e winrm/config/listener`
Test connectivity from a Linux system
``nc -z -w1 <windows-server-ip-or-host> 5985;echo $?``  Use BasicAuthentication just with WinRM over HTTPS with verifiable certificates in production environment. Enable BasicAuthentication ``````winrm set winrm/config/client/auth '@{Basic="true"}' winrm set winrm/config/service/auth '@{Basic="true"}' winrm set winrm/config/service '@{AllowUnencrypted="true"}'`````` ## WS-Management Agent Configuration  Understanding resource types helps when editing collector-specific configuration files. The agent-specific configuration details are maintained in `etc/wsman-config.xml`. This file has a similar structure as `etc/snmp-config.xml`, which the reader may already be familiar with. This file is consulted when a connection to a WS-Man Agent is made. If the IP address of the agent is matched by the `range`, `specific` or `ip-match` elements of a definition, then the attributes on that definition are used to connect to the agent. Otherwise, the attributes on the outer `wsman-config` definition are used. This `etc/wsman-config.xml` files automatically reload when modified. Here is an example with several definitions: ``````<?xml version="1.0"?> <wsman-config retry="3" timeout="1500" ssl="true" strict-ssl="false" path="/wsman"> <definition ssl="true" strict-ssl="false" path="/wsman" username="root" password="calvin" product-vendor="Dell" product-version="iDRAC 6"> <range begin="192.168.1.1" end="192.168.1.10"/> </definition> <definition ssl="false" port="5985" path="/wsman" username="Administrator" password="P@ssword"> <ip-match>172.23.1-4.1-255</ip-match> <specific>172.23.1.105</specific> </definition> </wsman-config>`````` Table 2. Collector configuration attributes Attribute Description Default `timeout` HTTP Connection and response timeout in milliseconds. HTTP client default `retry` Number of retries on connection failure. `0` `username` Username for basic authentication. none `password` Password used for basic authentication. none `port` HTTP/S port Default for protocol `max-elements` Maximum number of elements to retrieve in a single request. no limit `ssl` Enable SSL `False` `strict-ssl` Enforce SSL certificate verification. `True` `path` Path in the URL to the WS-Management service. `/` `product-vendor` Used to overwrite the detected product vendor. none `product-version` Used to overwrite the detected product version. none `gss-auth` Enables GSS authentication. When enabled a reverse lookup is performed on the target IP address in order to determine the canonical host name. `False`  If you try to connect against Microsoft Windows Server make sure to set specific ports for WinRM connections. By default Microsoft Windows Server uses port `TCP/5985` for plain text and port `TCP/5986` for SSL connections. ## WS-Management Collection Configuration Configuration for the WS-Management collector is stored in `etc/wsman-datacollection-config.xml` and `etc/wsman-datacollection.d/*.xml`.  The contents of these files are automatically merged and reloaded when changed. The `default` WS-Management collection looks as follows: ``````<?xml version="1.0"?> <wsman-datacollection-config rrd-repository="${install.share.dir}/rrd/snmp/">
<collection name="default">
<rrd step="300">
<rra>RRA:AVERAGE:0.5:1:2016</rra>
<rra>RRA:AVERAGE:0.5:12:1488</rra>
<rra>RRA:AVERAGE:0.5:288:366</rra>
<rra>RRA:MAX:0.5:288:366</rra>
<rra>RRA:MIN:0.5:288:366</rra>
</rrd>

<!--
Include all of the available system definitions
-->
<include-all-system-definitions/>
</collection>
</wsman-datacollection-config>``````

The magic happens with the `<include-all-system-definitions/>` element which automatically includes all of the system definitions into the collection group.

 If required, you can include a specific system-definition with `sys-def-name`.

System definitions and related groups can be defined in the root `etc/wsman-datacollection-config.xml` file, but it is preferred that be added to a device specific configuration files in `etc/wsman-datacollection-config.d/*.xml`.

 Avoid modifying any of the distribution configuration files and create new ones to store you specific details instead.

Here is an example configuration file for a Dell iDRAC:

``````<?xml version="1.0"?>
<wsman-datacollection-config>
<group name="drac-system"
resource-uri="http://schemas.dell.com/wbem/wscim/1/cim-schema/2/root/dcim/DCIM_ComputerSystem"
resource-type="node">
<attrib name="OtherIdentifyingInfo" index-of="#IdentifyingDescriptions matches '.*ServiceTag'" alias="serviceTag" type="String"/>
</group>

<group name="drac-power-supply"
resource-uri="http://schemas.dmtf.org/wbem/wscim/1/*"
dialect="http://schemas.microsoft.com/wbem/wsman/1/WQL"
filter="select InputVoltage,InstanceID,PrimaryStatus,SerialNumber,TotalOutputPower from DCIM_PowerSupplyView where DetailedState != 'Absent'"
resource-type="dracPowerSupplyIndex">
<attrib name="InputVoltage" alias="inputVoltage" type="Gauge"/>
<attrib name="InstanceID" alias="instanceId" type="String"/>
<attrib name="PrimaryStatus" alias="primaryStatus" type="Gauge"/>
<attrib name="SerialNumber" alias="serialNumber" type="String"/>
<attrib name="TotalOutputPower" alias="totalOutputPower" type="Gauge"/>
</group>

<system-definition name="Dell iDRAC (All Version)">
<rule>#productVendor matches '^Dell.*' and #productVersion matches '.*iDRAC.*'</rule>
<include-group>drac-system</include-group>
<include-group>drac-power-supply</include-group>
</system-definition>
</wsman-datacollection-config>``````

### System Definitions

Rules in the system definition are written using SpEL expressions.

The expression has access to the following variables in its evaluation context:

Name Type

(root)

org.opennms.netmgt.model.OnmsNode

agent

org.opennms.netmgt.collection.api.CollectionAgent

productVendor

java.lang.String

productVersion

java.lang.String

If a particular agent is matched by any of the rules, then the collector will attempt to collect the referenced groups from the agent.

### Group Definitions

Groups are retrieved by issuing an Enumerate command against a particular `Resource URI` and parsing the results. The Enumerate commands can include an optional `filter` in order to filter the records and attributes that are returned.

 When configuring a filter, you must also specify the dialect.

The resource type used by the group must of be of type `node` or a generic resource type. Interface level resources are not supported.

When using a generic resource type, the `IndexStorageStrategy` cannot be used since records have no implicit index. Instead, you must use an alternative such as the `SiblingColumnStorageStrategy`.

If a record includes a multi-valued key, you can collect the value at a specific index with an `index-of` expression. This is best demonstrated with an example. Let`s assume we wanted to collect the `ServiceTag` from the following record:

``````<IdentifyingDescriptions>CIM:GUID</IdentifyingDescriptions>
<IdentifyingDescriptions>CIM:Tag</IdentifyingDescriptions>
<IdentifyingDescriptions>DCIM:ServiceTag</IdentifyingDescriptions>
<OtherIdentifyingInfo>45454C4C-3700-104A-8052-C3C01BB25031</OtherIdentifyingInfo>
<OtherIdentifyingInfo>mainsystemchassis</OtherIdentifyingInfo>
<OtherIdentifyingInfo>C8BBBP1</OtherIdentifyingInfo>``````

Specifying, the attribute name `OtherIdentifyingInfo` would not be sufficient, since there are multiple values for that key. Instead, we want to retrieve the value for the `OtherIdentifyingInfo` key at the same index where `IdentifyingDescriptions` is set to `DCIM:ServiceTag`.

This can be achieved using the following attribute definition:

``<attrib name="OtherIdentifyingInfo" index-of="#IdentifyingDescriptions matches '.*ServiceTag'" alias="serviceTag" type="String"/>``

### Special Attributes

A group can contain the placeholder attribute `ElementCount` that, during collection, will be populated with the total number of results returned for that group. This can be used to threshold on the number results returned by an enumeration.

``````    <group name="Event-1234"
resource-uri="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/*"
dialect="http://schemas.microsoft.com/wbem/wsman/1/WQL"
filter="select * from Win32_NTLogEvent where LogFile = 'Some-Application-Specific-Logfile/Operational' AND EventCode = '1234'"
resource-type="node">
<attrib name="##ElementCount##" alias="elementCount" type="Gauge"/>
</group>``````