Getting started
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 on port 8006. Nothing is installed on the nodes.
Installation
Section titled “Installation”| Platform | How |
|---|---|
| Linux | wget https://github.com/Corsinvest/cv4pve-diag/releases/latest/download/cv4pve-diag-linux-x64.zip && unzip cv4pve-diag-linux-x64.zip && chmod +x cv4pve-diagARM: cv4pve-diag-linux-arm64.zip, cv4pve-diag-linux-arm.zip |
| Debian / Ubuntu | sudo dpkg -i cv4pve-diag-VERSION-ARCH.deb (amd64, arm64, armhf) |
| RHEL / Fedora | sudo rpm -i cv4pve-diag-VERSION-ARCH.rpm (x86_64, aarch64, armv7hl) |
| Arch Linux | yay -S cv4pve-diag |
| Windows (WinGet) | winget install Corsinvest.cv4pve.diag |
| Windows (manual) | cv4pve-diag.exe-win-x64.zip — also x86 and arm64 |
| macOS (Homebrew) | brew install corsinvest/tap/cv4pve-diag |
| macOS (installer) | cv4pve-diag-VERSION-arm64.pkg (Apple silicon) or -x86_64.pkg (Intel) |
| macOS (manual) | cv4pve-diag-osx-arm64.zip or cv4pve-diag-osx-x64.zip |
Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.
Connect to the cluster
Section titled “Connect to the cluster”Create a dedicated user and API token first — see Permissions. Then:
cv4pve-diag --host=pve1.local --api-token='diag@pve!audit=UUID' execute| Option | What it does |
|---|---|
--host | One or more nodes, comma-separated: pve1,pve2:8006,[fe80::1]. The port defaults to 8006. At startup the first node that accepts a connection is used, so the tool runs while a node is down; if the login on that node fails, the others are not tried. Any node gives the view of the whole cluster. |
--api-token | USER@REALM!TOKENID=UUID, Proxmox VE 6.2 or later. Recommended. Quote it on the command line: ! is special in bash. |
--username / --password | Alternative to the token, e.g. --username=diag@pve (without a realm, pam is used). Accounts with two-factor authentication cannot log in this way — use a token.--password=file:/path/secret asks for the password the first time and saves it in that file obfuscated, not encrypted (the key is built into the tool): protect the file like the password itself. |
--validate-certificate | Verify the node TLS certificate. Off by default, so the default self-signed Proxmox certificate is accepted — turn it on if the nodes have a trusted certificate. |
Long command lines can go in a parameter file, one option per line, passed with @:@/etc/cv4pve/production.conf. On error the tool prints ERROR: … and exits with code 1.
cv4pve-diag has three commands:
| Command | What it does |
|---|---|
execute |
Analyses the cluster and prints the report. --fast and --full choose the profile. |
create-settings |
Writes settings.json with the default thresholds (or those of --fast / --full), to edit and pass with --settings-file — see Settings. |
create-ignored-issues |
Writes ignored-issues.json with an example rule, to edit and pass with --ignored-issues-file — see Ignore rules. |
The two create- commands need no connection to the cluster.
cv4pve-diag --host=pve1 --api-token='diag@pve!audit=UUID' execute # standard profilecv4pve-diag --host=pve1 --api-token='diag@pve!audit=UUID' execute --fast # quick scan of a large clustercv4pve-diag --host=pve1 --api-token='diag@pve!audit=UUID' execute --full # everything, for audits
# Your own thresholds and accepted findingscv4pve-diag create-settings # then edit settings.jsoncv4pve-diag create-ignored-issues # then edit ignored-issues.jsoncv4pve-diag --host=pve1 --api-token='diag@pve!audit=UUID' \ --settings-file=settings.json --ignored-issues-file=ignored-issues.json execute--fast and --full go after the command. A settings file always wins over them.
The report lists one finding per row, with a code, a severity and the resource it concerns: Reading the report explains every column and the output formats.