Skip to main content
Virtualization & containers

Proxmox VE Health

Monitor VMs, containers, orphaned locks, storage, cluster quorum and snapshots of a Proxmox VE host locally, without credentials.

The Proxmox VE Health check monitors a Proxmox VE host: whether the VMs and containers that should run are running, whether guests are left with orphaned locks, how full storages are, whether the cluster has quorum, and how many snapshots exist and how old they are. It runs on Linux (x64) every 10 minutes by default, reads its data locally on the host and needs no credentials. The check does not change the host, its guests or the cluster.

Templates are not checked. The check does not cover backup history or guest tools; for backups, use Proxmox Backup Server.

Prerequisites

  • The octoja agent runs directly on the Proxmox VE host with root privileges. The check queries pvesh and reads guest configurations under /etc/pve.
  • You can assign checks to the device. Configuration packages require Monitoring Check Management.

Steps

  1. Open the host and add Proxmox VE Health under Checks. Use a configuration package for multiple hosts.
  2. Keep the sub-checks you need enabled and turn off the others.
  3. Under Guests that must run (IDs or exact names), enter guests that must always run even if Start at boot is not enabled in Proxmox. Enter guests the check should ignore under Excluded guests (IDs or exact names).
  4. Adjust the thresholds if needed and save.
  5. After the first run, open the result. It shows the number of guests and storages checked, whether the host is standalone or clustered, and every issue found.
  6. Configure alerting if needed.

In a cluster, assign the check to every node. It only checks guests and storages of the node it runs on.

Settings

FieldTypeRequiredDefaultDescription
Monitor guest stateToggleNoOnGuests with Start at boot enabled and listed guests must run on this node
Monitor orphaned locksToggleNoOnWarns about locked guests without a running task that holds the lock
Monitor storageToggleNoOnChecks the node's enabled storages for availability and usage
Monitor cluster and quorumToggleNoOnChecks quorum and the online state of all cluster nodes
Monitor snapshotsToggleNoOnChecks the snapshot count per guest and the age of each snapshot
Guests that must run (IDs or exact names)ListNoEmptyAdditional guests that must run; matching ignores case
Excluded guests (IDs or exact names)ListNoEmptyGuests the check ignores entirely; an exclusion takes precedence over Guests that must run
Storage warning: used (%)NumberNo80Usage at which a storage raises a warning
Storage critical: used (%)NumberNo95Usage at which a storage is critical; at most 100
Snapshot age warning (days)NumberNo7Age at which a snapshot raises a warning
Snapshot age critical (days)NumberNo30Age at which a snapshot is critical
Snapshot count warning per guestIntegerNo3Number of snapshots of a guest that raises a warning
Snapshot count critical per guestIntegerNo10Number of snapshots of a guest that is critical

Thresholds must be positive, and the warning value must not exceed the critical value. A value that exactly reaches a threshold counts as exceeding it. Thresholds of disabled sub-checks are not validated.

Results

ConditionResult
A guest with Start at boot or a listed guest is not runningCritical
A listed guest is missing on this nodeCritical
A guest is locked but no matching task is runningWarning
An enabled storage is unavailableCritical
Storage usage reaches the warning or critical thresholdWarning or Critical
A guest's snapshot count or a snapshot's age reaches the warning or critical thresholdWarning or Critical
Cluster without quorumCritical
Cluster node offlineCritical
Standalone host without a clusterOK
Invalid thresholdsError
Proxmox data cannot be read, for example without root privileges or on a host without Proxmox VEError

The suspended lock of a guest deliberately suspended to disk is not treated as orphaned. Running tasks such as backup, migration, snapshot or clone suppress the warning for the affected guest.

FAQ

Both check quorum and the online state of nodes. Proxmox Cluster & Quorum also checks Corosync links and the /etc/pve mount. If you run both checks on the same host, you can turn off Monitor cluster and quorum here so a cluster problem does not alert twice. Essential Proxmox services and HA are covered by Proxmox Services & HA.

The check only sees guests of the node it runs on. If the guest was migrated to another node, it is missing here. List guests that move between nodes only on the check of the node that should host them, or rely on Start at boot.