wingetCollections
  • Auto
  • Search
  • Awesome Collections
  • Awesome Programs
  • My Favorite Collections
  • My Collections
  • Account / Settings
  • Terms of Service
  • Privacy
  • About

© 2026 winget.ragerworks.com

Loading...
Install cv4pve-diag using Winget - wingetCollections
  1. Go back
  2. Packages
  3. cv4pve-diag
cv4pve-diag logo

cv4pve-diag Corsinvest Srl

corsinvest diagnostic health-check monitoring proxmox proxmoxve virtualization vm
Use this command to install cv4pve-diag:
winget install --id=Corsinvest.cv4pve.diag -e

cv4pve-diag is a comprehensive diagnostic tool designed to perform health checks and system analysis on Proxmox VE infrastructure. It helps identify potential issues, optimize performance, and ensure reliability for virtualization environments.

Key Features:

  • Node health and status monitoring to ensure optimal system operation.
  • VM/Container diagnostics and configuration validation for accurate resource allocation.
  • Storage capacity and performance checks to manage disk usage effectively.
  • Replication and backup status verification for data integrity and disaster recovery readiness.
  • Snapshot age monitoring to maintain efficient storage utilization.
  • Multiple output formats (Text, HTML, JSON, Markdown) for flexible reporting.

Audience & Benefit:
Ideal for system administrators managing Proxmox VE clusters, cv4pve-diag provides actionable insights to improve infrastructure performance and reliability. By identifying issues early, it helps users maintain high availability and operational efficiency.

The tool supports customizable severity thresholds, ignore patterns, and integrates seamlessly with cluster environments. It can be installed via winget for easy setup on Windows systems.

README

cv4pve-diag

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

Diagnostic Tool for Proxmox VE (Made in Italy)

License Release Downloads NuGet

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)
Versions
1.9.0
Website
github.com
License
Last updated
1/10/2026
Download latest version
  • 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

    Option 1: WinGet (Recommended)

    # Install using Windows Package Manager
winget install Corsinvest.cv4pve.diag

    Option 2: Manual 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

    PermissionPurposeScope
    VM.AuditRead VM/CT informationVirtual machines
    Datastore.AuditCheck storage capacityStorage systems
    Pool.AuditAccess pool informationResource pools
    Sys.AuditNode system informationCluster 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

    cv4pve-diag Tutorial

    Complete setup and usage guide

    Web GUI Version

    cv4pve-admin### Documentation Links

    Documentation Links

    ResourceDescription
    API DocumentationProxmox VE API reference
    API Token GuideProxmox VE API token documentation

    Command Reference

    Global Options

    Complete Parameter List

    cv4pve-diag [global-options] [command]

    Authentication Options

    ParameterDescriptionExample
    --hostProxmox host(s)--host=pve.local:8006
    --usernameUsername@realm--username=diagnostic@pve
    --passwordPassword or file--password=secret or --password=file:/path
    --api-tokenAPI token--api-token=user@realm!token=uuid

    Connection Options

    ParameterDescriptionDefault
    --validate-certificateValidate SSL certificatefalse

    Diagnostic Options

    ParameterDescriptionExample
    --settings-fileCustom settings file--settings-file=settings.json
    --ignored-issues-fileIgnored issues file--ignored-issues-file=ignored.json
    --ignored-issues-showShow ignored issues tableFlag

    Output Options

    ParameterDescriptionOptions
    --outputOutput formatText, 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

    Copyright © Corsinvest Srl