cv4pve-diag

     ______                _                      __
    / ____/___  __________(_)___ _   _____  _____/ /_
   / /   / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
  / /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_
  \____/\____/_/  /____/_/_/ /_/|___/\___/____/\__/

Diagnostic Tool for Proxmox VE (Made in Italy)

Quick Start

# Check available releases at: https://github.com/Corsinvest/cv4pve-diag/releases
# Download specific version (replace VERSION with actual version number)
wget https://github.com/Corsinvest/cv4pve-diag/releases/download/VERSION/cv4pve-diag-linux-x64.zip
unzip cv4pve-diag-linux-x64.zip

# Run diagnostic
./cv4pve-diag --host=YOUR_HOST --username=root@pam --password=YOUR_PASSWORD execute

Features

Core Capabilities

Performance & Reliability

Native C# implementation
Cross-platform (Windows, Linux, macOS)
API-based operation (no root access required)
Cluster support with automatic analysis
High availability with multiple host support

Flexible Analysis

Comprehensive checks for VMs and Containers
Storage monitoring and capacity analysis
Node health verification
Replication status checking
Backup configuration validation

Advanced Reporting

Multiple output formats (Text, HTML, JSON, Markdown)
Severity levels (Critical, Warning, Info)
Customizable settings via configuration files
Issue filtering with ignore rules
Export capabilities for automation

Enterprise Features

API token support (Proxmox VE 6.2+)
SSL validation options
Custom settings management
Ignored issues tracking
Comprehensive logging and status reporting

Installation

Linux Installation

# Check available releases and get the specific version number
# Visit: https://github.com/Corsinvest/cv4pve-diag/releases

# Download specific version (replace VERSION with actual version like v1.9.0)
wget https://github.com/Corsinvest/cv4pve-diag/releases/download/VERSION/cv4pve-diag-linux-x64.zip

# Alternative: Get latest release URL programmatically
LATEST_URL=$(curl -s https://api.github.com/repos/Corsinvest/cv4pve-diag/releases/latest | grep browser_download_url | grep linux-x64 | cut -d '"' -f 4)
wget "$LATEST_URL"

# Extract and make executable
unzip cv4pve-diag-linux-x64.zip
chmod +x cv4pve-diag

# Optional: Move to system path
sudo mv cv4pve-diag /usr/local/bin/

Windows Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-diag/releases
# Download specific version (replace VERSION with actual version)
Invoke-WebRequest -Uri "https://github.com/Corsinvest/cv4pve-diag/releases/download/VERSION/cv4pve-diag.exe-win-x64.zip" -OutFile "cv4pve-diag.zip"

# Extract
Expand-Archive cv4pve-diag.zip -DestinationPath "C:\Tools\cv4pve-diag"

# Add to PATH (optional)
$env:PATH += ";C:\Tools\cv4pve-diag"

macOS Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-diag/releases
# Download specific version (replace VERSION with actual version)
wget https://github.com/Corsinvest/cv4pve-diag/releases/download/VERSION/cv4pve-diag-osx-x64.zip
unzip cv4pve-diag-osx-x64.zip
chmod +x cv4pve-diag

# Move to applications
sudo mv cv4pve-diag /usr/local/bin/

Configuration

Authentication Methods

Username/Password

cv4pve-diag --host=192.168.1.100 --username=root@pam --password=your_password execute

API Token (Recommended)

cv4pve-diag --host=192.168.1.100 --api-token=diagnostic@pve!token1=uuid-here execute

Password from File

# Store password in file
cv4pve-diag --host=192.168.1.100 --username=root@pam --password=file:/etc/cv4pve/password execute

# First run: prompts for password and saves to file
# Subsequent runs: reads password from file automatically

Usage Examples

Basic Diagnostic Operations

Execute Diagnostics

Simple Execution

cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret execute

With Output Format

# HTML output
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret --output=Html execute

# JSON output for automation
cv4pve-diag --host=pve.domain.com --api-token=diag@pve!token=uuid --output=Json execute

# Markdown format
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret --output=Markdown execute

Settings Management

Create Settings File

# Generate default settings file
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret create-settings

# This creates settings.json with customizable diagnostic rules

Use Custom Settings

# Run diagnostics with custom settings
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret --settings-file=settings.json execute

Ignore Issues

Create Ignored Issues File

# Generate ignored issues template
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret create-ignored-issues

# This creates ignored-issues.json

Use Ignored Issues

# Run diagnostics with ignored issues
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret --ignored-issues-file=ignored-issues.json execute

# Show ignored issues in separate table
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret --ignored-issues-file=ignored-issues.json --ignored-issues-show execute

Export Data

Export Collected Data

# Export diagnostic data to JSON file
cv4pve-diag --host=pve.domain.com --username=root@pam --password=secret export-collect

Configuration Files

Parameter Files for Complex Setups

Create Parameter File

# /etc/cv4pve/production.conf
--host=pve-cluster.company.com
--api-token=diagnostic@pve!production=uuid-here
--settings-file=/etc/cv4pve/settings.json
--ignored-issues-file=/etc/cv4pve/ignored-issues.json
--validate-certificate

Execute with Parameter File

cv4pve-diag @/etc/cv4pve/production.conf execute --output=Html

Security & Permissions

Required Permissions

Permission	Purpose	Scope
VM.Audit	Read VM/CT information	Virtual machines
Datastore.Audit	Check storage capacity	Storage systems
Pool.Audit	Access pool information	Resource pools
Sys.Audit	Node system information	Cluster nodes

API Token Setup (Recommended)

Creating API Tokens

1. Generate API Token with Proper Permissions

# Follow Proxmox VE documentation for:
# - API token creation with proper privilege separation
# - Permission assignment for required roles
# - Required permissions: VM.Audit, Datastore.Audit, Pool.Audit, Sys.Audit
# Refer to official Proxmox VE API documentation for detailed steps

2. Use Token in Commands

cv4pve-diag --host=pve.local --api-token=diagnostic@pve!diag-token=uuid-from-creation execute

Advanced Features

Custom Settings

Customize Diagnostic Rules

The settings file allows you to customize thresholds and rules for diagnostics:

{
  "Node": {
    "Cpu": { "Warning": 70, "Critical": 80 },
    "Memory": { "Warning": 70, "Critical": 80 }
  },
  "Storage": {
    "Threshold": { "Warning": 70, "Critical": 80 }
  }
}

Example Usage

# Create default settings
cv4pve-diag --host=pve.local --username=root@pam --password=secret create-settings

# Edit settings.json with your preferences
# Run with custom settings
cv4pve-diag --host=pve.local --username=root@pam --password=secret --settings-file=settings.json execute

Ignore Specific Issues

Filter Unwanted Warnings

Create rules to ignore specific issues using regex patterns:

[
  {
    "Id": "105",
    "Context": "Qemu",
    "SubContext": "Protection"
  }
]

Pattern matching:

Exact match: "Id": "105" - ignora solo VM 105
Partial match: "Description": ".*test.*" - ignora se descrizione contiene "test"
All match: "Id": ".*" - ignora tutti gli ID (usa con Context/SubContext specifici)

Diagnostic Checks

Check Categories

Node Checks

Node online status
Update availability
Replication status
ZFS health
CPU/Memory usage
Storage capacity

VM/CT Checks

VM/CT status
Resource usage
QEMU agent status
Backup configuration
Snapshot age
AutoSnapshot configuration
Protection status
Start on boot
Hardware configuration
VirtIO usage

Storage Checks

Storage capacity
Orphaned images
Disk allocation
Replication errors
Backup file validation

Example Output

-----------------------------------------------------------------------------------------------------------------------------------------
| Id                             | Description                                                  | Context | SubContext   | Gravity  |
-----------------------------------------------------------------------------------------------------------------------------------------
| pve2                           | 1 Replication has errors                                     | Node    | Replication  | Critical |
| pve2                           | Zfs 'rpool' health problem                                   | Node    | Zfs          | Critical |
| 312                            | Unknown resource qemu                                        | Qemu    | Status       | Critical |
| pve3                           | Node not online                                              | Node    | Status       | Warning  |
| local-zfs:vm-117-disk-1        | Image Orphaned                                               | Storage | Image        | Warning  |
| 121                            | Qemu Agent not enabled                                       | Qemu    | Agent        | Warning  |
| 103                            | cv4pve-autosnap not configured                               | Qemu    | AutoSnapshot | Warning  |
| 115                            | vzdump backup not configured                                 | Qemu    | Backup       | Warning  |
| 117                            | Unused disk0                                                 | Qemu    | Hardware     | Warning  |
| 121                            | 10 snapshots older than 1 month                              | Qemu    | Snapshot     | Warning  |
| pve1                           | 3 Update availble                                            | Node    | Update       | Info     |
| 109                            | For more performance switch 'scsi0' hdd to VirtIO            | Qemu    | VirtIO       | Info     |
-----------------------------------------------------------------------------------------------------------------------------------------

Troubleshooting

Common Issues & Solutions

Authentication Problems

Issue: "Authentication failed"

# Verify credentials
cv4pve-diag --host=pve.local --username=root@pam --password=test execute

# Check API token format
cv4pve-diag --host=pve.local --api-token=user@realm!tokenid=uuid execute

Solution: Verify permissions

# Check user permissions in Proxmox
pveum user list
pveum user permissions diagnostic@pve

Connection Issues

Issue: "Connection timeout" or "Host unreachable"

# Test connectivity
ping pve.local
telnet pve.local 8006

# Try with SSL validation disabled (testing only)
cv4pve-diag --host=pve.local --username=root@pam --password=secret execute

Solution: Use SSL validation

# Enable SSL validation for production
cv4pve-diag --host=pve.local --validate-certificate --username=root@pam --password=secret execute

Resources

Video Tutorials

Official Tutorial

Complete setup and usage guide

Web GUI Version

### Documentation Links

Documentation Links

Resource	Description
API Documentation	Proxmox VE API reference
API Token Guide	Proxmox VE API token documentation

Command Reference

Global Options

Complete Parameter List

cv4pve-diag [global-options] [command]

Authentication Options

Parameter	Description	Example
`--host`	Proxmox host(s)	`--host=pve.local:8006`
`--username`	Username@realm	`--username=diagnostic@pve`
`--password`	Password or file	`--password=secret` or `--password=file:/path`
`--api-token`	API token	`--api-token=user@realm!token=uuid`

Connection Options

Parameter	Description	Default
`--validate-certificate`	Validate SSL certificate	`false`

Diagnostic Options

Parameter	Description	Example
`--settings-file`	Custom settings file	`--settings-file=settings.json`
`--ignored-issues-file`	Ignored issues file	`--ignored-issues-file=ignored.json`
`--ignored-issues-show`	Show ignored issues table	Flag

Output Options

Parameter	Description	Options
`--output`	Output format	`Text`, `Html`, `Json`, `JsonPretty`, `Markdown`

Commands

Available Commands

execute

Execute diagnostic and display results

cv4pve-diag --host=pve.local --username=root@pam --password=secret execute

create-settings

Create default settings file

cv4pve-diag --host=pve.local --username=root@pam --password=secret create-settings

create-ignored-issues

Create ignored issues template

cv4pve-diag --host=pve.local --username=root@pam --password=secret create-ignored-issues

export-collect

Export collected diagnostic data

cv4pve-diag --host=pve.local --username=root@pam --password=secret export-collect

Support

Professional support and consulting available through Corsinvest.

Part of cv4pve suite | Made with ❤️ in Italy by Corsinvest

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.github/workflows		.github/workflows
.vscode		.vscode
manifests/c/Corsinvest/cv4pve/diag/1.9.0		manifests/c/Corsinvest/cv4pve/diag/1.9.0
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
3rd-party-licenses.md		3rd-party-licenses.md
Corsinvest.ProxmoxVE.Diagnostic.sln		Corsinvest.ProxmoxVE.Diagnostic.sln
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
LICENSE.md		LICENSE.md
README.md		README.md
icon.png		icon.png

License

Corsinvest/cv4pve-diag

Folders and files

Latest commit

History

Repository files navigation

cv4pve-diag

Quick Start

Features

Core Capabilities

Performance & Reliability

Flexible Analysis

Advanced Reporting

Enterprise Features

Installation

Linux Installation

Windows Installation

macOS Installation

Configuration

Authentication Methods

Username/Password

API Token (Recommended)

Password from File

Usage Examples

Basic Diagnostic Operations

Simple Execution

With Output Format

Create Settings File

Use Custom Settings

Create Ignored Issues File

Use Ignored Issues

Export Collected Data

Configuration Files

Create Parameter File

Execute with Parameter File

Security & Permissions

Required Permissions

API Token Setup (Recommended)

1. Generate API Token with Proper Permissions

2. Use Token in Commands

Advanced Features

Custom Settings

Example Usage

Ignore Specific Issues

Diagnostic Checks

Check Categories

Node Checks

VM/CT Checks

Storage Checks

Example Output

Troubleshooting

Common Issues & Solutions

Issue: "Authentication failed"

Solution: Verify permissions

Issue: "Connection timeout" or "Host unreachable"

Solution: Use SSL validation

Resources

Video Tutorials

Official Tutorial

Web GUI Version

Documentation Links

Command Reference

Global Options

Authentication Options

Connection Options

Diagnostic Options

Output Options

Commands

execute

create-settings

create-ignored-issues

export-collect

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Packages