# install (x64 — arm64 on the Releases page) $ wget https://github.com/Corsinvest/\ cv4pve-diag/releases/latest/download/\ cv4pve-diag-linux-x64.zip $ unzip cv4pve-diag-linux-x64.zip $ chmod +x cv4pve-diag # run against any node $ ./cv4pve-diag --host=pve01 \ --api-token='diag@pve!audit=…' \ execute --full
# install $ brew install corsinvest/tap/cv4pve-diag # run against any node $ cv4pve-diag --host=pve01 \ --api-token='diag@pve!audit=…' \ execute --full
# install PS> winget install Corsinvest.cv4pve.diag # run against any node PS> cv4pve-diag --host=pve01 ` --api-token='diag@pve!audit=…' ` execute --full
2 critical 5 warning 2 info 4 ok
Find what is wrong in your Proxmox VE cluster
| Gravity | Code | Id | Description | Context | SubContext |
|---|---|---|---|---|---|
| Critical | CC0004 | access/users/root@pam | root@pam has no TFA configured — full access protected only by password | Cluster | Access |
| Critical | CG0002 | nodes/pve02/qemu/203 | Disk 'scsi0' disabled for backup | Qemu | Backup |
| Warning | WN0013 | nodes/pve01 | Node requires reboot: running kernel '6.8.12-20-pve' but newer kernel '6.8.12-43-pve' is installed | Node | Reboot |
| Warning | WS0002 | nodes/pve01/storage/datapool | Image Orphaned 51.54 GB file vm-106-disk-1 | Storage | Image |
| Warning | WS0009 | nodes/pve01/storage/pbs01 | Storage usage 80% - 2.58 TB of 3.22 TB | Storage | Usage |
| Warning | WG0037 | nodes/pve01/qemu/1010 | CPU type 'kvm64' is missing security flags: +spec-ctrl, +ssbd, +pcid, +md-clear — add to cpu flags to mitigate Spectre/Meltdown/MDS | Qemu | CPU |
| Warning | WG0017 | nodes/pve02/qemu/999 | vzdump backup not configured | Qemu | Backup |
| Info | IC0002 | cluster | No HA resources configured — VMs will not automatically restart on node failure | Cluster | HA |
| Info | IN0001 | nodes/pve02 | 6 Update available | Node | Update |
| Ok | WC0001 | cluster/backup | 3 backup job(s) configured at cluster level | Cluster | Backup |
| Ok | WC0003 | cluster | Cluster firewall is enabled | Cluster | Firewall |
| Ok | WG0017 | nodes/pve01/qemu/100 | Guest is covered by at least one enabled backup job | Qemu | Backup |
| Ok | WG0017 | nodes/pve01/qemu/101 | Guest is covered by at least one enabled backup job | Qemu | Backup |
Ok rows come from --full, or IncludeOkResult: true in the settings file.| Gravity | ControlId | Code | Id | Description | Context | SubContext |
|---|---|---|---|---|---|---|
| Critical | Art.21(j) | CC0004 | access/users/root@pam | root@pam has no TFA configured — full access protected only by password | Cluster | Access |
| Critical | Art.21(c) | CG0002 | nodes/pve02/qemu/203 | Disk 'scsi0' disabled for backup | Qemu | Backup |
| Warning | Art.21(e) | WN0013 | nodes/pve01 | Node requires reboot: running kernel '6.8.12-20-pve' but newer kernel '6.8.12-43-pve' is installed | Node | Reboot |
| Warning | Art.21(e) | WG0037 | nodes/pve01/qemu/1010 | CPU type 'kvm64' is missing security flags: +spec-ctrl, +ssbd, +pcid, +md-clear — add to cpu flags to mitigate Spectre/Meltdown/MDS | Qemu | CPU |
| Warning | Art.21(c) | WG0017 | nodes/pve02/qemu/999 | vzdump backup not configured | Qemu | Backup |
| Info | Art.21(c) | IC0002 | cluster | No HA resources configured — VMs will not automatically restart on node failure | Cluster | HA |
| Ok | Art.21(c) | WC0001 | cluster/backup | 3 backup job(s) configured at cluster level | Cluster | Backup |
| Ok | Art.21(e) | WC0003 | cluster | Cluster firewall is enabled | Cluster | Firewall |
| Ok | Art.21(c) | WG0017 | nodes/pve01/qemu/100 | Guest is covered by at least one enabled backup job | Qemu | Backup |
| Ok | Art.21(c) | WG0017 | nodes/pve01/qemu/101 | Guest is covered by at least one enabled backup job | Qemu | Backup |
| Gravity | ControlId | Code | Id | Description | Context | SubContext |
|---|---|---|---|---|---|---|
| Critical | A.5.17, A.8.5 | CC0004 | access/users/root@pam | root@pam has no TFA configured — full access protected only by password | Cluster | Access |
| Critical | A.8.13 | CG0002 | nodes/pve02/qemu/203 | Disk 'scsi0' disabled for backup | Qemu | Backup |
| Warning | A.8.8 | WN0013 | nodes/pve01 | Node requires reboot: running kernel '6.8.12-20-pve' but newer kernel '6.8.12-43-pve' is installed | Node | Reboot |
| Warning | A.5.30, A.8.16 | WS0009 | nodes/pve01/storage/pbs01 | Storage usage 80% - 2.58 TB of 3.22 TB | Storage | Usage |
| Warning | A.8.8 | WG0037 | nodes/pve01/qemu/1010 | CPU type 'kvm64' is missing security flags: +spec-ctrl, +ssbd, +pcid, +md-clear — add to cpu flags to mitigate Spectre/Meltdown/MDS | Qemu | CPU |
| Warning | A.8.13 | WG0017 | nodes/pve02/qemu/999 | vzdump backup not configured | Qemu | Backup |
| Info | A.5.30 | IC0002 | cluster | No HA resources configured — VMs will not automatically restart on node failure | Cluster | HA |
| Ok | A.8.13 | WC0001 | cluster/backup | 3 backup job(s) configured at cluster level | Cluster | Backup |
| Ok | A.8.20, A.8.22 | WC0003 | cluster | Cluster firewall is enabled | Cluster | Firewall |
| Ok | A.8.13 | WG0017 | nodes/pve01/qemu/100 | Guest is covered by at least one enabled backup job | Qemu | Backup |
| Ok | A.8.13 | WG0017 | nodes/pve01/qemu/101 | Guest is covered by at least one enabled backup job | Qemu | Backup |
| Gravity | ControlId | Code | Id | Description | Context | SubContext |
|---|---|---|---|---|---|---|
| Critical | Art.9 | CC0004 | access/users/root@pam | root@pam has no TFA configured — full access protected only by password | Cluster | Access |
| Critical | Art.11, Art.12 | CG0002 | nodes/pve02/qemu/203 | Disk 'scsi0' disabled for backup | Qemu | Backup |
| Warning | Art.11 | WS0009 | nodes/pve01/storage/pbs01 | Storage usage 80% - 2.58 TB of 3.22 TB | Storage | Usage |
| Warning | Art.11, Art.12 | WG0017 | nodes/pve02/qemu/999 | vzdump backup not configured | Qemu | Backup |
| Info | Art.11 | IC0002 | cluster | No HA resources configured — VMs will not automatically restart on node failure | Cluster | HA |
| Ok | Art.11, Art.12 | WC0001 | cluster/backup | 3 backup job(s) configured at cluster level | Cluster | Backup |
| Ok | Art.11, Art.12 | WG0017 | nodes/pve01/qemu/100 | Guest is covered by at least one enabled backup job | Qemu | Backup |
| Ok | Art.11, Art.12 | WG0017 | nodes/pve01/qemu/101 | Guest is covered by at least one enabled backup job | Qemu | Backup |
Ok rows come from --full, or IncludeOkResult: true in the settings file.A Proxmox VE cluster rarely breaks all at once: it drifts. A disk gets excluded from backup, a
snapshot is forgotten for months, a node keeps running the old kernel after an update, root@pam
has no second factor, an HA guest has no replica to fail over to. The web UI shows each object on
its own page, so nothing tells you what is wrong across the cluster — you find out during a
restore, a failover or an audit.
cv4pve-diag reads the whole cluster and lists those problems in one report, each with a stable code, a severity and the resource it concerns, so you can fix them before they matter.
Where it fits
Section titled “Where it fits”The cv4pve suite follows the Unix philosophy: each tool does one thing and does it well. cv4pve-diag finds what is wrong. Its companion cv4pve-report is the RVTools for Proxmox VE: it exports everything the cluster contains, to read, share and keep. Two questions, two tools, used together.
| cv4pve-diag | cv4pve-report | |
|---|---|---|
| Question | What is wrong? | What do I have? |
| Purpose | Diagnostics and health checks | Inventory and reporting |
| Result | A list of problems, each with a code, a severity and the resource it concerns | The full inventory: nodes, VMs, containers, storage, network, users… |
| Formats | Text, HTML, JSON, Markdown, Excel | Excel, static HTML site, multi-file JSON, plus an SVG network diagram |
| Compliance | Findings tagged with the controls of 18 standards | — |
| Access | Proxmox VE API only, from outside the nodes | Proxmox VE API only, from outside the nodes |
Want both on a schedule, from a web interface? cv4pve-admin runs them as its Diagnostics and System Report modules.
Outside the nodes, API only
Section titled “Outside the nodes, API only”cv4pve-diag runs outside the cluster — on your workstation, a management VM or a scheduled job — and talks only to the Proxmox VE REST API. Nothing is installed on the nodes and no SSH or root shell is needed: an API token with the privileges listed in Permissions is enough. Give it more than one node and it connects to the first one that answers, so it still runs while a node is down.
Compliance evidence
Section titled “Compliance evidence”100+ findings are tagged with the controls they relate to. Run it with --compliance=Nis2 (or any of
18 frameworks) and the report keeps only the findings that matter for that standard, each with its
control — root@pam without TFA becomes a gap against NIS2 Art. 21(j), a disk excluded from backup
one against Art. 21(c). A report you can hand to an auditor, produced from the cluster itself.
ISO 27001 · NIS2 · NIS2 Implementing Regulation · ACN NIS2 Italy · DORA · PCI DSS · GDPR · AgID · ENS · BSI C5 · BSI IT-Grundschutz · ISO 22301 · SOC 2 · NIST 800-53 · ISO 27017 · ISO 27018 · CIS · NIST CSF
See the compliance mapping and an example report →
What it does for you
Section titled “What it does for you”Cluster-wide in one run
Quorum, HA, replication, backups, firewall, TFA, SMART, ZFS, LVM-thin, snapshots, guest agent, CPU flags, orphaned disks — cluster, nodes, storages, VMs and containers together.
02Audit evidence, not just alerts
100+ findings carry the controls they relate to. Filter with --compliance and the report gets a ControlId column ready for your auditor.
03Honest about what it cannot see
Proxmox VE silently filters what a token may not read. cv4pve-diag checks the privileges first and states in the report what the analysis does not cover.
04Tuned to your cluster
Thresholds for CPU, memory, PSI pressure, SMART and health score, fast / standard / full profiles, parallel API requests for large clusters.
05Silence what you accepted
Ignore rules by code, resource, context or severity keep the report focused on what is new — and can still be shown for review.
06Every format you need
Text in the terminal, HTML for people, Excel for auditors, JSON and Markdown for automation — from one self-contained binary.
Run your first diagnostic
Download the binary, point it at any node, read the report.
Made by Corsinvest,official Proxmox partner