proxDoc/README.md

ProxDoc - The Proxmox System Doctor

ProxDoc is a comprehensive diagnostic tool for Proxmox server health monitoring and system examination.

⚡ Quick run

Copy and paste on any Proxmox node (as root). Nothing is installed; the script is fetched and run.

# Quick health check: services, temperatures, disk SMART, node exporter, Ceph
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --quick

# Full examination (CPU, RAM, DIMMs, storage, network/NICs, HBAs, services, VMs, containers, Ceph)
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --diags

# One area at a time
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --services     # vital Proxmox services
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --drives       # physical drive-bay map (DriveAtlas)
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --ceph         # Ceph health, OSD tree, usage
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --vm-list      # VM vitals
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --ct-list      # container vitals
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --backup       # backup health
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --checks=cpu,ram   # pick specific checks

Why this exists

When something is wrong with one of six Proxmox nodes I want the same answer every time, in one command, without remembering which of a dozen tools to run: are the services up, are the drives healthy, is Ceph happy, is it running hot? ProxDoc is a single read-only bash script (it never changes system state) that runs those checks and prints a colour-coded report. It is meant to be run straight from the repository with curl | bash, so every node always runs the current version.

Gallery

--quick on a live node (compute-storage-01): services, temperatures, SMART summary, node exporter and Ceph status. A Ceph warning (slow BlueStore operations, with the standing noout flag set) shows up in amber at the bottom.

_{Rendered from real command output with scripts/render_terminal.py; private IPs are masked.}

Features

• Complete system diagnostics and health checks
• DriveAtlas integration for physical drive bay mapping
• Ceph cluster health monitoring (OSD tree, pool usage, disk usage)
• Node Exporter status check for Prometheus monitoring
• hwmon daemon status for hardware monitoring
• Quick health check mode for fast assessments
• Temperature monitoring
• Disk health status via SMART
• CPU and RAM information
• Detailed memory DIMM information (slots, speed, manufacturer)
• Motherboard and system information
• Storage information including ZFS pools
• Network diagnostics with ethtool integration
• Detailed NIC information (driver, firmware, link speed)
• HBA/Storage controller detection and details
• Hardware information
• Service status monitoring
• VM and Container status

Requirements

The script requires the following tools to be installed:

• dmidecode
• lscpu
• ip
• smartctl
• sensors
• lspci
• bc

Optional tools for enhanced diagnostics:

• ethtool (for detailed NIC information including link speed and firmware)
• netstat (for network statistics)

Usage

Run remotely via curl:

curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- [OPTION]

Examples

# Full system diagnostics
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --diags

# Quick health check
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --quick

# Check services
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --services

# Show drive bay mapping
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --drives

Available Options

• --help: Show the help guide
• --diags: Perform full system examination
• --quick: Quick health check (services, temps, disks)
• --drives: Show physical drive bay mapping (DriveAtlas)
• --ceph: Check Ceph cluster health
• --node-exporter: Check Node Exporter status
• --hwmon: Check hwmon daemon status
• --services: Check vital Proxmox services
• --vm-list: Check VM vitals
• --ct-list: Check container vitals
• --backup: Review backup health
• --checks=LIST: Run only specific checks (comma-separated)
  • Valid checks: cpu, ram, memory, storage, disk, network, hardware, temps, services, ceph, vms, containers

Output Information

The script provides detailed information about:

• System information and Proxmox version
• CPU model, cores, and frequency
• RAM usage and detailed DIMM information
• Motherboard manufacturer, model, and serial number
• Storage status
• Disk health
• Network configuration
• Detailed NIC information (driver, MAC, speed, firmware)
• HBA/Storage controller details
• Hardware details including PCI devices
• System load
• Service status
• Recent system errors
• VM and container status

Note

• This script must be run as root
• Designed for Proxmox environments
• Supports Proxmox version 6.0 and above
• No local installation required - runs directly from Gitea

Version

Current Version: 1.2.0

Changelog

v1.2.0

• Fixed variable quoting in disk iteration loops (security)
• Added input validation with whitelist of valid options
• Added examples to help documentation
• Added timeout protection to smartctl and ceph commands
• Added --checks= option for selective diagnostics
• Extracted magic strings into named constants
• Added validation for potentially empty variables
• Standardized error handling with cleanup trap
• Added optional logging infrastructure (PROXDOC_LOGFILE)
• Cached disk list and unit files to reduce command overhead
• Added efficient process wait utility function
• Fixed CPU MHz parsing showing multiple values
• Fixed memory DIMM table not displaying data
• Fixed bonding_masters showing as network interface

v1.1.0

• Added DriveAtlas integration (--drives) for physical drive bay mapping
• Added Ceph cluster health monitoring (--ceph)
• Added Node Exporter status check (--node-exporter)
• Added hwmon daemon status check (--hwmon)
• Added quick health check mode (--quick)
• Added container list option (--ct-list)
• Full diagnostics now include all monitoring checks
• Improved error handling with graceful fallbacks
• Optimized for remote execution via curl

v1.0.0

• Initial release

CI

Workflow	Purpose	Triggers
lint.yml	shellcheck on all .sh files	Every push and PR

Branch protection is enabled on main — the lint check must pass before any PR can merge.