
= VmwareMonitor
:description: Learn how to configure and use the VmwareMonitor in OpenNMS {page-component-title} to test the power state of a virtual machine or host system.

This monitor is part of the VMWare integration that provisiond provides.
It tests the power state of a virtual machine or host system.
If the power state is `poweredOn`, the service is considered to be up; if it is `poweredOff`, the service is marked as down.
By default, a power state of `standBy` will also mark the service as down.

If you use https://www.vmware.com/content/dam/digitalmarketing/vmware/en/pdf/techpaper/Distributed-Power-Management-vSphere.pdf[Distributed Power Management] (automatic PDF download), you can change the `standBy` state (see the `ignoreStandBy` parameter).

Optionally, a service down event can be triggered if there are pending alarms in vCenter that have not been acknowledged or cleared.

== Import hosts

The VmwareMonitor requires that hosts be imported using provisiond and the VMware import function.
{page-component-title} requires network access to the VMWare vCenter server and each of the monitored hosts.

The credentials for accessing the status of a VMware entity are collected from the appropriate vCenter instance using settings from `$\{OPENNMS_HOME}/etc/vmware-config.xml`.

NOTE: Metadata expressions can also be used in the username and password attributes of the `vmware-config.xml` configuration file. 
This allows the user to also reference credentials stored in the secure credentials vault.

This file also sets specific asset fields to be assigned to imported virtual machines and host systems.

The VMware integration populates the following asset fields via provisiond:

* VMware Management Server
* VMware Managed Entity Type
* `foreignId` (which contains an internal VMware vCenter Identifier)

For more information, see xref:reference:/provisioning/handlers/vmware.adoc[].

== VmwareMonitor class

[caption=]
.VmwareMonitor class
[cols="1,3"]
|===
s| Class Name
| org.opennms.netmgt.poller.monitors.VmwareMonitor
|===

== Configuration and use

[caption=]
.Optional monitor-specific parameters
[options="autowidth"]
|===
| Parameter | Description | Default Value

| retry
| Number of retries before the service is marked as down.
| 0

| ignoreStandBy
| Treat the `standBy` power state as an indicator that a service is up.
| false

| reportAlarms
| Check for unacknowledged vSphere alarms for a comma-separated list of <<operation:deep-dive/events/event-configuration.adoc#severities, severities>> (red, yellow, green, gray).
| _Blank_
|===

This monitor implements the <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-common-parameters, common configuration parameters>>.

== Example

The following is an example of a `poller-configuration.xml` VmwareMonitor configuration.
With these settings, the monitor will go down if any unacknowledged vSphere alarms with either red or yellow severities exist for the managed entity:

Note that you must include the `monitor` section for each service in your definition.

[source, xml]
----
<service name="VMware-ManagedEntity" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="reportAlarms" value="red, yellow"/>
</service>

<monitor service="VMware-ManagedEntity" class-name="org.opennms.netmgt.poller.monitors.VmwareMonitor"/>
----
