VMware ESX vSphere

VMware ESX Server Profile (API)

This profile monitors an instance of the VMware ESX 3 or 4 virtualization software using the VMware vSphere API. The profile has been tested with version 4.0 of the API and ESX 3.5 and 4.0 hosts, and vCenter 4.0. The profile requires download and installation of the VMware SDK for Perl from VMware directly and then configuration of one or more users with at least read-level access to the metrics being polled. The Installation and Implementation Notes sections of this document describe these steps in more detail.

Services Configuration
  • Service - Definitions in Monarch are stored under this name.
  • Command Line - Service command name with arguments to be passed to the plugin.
  • Plugin Command Line - Plugin script called by Nagios for this Service.
  • Extended Info - The Extended Service Info definition, typically used for generating graphs.
    Command lines displayed below are intended to be single line commands.
    Service Command Line Plugin Command Line
    api_vsphere_cpu check_vsphere_cpu!50!80 /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib/apps/groundwork/check_vsphere_cpu.pl --credstore ~nagios/.vmware/credstore/vicredentials.xml --server $HOSTNAME$ --warning $ARG1$ --critical $ARG2$
    api_vsphere_datastore check_vsphere_datastore!10:99!5:100 /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib/apps/groundwork/check_vsphere_datastore.pl --credstore ~nagios/.vmware/credstore/vicredentials.xml --server $HOSTNAME$ --warning $ARG1$ --critical $ARG2$
    api_vsphere_memory check_vsphere_memory!75!90 /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib/apps/groundwork/check_vsphere_memory.pl --server $HOSTNAME$ --credstore ~nagios/.vmware/credstore/vicredentials.xml --warning $ARG1$ --critical $ARG2$
    api_vsphere_net check_vsphere_net!400000!600000 /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib/apps/groundwork/check_vsphere_net.pl --server $HOSTNAME$ --credstore ~nagios/.vmware/credstore/vicredentials.xml --warning $ARG1$ --critical $ARG2$
    api_vsphere_vms check_vsphere_vms!50!80 /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib/apps/groundwork/check_vsphere_vms.pl --server $HOSTNAME$ --credstore ~nagios/.vmware/credstore/vicredentials.xml --warning $ARG1$ --critical $ARG2$
Profile Package

This package includes the following files:

Profile Definitions

  • service-profile-api-vsphere-esx.xml
  • perfconfig-api-vsphere-esx.xml

Plugins Scripts (installed with the GroundWork Monitor product)

  • check_vsphere_cpu.pl
  • check_vsphere_datastore.pl
  • check_vsphere_memory.pl
  • check_vsphere_net.pl
  • check_vsphere_vms.pl
Installation

GroundWork Monitor includes many monitoring profiles for a variety of devices, systems and applications. Profiles already imported on a new GroundWork installation include Service Ping, SNMP Network, and SSH UNIX. The GroundWork Monitor Configuration tool is used to import updated profiles and profiles that require additional setup; the Profile XML file and its companion Performance Configuration definition file. Services can also be imported in addition to Service Profiles in the Profile Importer. The import process is documented under GROUNDWORK PROFILES > How to import profiles.

However, if you separately received this document along with the Profile Package contents described above then please following the following steps before proceeding further:

  1. Download the VMware vSphere SDK for Perl 4.0 from VMware, and follow the install instructions for Linux such that you unpack the SDK into /usr/local/groundwork/users/nagios on the GroundWork Monitor server. This will result in a directory called vmware-vsphere-cli-distrib under that Nagios directory.
  2. When you have completed the installation, recursively change the ownership of the vmware-vsphere-cli-distrib directory with a ‘chown --R nagios:nagios /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib’ command.
  3. Change to user nagios and enter the directory /usr/local/groundwork/users/nagios/vmware-vsphere-cli-distrib/apps. Make a directory called groundwork and transfer the five Plugin Scripts from the Profile Package inside that directory. These scripts are included with GroundWork Monitor 6.2 in a tar archive at /usr/local/groundwork/core/profiles/vmware_esx4_plugins.tar.gz. Make sure those scripts are executable by user nagios and have not been edited on a Microsoft Windows server. If the latter is true, after placing the scripts in the groundwork directory please run a dos2unix *.pl command from that groundwork directory.

There is an additional step of setting up credentials for using the plugins and the instructions for doing this are referenced in the Implementation Notes section.

The GroundWork Monitor Configuration tool is used to import profile definitions, even those that come with the product. You must import the profile supplied with this package, called service-profile-api-vsphere-host.xml.

If you received the plugin package from support, you must copy this file and the perfconfig-api-vsphere-host.xml file into the profiles directory and change their ownership to the nagios user, and then use the profile importer to import service-profile-api-vsphere-host.xml.

Implementation

This section contains detail settings used by this profile. These parameters can be altered with the Configuration tool.

Command Parameters

Command parameters are in the Configuration Services section with the following names and default values. Any bolded arguments MUST be set before this Service Profile will work properly.

api_vsphere_cpu

  • Returns the CPU usage as a percentage of the total of all CPU cores available on the ESX server.
  • $ARG1$ - Default is 50.  This is the warning threshold for the percentage of CPU core cycles used of the total available.
  • $ARG2$ - Default is 80.  This is the critical threshold for the percentage of CPU core cycles used of the total available.

api_vsphere_datastore

  • Returns a list of VMware datastore extents on the VMware ESX server and checks the amount of free space against the total amount available.
  • $ARG1$ - Default is 10:99.  This is the warning threshold for the storage FREE across all attached data extents as a percentage of the total available. If the space used is between 10 and 99 percent no warning; if below 10% or above 99% then a warning alert.
  • $ARG2$ - Default is 5:100.  This is the critical threshold for the storage FREE across all attached data extents as a percentage of the total available. If the space used is between 5 and 100 percent no alert; if below 5% or above 100% then a critical alert.

api_vsphere_memory

  • Returns the memory usage as a percentage of the total available on the ESX server.
  • $ARG1$ - Default is 75. This is the warning threshold for the amount of memory in use as a percentage of the maximum available.
  • $ARG2$ - Default is 90. This is the critical threshold for the amount of memory in use as a percentage of the maximum available.

api_vsphere_net

  • Returns the absolute kilobytes per second average network use across all network interfaces on the ESX server. Defaults are appropriate for Gigabit connection.
  • $ARG1$ - Default is 400000. This is the warning threshold for the traffic in Kilobits per second.
  • $ARG2$ - Default is 600000. This is the critical threshold for the traffic in Kilobits per second

api_vsphere_vms

  • Returns a list of VMware guest instances installed on the VMware ESX server and checks the number running against the total number.
  • $ARG1$ - Default is 50.  This is the warning threshold for the number of guests that need to be up as a percentage of the total number.
  • $ARG2$ - Default is 80.  This is the critical threshold for the number of guests that need to be up as a percentage of the total number.
Performance Graphing Parameters

The following parameters are used to generate performance charts. These parameters are set using the Configuration>Performance tool in GroundWork Monitor.

api_vsphere_cpu

  • Graphs the CPU utilization of the ESX server as a percentage.
  • The Nagios service description must match the string "api_vsphere_cpu".

api_vsphere_datastore

  • Graphs percentage free datastore space attached to the ESX server.
  • The Nagios service description must contain the string "api_vsphere_datastore".

api_vsphere_memory

  • Graphs memory used percentage on the ESX server.
  • The Nagios service description must match the string "api_vsphere_memory".

api_vsphere_net

  • Graphs all absolute KBps network usage average for all NICs on the server.
  • The Nagios service description must match the string "api_vsphere_net".

api_vsphere_vms

  • Graphs numbers of running, not running and total Guest VMs on the server
  • The Nagios service description must contain the string "api_vsphere_vms".
Implementation Notes

On the GroundWork server you must add credentials for the user that is authorized to access the ESX servers. User names and their passwords must be added to a credential store that the plugins have access to. The profile definitions are coded to locate this credential store in the standard location for a UNIX user on the GroundWork server (~/.vmware/credstore/vicredentials.xml). You do not have to create this file. You manage it by running a credential administration tool that comes with the SDK.

These are the commands:

~/vmware-vsphere-cli-distrib/apps/general/credstore_admin.pl add --server <servername> --username <username> --password <password>

~/vmware-vsphere-cli-distrib/apps/general/credstore_admin.pl remove --server <servername> --username <username> --password <password>

~/vmware-vsphere-cli-distrib/apps/general/credstore_admin.pl list

One such entry must exist for each ESX server to be polled. The plugins will use the first username it finds for the specified ESX server.

The provided plugins use the fully qualified domain name of the ESX server as supplied in the $HOSTADDRESS$ macro.  This is successful across ESX and ESXi servers. Using the short name of the server may not retrieve all data points requested, in particular the Network data from ESX.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.