Install cv4pve-diag and check a Proxmox VE cluster

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.

First run

1. Install cv4pve-diag

   Linux
   zip

   arch=$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/;s/armv7l/arm/')
   wget https://github.com/Corsinvest/cv4pve-diag/releases/latest/download/cv4pve-diag-linux-$arch.zip
   unzip cv4pve-diag-linux-$arch.zip
   chmod +x cv4pve-diag

   Debian / Ubuntu

   curl -s https://api.github.com/repos/Corsinvest/cv4pve-diag/releases/latest | grep -o "https://[^\"]*-$(dpkg --print-architecture)\.deb" | xargs curl -LO
   sudo dpkg -i cv4pve-diag-*-$(dpkg --print-architecture).deb

   RHEL / Fedora

   curl -s https://api.github.com/repos/Corsinvest/cv4pve-diag/releases/latest | grep -o "https://[^\"]*-$(rpm --eval %_target_cpu)\.rpm" | xargs curl -LO
   sudo rpm -i cv4pve-diag-*-$(rpm --eval %_target_cpu).rpm

   Arch Linux

   yay -S cv4pve-diag

   macOS
   Homebrew

   brew install corsinvest/tap/cv4pve-diag

   Installer

   curl -s https://api.github.com/repos/Corsinvest/cv4pve-diag/releases/latest | grep -o "https://[^\"]*-$(uname -m)\.pkg" | xargs curl -LO
   sudo installer -target / -pkg cv4pve-diag-*-$(uname -m).pkg

   zip

   arch=$(uname -m | sed 's/x86_64/x64/')
   curl -LO https://github.com/Corsinvest/cv4pve-diag/releases/latest/download/cv4pve-diag-osx-$arch.zip
   unzip cv4pve-diag-osx-$arch.zip
   chmod +x cv4pve-diag

   Windows
   WinGet

   winget install Corsinvest.cv4pve.diag

   zip

   $arch = @{ AMD64 = 'x64'; x86 = 'x86'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]
   Invoke-WebRequest https://github.com/Corsinvest/cv4pve-diag/releases/latest/download/cv4pve-diag.exe-win-$arch.zip -OutFile cv4pve-diag.zip
   Expand-Archive cv4pve-diag.zip -DestinationPath . -Force

   All files are on the latest release page.

2. Create an API token

   Create a dedicated user and an API token in Proxmox VE, with the privileges the tool needs: see Permissions.

3. Run cv4pve-diag execute

   Point the tool at any node:

   cv4pve-diag --host=pve01 --api-token='diag@pve!audit=<uuid>' execute

   Several nodes, username and password, certificates and options in a file for scheduled runs: see Connection.

4. Read the report

   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.

Run

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=pve01 --api-token='diag@pve!audit=<uuid>' execute           # standard profile
cv4pve-diag --host=pve01 --api-token='diag@pve!audit=<uuid>' execute --fast    # quick scan of a large cluster
cv4pve-diag --host=pve01 --api-token='diag@pve!audit=<uuid>' execute --full    # everything, for audits

# Your own thresholds and accepted findings
cv4pve-diag create-settings                 # then edit settings.json
cv4pve-diag create-ignored-issues           # then edit ignored-issues.json
cv4pve-diag --host=pve01 --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.