Configure the VMware (ESXi / vCenter) Check

Set up the VMware check to monitor ESXi hosts and vCenter Server — host state, VM power states, and datastore usage.

Written By Stefan Steuer

Last updated 28 days ago

Configure a VMware (ESXi / vCenter) Check

The VMware check connects to an ESXi host or vCenter Server and reports the state of the virtualization infrastructure: host alerts, virtual-machine power states, and datastore capacity. octoja talks to vSphere directly via the vSphere SOAP API — no separate management agent on the ESXi/vCenter host is required. Point it at a standalone ESXi host for small sites, or at vCenter for multi-host clusters.

Requirements

An ESXi host or vCenter Server reachable over HTTPS from the octoja agent's network
The octoja agent installed on any device (Windows, macOS, or Linux) that can reach the vCenter / ESXi address — the host being monitored does not need an agent
A vSphere user with at least Read-only role on the inventory you want monitored

Use a dedicated read-only user. The check needs read access only. Create a user in vSphere (or use SSO) with the built-in Read-only role assigned at the level you want monitored — a single host, a cluster, or the whole inventory.

How it works

Each check run reads three things from the inventory:

Host alerts — hosts that are disconnected, not responding, or powered off
VM states — total VM count, count of running (powered-on) VMs, and any suspended VMs
Datastore usage — capacity, free space, and used percentage per datastore against your warning and critical thresholds

Each dimension can be turned on or off independently. The worst result across the active dimensions becomes the overall check status.

Steps

Make sure the octoja agent is installed on a device that can reach the vCenter / ESXi management address.
Go to Devices and open that device.
Click the Checks tab → Add Check → VMware (ESXi / vCenter).
Fill in the connection details:

Field	What to enter
Host	vCenter or ESXi hostname / IP without scheme, e.g. `vcenter.example.com`
Username	vSphere user (e.g. `administrator@vsphere.local` for vCenter, `root` for an ESXi host)
Password	Password for the vSphere user
Ignore SSL certificate errors	Leave on for typical vCenter / ESXi installations (self-signed certificates). Turn off only if you have replaced the certificate with one signed by a trusted CA

Choose which dimensions to monitor:

Field	What it does
Monitor host alerts	Flag hosts that are disconnected, not responding, or powered off
Monitor VM states	Count powered-on VMs and warn on suspended VMs
Monitor datastores (LUNs)	Check datastore capacity utilization

If datastore monitoring is on, adjust the thresholds:

Field	What it does
Datastore warning threshold (% used)	Warn when a datastore is at or above this percentage used (default: 80 %)
Datastore critical threshold (% used)	Critical when a datastore is at or above this percentage used (default: 90 %)

Click Add Check.

What triggers an alert?

Condition	Severity
Connection refused, hostname unreachable, or authentication failed	Failure
A host in the inventory is disconnected or not responding (host alerts on)	Critical
A host is powered off (host alerts on)	Warning
A host is in standby (host alerts on)	Warning
A host reports overall status red (host alerts on)	Critical
A host reports overall status yellow (host alerts on)	Warning
One or more VMs are suspended (VM states on)	Warning
Any datastore used percentage at or above the critical threshold (datastores on)	Critical
Any datastore used percentage at or above the warning threshold (datastores on)	Warning
A datastore is inaccessible (datastores on)	Critical
All active dimensions clean	OK

Tips

The check runs every 5 minutes by default — virtualization is the bottom of the stack, so prompt notification of an ESXi host going offline matters.
Point a single check at vCenter rather than at each ESXi host individually when you have a cluster. The check will see every host and every VM under that vCenter in one place.
For very large estates, run datastore monitoring on its own check (with VMs and hosts off) and a separate check for hosts and VMs. The thresholds apply per datastore, so you can tune storage alerting separately from host alerting.
If the check times out, the inventory may be too large to query within the check's 30-second limit. Grant the vSphere user read access only to the hosts, clusters, and datastores you actually want monitored — a smaller scope keeps queries fast.

After the first check interval, the result appears in the device's Checks tab with KPI tiles for VMs / datastores / alerts plus per-datastore usage bars.