Check PVE

Icinga check command for Proxmox VE via API


Icinga check command for Proxmox VE via API



This check command depends on the following python modules:

  • enum
  • requests
  • argparse

Installation on Debian / Ubuntu

apt install python-enum34 python-requests

Installation on Redhat 6 / CentOS 6

yum install python-argparse python-enum34 python34-requests

Installation on Redhat 7 / CentOS 7

yum install python-enum34 python-requests

Installation on FreeBSD

pkg install py36-requests

Create a API user in Proxmox VE

Create a role named Monitoring and assign neccesarry privileges:

pveum roleadd Monitoring
pveum rolemod Monitoring --privs Sys.Modify,VM.Monitor,Sys.Audit,Datastore.Audit,VM.Audit

Create a user named monitoring and set password:

pveum useradd monitoring@pve --comment "The ICINGA 2 monitoring user"
pveum passwd monitoring@pve

Assign monitoring role to user monitoring

pveum aclmod / -user monitoring@pve -role Monitoring

For further information about the Proxmox VE privilege system have a look into the documentation.


The icinga2 folder contains the command defintion and service examples for use with Icinga2.

usage: [-h] -e API_ENDPOINT -u API_USER -p API_PASSWORD [-k] -m
                    [-n NODE] [--name NAME] [--vmid VMID]
                    [--expected-vm-status {running,stopped,paused}]
                    [--ignore-vm-status] [--ignore-service NAME]
                    [--ignore-disk NAME] [-w TRESHOLD_WARNING]
                    [-c TRESHOLD_CRITICAL] [-M] [-V MIN_VERSION]

Check command for PVE hosts via API

optional arguments:
  -h, --help            show this help message and exit

API Options:
  -e API_ENDPOINT, --api-endpoint API_ENDPOINT
                        PVE api endpoint hostname
  -u API_USER, --username API_USER
                        PVE api user (e.g. icinga2@pve or icinga2@pam,
                        depending on which backend you have chosen in proxmox)
                        PVE api user password
  -k, --insecure        Don't verify HTTPS certificate

Check Options:
  -m {cluster,version,cpu,memory,storage,io_wait,updates,services,subscription,vm,vm_status,replication,disk-health}, --mode {cluster,version,cpu,memory,storage,io_wait,updates,services,subscription,vm,vm_status,replication,disk-health}
                        Mode to use.
  -n NODE, --node NODE  Node to check (necessary for all modes except cluster
                        and version)
  --name NAME           Name of storage or vm
  --vmid VMID           ID of virtual machine or container
  --expected-vm-status {running,stopped,paused}
                        Expected VM status
  --ignore-vm-status    Ignore VM status in checks
  --ignore-service NAME
                        Ignore service NAME in checks
  --ignore-disk NAME    Ignore disk NAME in health check
                        Warning treshold for check value
                        Critical treshold for check value
  -M                    Values are shown in MB (if available). Tresholds are
                        also treated as MB values
  -V MIN_VERSION, --min-version MIN_VERSION
                        The minimal pve version to check for. Any version
                        lower than this will return CRITICAL.


Check cluster health

./ -u  -p  -e  -m cluster
OK - Cluster 'proxmox1' is healthy'

Check PVE version

./ -u  -p  -e  -m version -V 5.0.0
OK - Your pve instance version '5.2' (0fcd7879) is up to date

Check CPU load

./ -u  -p  -e  -m cpu -n node1
OK - CPU usage is 2.4%|usage=2.4%;;

Check memory usage

./ -u  -p  -e  -m memory -n node1
OK - Memory usage is 37.44%|usage=37.44%;; used=96544.72MB;;;257867.91

Check disk-health

./ -u  -p  -e  -m disk-health -n node1
OK - All disks are healthy|wearout_sdb=96%;; wearout_sdc=96%;; wearout_sdd=96%;; wearout_sde=96%;;

Check storage usage

./ -u  -p  -e  -m storage -n node1 --name local
OK - Storage usage is 54.23%|usage=54.23%;; used=128513.11MB;;;236980.36

./ -u  -p  -e  -m storage -n node1 --name vms-disx
CRITICAL - Storage 'vms-disx' doesn't exist on node 'node01'

Check subscription status

./ -u  -p  -e  -m subscription -n node1 -w 50 -c 10
OK - Subscription of level 'Community' is valid until 2019-01-09

Check VM status

Without specifying a node name:

./ -u  -p  -e  -m vm --name test-vm
OK - VM 'test-vm' is running on 'node1'|cpu=1.85%;; memory=8.33%;;

With memory thresholds:

./ -u  -p  -e  -m vm --name test-vm -w 50 -c 80
OK - VM 'test-vm' is running on 'node1'|cpu=1.85%;; memory=40.33%;50.0;80.0

With a specified node name, the check plugin verifies on which node the VM runs.

./ -u  -p  -e  -m vm -n node1 --name test-vm
OK - VM 'test-vm' is running on node 'node1'|cpu=1.85%;; memory=8.33%;;

./ -u  -p  -e  -m vm -n node1 --name test-vm
WARNING - VM 'test-vm' is running on node 'node2' instead of 'node1'|cpu=1.85%;; memory=8.33%;;

If you only want to gather metrics and don't care about the vm status add the --ignore-vm-status flag:

./ -u  -p  -e  -m vm --name test-vm --ignore-vm-status
OK - VM 'test-vm' is not running

Specify the expected VM status:

./ -u  -p  -e  -m vm --name test-vm --expected-vm-status stopped
OK - VM 'test-vm' is not running

For hostalive checks without gathering performance data use vm_status instead of vm. The parameters are the same as with vm.

Check storage replication status

./ -u  -p  -e  -m replication -n node1
OK - No failed replication jobs on node1


Could not connect to PVE API: Failed to resolve hostname

Verify that your DNS server is working and can resolve your hostname. If everything is fine check for proxyserver environment variables (HTTP_PROXY,HTTPS_PROXY), which maybe not allow communication to port 8006.