VMWare Handler

The VMware adapter pulls hosts and/or virtual machines from a vCenter server into Meridian. With this adapter, nodes can automatically be added, updated, or removed from your Meridian based on the status of the VMware entity. The adapter also lets Meridian 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 Meridian 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 Meridian

Now that vCenter has been configured to allow access to read objects, it is time to set up Meridian 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-config>
    <vmware-server hostname="vcenter.mydomain.org" username="OpenNMS" password="secret"/>
</vmware-config>

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)
</requisition-def>
1 The name of the requisition to appear within Meridian.
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

importIPv4Only

Imports only IPv4 interfaces. Cannot be true if importIPv6Only is true.

false

importIPv6Only

Imports only IPv6 interfaces. Cannot be true if importIPv4Only is true.

false

topologyNetworks

Add the network information to the VMWare topology. If set to false, port group information will not be added to Meridian topology maps.

true

topologyDatastores

Add the datastores information to the VMWare topology.

true

topologyPortGroups

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

false

importVMPoweredOn

Defines if powered-on machines should be imported.

true

importVMPoweredOff

Defines if powered-off machines should be imported.

false

importVMSuspended

Defines if suspended machines should be imported.

false

importVMAll

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

false

importVMOnly

Imports only virtual machines and ignores hosts. Cannot be true if importHostOnly is true.

false

importHostPoweredOn

Defines if powered-on host systems should be imported.

true

importHostPoweredOff

Defines if powered-off host systems should be imported.

false

importHostStandBy

Defines if stand-by host systems should be imported.

false

importHostUnknown

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

false

importHostAll

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

false

importHostOnly

Imports only host systems and ignores VMs. Cannot be true if importVMOnly is true.

false

virtualMachineServices

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

VMware-ManagedEntity
VMware-VirtualMachine

hostSystemServices

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

VMware-ManagedEntity
VMware-HostSystem
VMwareCim-HostSystem

timeout

VMware connection timeout, in milliseconds.

3000

cimTimeout

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.

3000

When including multiple parameters in your import request, use a semicolon (;) for concatenation.

Examples for import-url-resource
vmware://vcenter.mydomain.org?importHostPoweredOff=true
vmware://172.16.123.100/vCenterImport?key=shouldImport;value=1
vmware://172.16.123.100/vCenterImport?_shouldImport=1
vmware://172.16.123.100/vCenterImport?_shouldImport=1;username=opennms;password=secret
vmware://[2001:db8:0:8d3:0:8a2e:70:7344]?virtualMachineServices=VM-SERVICE1,VM-SERVICE2
If you do not import powered-off or standby entities, they will be removed and re-added to Meridian 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"
    import-url-resource="vmware://<vcenter-host>/VCenterImport?key=OpenNMS-Import;value=yes">

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

<requisition-def import-name="vmware-requisition"
    import-url-resource="vmware://<vcenter-host>/VCenterImport?_OpenNMS-Import=yes">