VMWare Handler

The VMware adapter pulls hosts and/or virtual machines from a vCenter server into Horizon. With this adapter, nodes can automatically be added, updated, or removed from your Horizon based on the status of the VMware entity. The adapter also lets Horizon collect additional performance metrics directly from the VMware server based on stats stored by the hypervisor.

Preparing VMware credentials

To allow communication between OpenNMS and VMware, you must create a user and a role for authentication and permissions. You can either create a new local user within your vCenter server or use an account that has been defined in an external authentication system that is set up to access your vCenter instance.

Create a new vCenter role:
  1. Log into vCenter Server.

  2. Go to Home  Administration  Roles.

  3. Select the built-in "Read Only" role.

  4. Select the option to clone the role and name the new role "OpenNMS-Access" (or another name to your preference).

  5. Edit the new role to add the Host  CIM  CIM Interaction permission.

  6. Click OK to save the role.

Assign OpenNMS user permissions to access vCenter objects:
  1. Navigate to Home  Inventory  Hosts and Clusters within your vCenter.

  2. Right click on the container to apply the permission. If you want Horizon to import all entities, this would be the root vCenter level. To import only a subset of nodes, select a specific data center, cluster, or host.

  3. Select the Add Permission option from the right-click menu.

  4. Enter the name of the user account to use to connect to vCenter during the import process.

  5. Select the "OpenNMS-Access" role (or whatever you called it in the previous step).

  6. Save the role assignment and make sure to propagate to child objects, if prompted.

Provide credentials to Horizon

Now that vCenter has been configured to allow access to read objects, it is time to set up Horizon to be able to connect to vCenter. In the ${OPENNMS_HOME}/etc/vmware-config.xml file, add a line with the hostname, user, and password to connect to your vCenter server. If you have multiple vCenter servers, you can specify multiple <vmware-server /> objects in this file.

<?xml version="1.0"?>
    <vmware-server hostname="vcenter.mydomain.org" username="OpenNMS" password="secret"/>

Configure VMware requisition

The final step is to set up a requisition definition in ${OPENNMS_HOME}/etc/provisiond-configuration.xml. Use the vmware:// prefix to create a <requisition-def> object for the vCenter server.

<requisition-def import-name="vCenter" (1)
    import-url-resource="vmware://vcenter.mydomain.org"> (2)
    <cron-schedule>0 42 23 * * ? *</cron-schedule> (3)
1 The name of the requisition to appear within Horizon.
2 The hostname defined in the provisiond-configuration.xml must match the same case as the hostname entered in the vmware-config.xml.
3 The schedule of how frequently the import should rerun. In this example, the import runs every day at 23:42.

By default, all running hosts and virtual machines will be detected and added to the requisition. Change this behavior by adding additional parameters to the import-url-resource parameter in the requisition definition.

Do not forget to restart services after making changes to the provisiond-configuration.xml file.

Optional import parameters

Parameter Description Default


Imports only IPv4 interfaces.



Imports only IPv6 interfaces.



Add the network information to the VMWare topology.



Add the datastores information to the VMWare topology.



Add the port groups information (distributed virtual switches) to the VMWare topology.



Defines if powered-on machines should be imported.



Defines if powered-off machines should be imported.



Defines if suspended machines should be imported.



Imports all virtual machines and ignores importVMPoweredOn, importVMPoweredOff, and importVMSuspended parameters.



Imports only virtual machines and ignores hosts.



Defines if powered-on host systems should be imported.



Defines if powered-off host systems should be imported.



Defines if stand-by host systems should be imported.



Defines if host systems with an unknown power state should be imported.



Imports all host systems and ignores importHostPoweredOn, importHostPoweredOff, and importHostSuspended parameters.



Imports only host systems and ignores VMs.



Monitor services to assign to imported virtual machines. Multiple values should be comma separated.

VMware-ManagedEntity, VMware-VirtualMachine


Monitor services to assign to imported host systems. Multiple values should be comma separated.

VMware-ManagedEntity, VMware-HostSystem, VMwareCim-HostSystem


VMware connection timeout, in milliseconds.



Timeout, in milliseconds, used to test interface addresses for a reachable CIM service. Increase this value only if you have problems discovering CIM services on host systems.


importVMOnly and importHostOnly cannot both be true simultaneously.
importIPv4Only and importIPv6Only cannot both be true simultaneously.
If you do not import powered-off or standby entities, they will be removed and re-added to Horizon based on their power state. This can cause their database ID to change over time. Enabling the storeByForeignSource setting can help make sure collected metrics are kept properly.

Provision a subset of VMware entities

If you want to provision an arbitrary selection of VMware entities, you can specify a key-value pair to match objects that have a specific attribute in vCenter. The key to look up is a user-defined attribute for entities being imported. If the value provided starts with a ~, the value will be treated as a regular expression. Only one key-value pair can be specified per requisition.

<requisition-def import-name="vmware-requisition"

If you need to specify several attributes, use the _[customAttributeName] parameter

<requisition-def import-name="vmware-requisition"