{"id":23151629,"url":"https://github.com/nbuchwitz/check_pve","last_synced_at":"2025-04-05T13:06:57.920Z","repository":{"id":28241704,"uuid":"116843155","full_name":"nbuchwitz/check_pve","owner":"nbuchwitz","description":"Icinga check command for Proxmox VE via API","archived":false,"fork":false,"pushed_at":"2025-03-15T21:16:47.000Z","size":194,"stargazers_count":117,"open_issues_count":9,"forks_count":38,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-29T12:07:02.009Z","etag":null,"topics":["hacktoberfest","icinga2","monitoring","proxmox","proxmox-ve","pve"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nbuchwitz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-09T16:45:57.000Z","updated_at":"2025-03-15T21:16:19.000Z","dependencies_parsed_at":"2024-12-17T18:35:19.250Z","dependency_job_id":"9c26c388-7868-4c19-8bfb-baa979ea790d","html_url":"https://github.com/nbuchwitz/check_pve","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbuchwitz%2Fcheck_pve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbuchwitz%2Fcheck_pve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbuchwitz%2Fcheck_pve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbuchwitz%2Fcheck_pve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nbuchwitz","download_url":"https://codeload.github.com/nbuchwitz/check_pve/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339155,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","icinga2","monitoring","proxmox","proxmox-ve","pve"],"created_at":"2024-12-17T18:35:08.238Z","updated_at":"2025-04-05T13:06:57.887Z","avatar_url":"https://github.com/nbuchwitz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# check_pve\nIcinga check command for Proxmox VE via API\n\n![Linter](https://github.com/nbuchwitz/check_pve/actions/workflows/lint.yml/badge.svg)\n\n## Setup\n\n### Requirements\n\nThis check command depends on **Python 3** and the following modules:\n * requests\n * argparse\n * packaging\n\n**Installation on Debian / Ubuntu**\n```\napt install python3 python3-requests python3-packaging\n```\n\n**Installation on Rocky / Alma Linux 9**\n```\nyum install python3 python3-requests python3-packaging\n```\n\n**Installation on FreeBSD**\n```\npkg install python3 py39-requests py39-packaging\n```\n\n**Installation from requirements file**\n```\npip3 install -r requirements.txt\n```\n\n**Installation as Docker container**\n```\ndocker build -t check_pve .\n```\nAfter this, you can start the container like so:\n```\ndocker run -d --name check_pve --rm check_pve\n```\nThe container will keep running without having the need for any of the requirements listed above (for environments that do not support this).\nRunning a check is as simple as:\n```\ndocker exec check_pve python check_pve.py ....rest of the default arguments listed below....\n```\n\n### Create a API user in Proxmox VE\n\nCreate a role named ``Monitoring`` and assign necessary privileges:\n\n```\npveum roleadd Monitoring\npveum rolemod Monitoring --privs VM.Monitor,Sys.Audit,Sys.Modify,Datastore.Audit,VM.Audit\n```\n\nCreate a user named ``monitoring`` and set password:\n\n```\npveum useradd monitoring@pve --comment \"The ICINGA 2 monitoring user\"\n```\n\n#### Use token based authorization (recommended)\n\nCreate an API token named `monitoring` for the user `monitoring` with backend `pve`:\n\n```\npveum user token add monitoring@pve monitoring\n```\n\nPlease save the token secret as there isn't any way to fetch it at a later point.\n\nAssign role `Monitoring` to token `monitoring` and the user `monitoring@pve`:\n\n```\npveum acl modify / --roles Monitoring --user 'monitoring@pve'\npveum acl modify / --roles Monitoring --tokens 'monitoring@pve!monitoring'\n```\n\nYou can now use the check command like this: `./check_pve.py -u monitoring@pve -t monitoring=abcdef12-3456-7890-abcd-deadbeef1234 ...`\n\n#### Use password based authorization\n\nSet password for the user `monitoring`:\n\n```\npveum passwd monitoring@pve\n```\n\nAssign ``monitoring`` role to user ``monitoring``\n\n```\npveum acl modify / --users monitoring@pve --roles Monitoring\n```\n\nFor further information about the Proxmox VE privilege system have a look into the [documentation](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#_strong_pveum_strong_proxmox_ve_user_manager).\n\n\n## Usage\n\nThe ``icinga2`` folder contains the command definition and service examples for use with Icinga2.\n\n```\nusage: check_pve.py [-h] [--version] [-e API_ENDPOINT] [--api-port API_PORT] [-u API_USER] [-p API_PASSWORD | -t API_TOKEN] [-k]\n                    [-m {cluster,version,cpu,memory,swap,storage,io_wait,io-wait,updates,services,subscription,vm,vm_status,vm-status,replication,disk-health,ceph-health,zfs-health,zfs-fragmentation,backup}]\n                    [-n NODE] [--name NAME] [--vmid VMID] [--expected-vm-status {running,stopped,paused}] [--ignore-vmid VMID] [--ignore-vm-status] [--ignore-service NAME] [--ignore-disk NAME]\n                    [--ignore-pools NAME] [-w THRESHOLD_WARNING] [-c THRESHOLD_CRITICAL] [-M] [-V MIN_VERSION] [--unit {GB,MB,KB,GiB,MiB,KiB,B}]\n\nCheck command for PVE hosts via API\n\noptions:\n  -h, --help            show this help message and exit\n  --version             Show version of check command\n\nAPI Options:\n  -e API_ENDPOINT, -H API_ENDPOINT, --api-endpoint API_ENDPOINT\n                        PVE api endpoint hostname or ip address (no additional data like paths)\n  --api-port API_PORT   PVE api endpoint port\n  -u API_USER, --username API_USER\n                        PVE api user (e.g. icinga2@pve or icinga2@pam, depending on which backend you have chosen in proxmox)\n  -p API_PASSWORD, --password API_PASSWORD\n                        PVE API user password\n  -t API_TOKEN, --api-token API_TOKEN\n                        PVE API token (format: TOKEN_ID=TOKEN_SECRET)\n  -k, --insecure        Don't verify HTTPS certificate\n\nCheck Options:\n  -m {cluster,version,cpu,memory,swap,storage,io_wait,io-wait,updates,services,subscription,vm,vm_status,vm-status,replication,disk-health,ceph-health,zfs-health,zfs-fragmentation,backup}, --mode {cluster,version,cpu,memory,swap,storage,io_wait,io-wait,updates,services,subscription,vm,vm_status,vm-status,replication,disk-health,ceph-health,zfs-health,zfs-fragmentation,backup}\n                        Mode to use.\n  -n NODE, --node NODE  Node to check (necessary for all modes except cluster, version and backup)\n  --name NAME           Name of storage, vm, or container\n  --vmid VMID           ID of virtual machine or container\n  --expected-vm-status {running,stopped,paused}\n                        Expected VM status\n  --ignore-vmid VMID    Ignore VM with vmid in checks\n  --ignore-vm-status    Ignore VM status in checks\n  --ignore-service NAME\n                        Ignore service NAME in checks\n  --ignore-disk NAME    Ignore disk NAME in health check\n  --ignore-pools NAME   Ignore vms and containers in pool(s) NAME in checks\n  -w THRESHOLD_WARNING, --warning THRESHOLD_WARNING\n                        Warning threshold for check value. Mutiple thresholds with name:value,name:value\n  -c THRESHOLD_CRITICAL, --critical THRESHOLD_CRITICAL\n                        Critical threshold for check value. Mutiple thresholds with name:value,name:value\n  -M                    Values are shown in the unit which is set with --unit (if available). Thresholds are also treated in this unit\n  -V MIN_VERSION, --min-version MIN_VERSION\n                        The minimal pve version to check for. Any version lower than this will return CRITICAL.\n  --unit {GB,MB,KB,GiB,MiB,KiB,B}\n                        Unit which is used for performance data and other values\n```\n\n## Check examples\n\n\n**Check cluster health**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -t \u003cAPI_TOKEN\u003e -e \u003cAPI_ENDPOINT\u003e -m cluster\nOK - Cluster 'proxmox1' is healthy'\n```\n\n**Check PVE version**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m version -V 5.0.0\nOK - Your pve instance version '5.2' (0fcd7879) is up to date\n```\n\n**Check CPU load**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m cpu -n node1\nOK - CPU usage is 2.4%|usage=2.4%;;\n```\n\n**Check memory usage**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m memory -n node1\nOK - Memory usage is 37.44%|usage=37.44%;; used=96544.72MB;;;257867.91\n```\n\n**Check disk-health**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m disk-health -n node1\nOK - All disks are healthy|wearout_sdb=96%;; wearout_sdc=96%;; wearout_sdd=96%;; wearout_sde=96%;;\n```\n\n**Check storage usage**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m storage -n node1 --name local\nOK - Storage usage is 54.23%|usage=54.23%;; used=128513.11MB;;;236980.36\n\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m storage -n node1 --name vms-disx\nCRITICAL - Storage 'vms-disx' doesn't exist on node 'node01'\n```\n\n**Check subscription status**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m subscription -n node1 -w 50 -c 10\nOK - Subscription of level 'Community' is valid until 2019-01-09\n```\n\n**Check VM status**\n\nWithout specifying a node name:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm --name test-vm\nOK - VM 'test-vm' is running on 'node1'|cpu=1.85%;; memory=8.33%;;\n```\n\nYou can also pass a container name for the VM check:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm --name test-lxc\nOK - LXC 'test-lxc' on node 'node1' is running|cpu=0.11%;; memory=13.99%;;\n```\n\nWith memory thresholds:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm --name test-vm -w 50 -c 80\nOK - VM 'test-vm' is running on 'node1'|cpu=1.85%;; memory=40.33%;50.0;80.0\n```\n\nWith a specified node name, the check plugin verifies on which node the VM runs.\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm -n node1 --name test-vm\nOK - VM 'test-vm' is running on node 'node1'|cpu=1.85%;; memory=8.33%;;\n\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm -n node1 --name test-vm\nWARNING - VM 'test-vm' is running on node 'node2' instead of 'node1'|cpu=1.85%;; memory=8.33%;;\n```\n\nIf you only want to gather metrics and don't care about the vm status add the ``--ignore-vm-status`` flag:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm --name test-vm --ignore-vm-status\nOK - VM 'test-vm' is not running\n```\n\nSpecify the expected VM status:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm --name test-vm --expected-vm-status stopped\nOK - VM 'test-vm' is not running\n\n```\n\nFor hostalive checks without gathering performance data use ``vm_status`` instead of ``vm``. The parameters are the same as with ``vm``.\n\n**Check swap usage**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m swap -n pve\nOK - Swap usage is 0.0 %|usage=0.0%;; used=0.0MB;;;8192.0\n```\n\n**Check storage replication status**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m replication -n node1\nOK - No failed replication jobs on node1\n```\n\n**Check ceph cluster health**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m ceph-health\nWARNING - Ceph Cluster is in warning state\n```\n\n**Check ZFS pool health**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m zfs-health -n pve\nOK - All ZFS pools are healthy\n```\n\nCheck for specific pool:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m zfs-health -n pve --name rpool\nOK - ZFS pool 'rpool' is healthy\n```\n\n**Check ZFS pool fragmentation**\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m zfs-fragmentation -n pve -w 40 -c 60\nCRITICAL - 2 of 2 ZFS pools are above fragmentation thresholds:\n\n- rpool (71 %) is CRITICAL\n- diskpool (50 %) is WARNING\n|fragmentation_diskpool=50%;40.0;60.0 fragmentation_rpool=71%;40.0;60.0\n\n```\n\nCheck for specific pool:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m zfs-fragmentation -n pve --name diskpool -w 40 -c 60\nWARNING - Fragmentation of ZFS pool 'diskpool' is above thresholds: 50 %|fragmentation=50%;40.0;60.0\n```\n\n**Check VZDump Backups**\n\nCheck task history on all nodes:\n\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m backup\nCRITICAL - 8 backup tasks successful, 3 backup tasks failed\n```\n\nCheck for specific node and time frame:\n\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m backup -n pve -c 86400\nOK - 2 backup tasks successful, 0 backup tasks failed within the last 86400.0s\n```\n\nIgnore a VM by their id from backup check:\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m backup --ignore-vmid 123\n```\n\n## FAQ\n\n### Individual thresholds per metric\n\nYou can either specify a threshold for warning or critical which is applied to all metrics or define individual thresholds like this (`name:value,name:value,...`):\n\n```\n./check_pve.py -u \u003cAPI_USER\u003e -p \u003cAPI_PASSWORD\u003e -e \u003cAPI_ENDPOINT\u003e -m vm --name test-vm -w memory:50 -c cpu:50,memory:80\nOK - VM 'test-vm' is running on 'node1'|cpu=1.85%;50.0; memory=40.33%;50.0;80.0\n```\n\n### Could not connect to PVE API: Failed to resolve hostname\n\nVerify 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.\n\n## Contributors\n\nThank you to everyone, who is contributing to `check_pve`: https://github.com/nbuchwitz/check_pve/graphs/contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbuchwitz%2Fcheck_pve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnbuchwitz%2Fcheck_pve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbuchwitz%2Fcheck_pve/lists"}