proxDoc/README.md

# ProxDoc - The Proxmox System Doctor

[![Lint](https://code.lotusguild.org/LotusGuild/proxDoc/actions/workflows/lint.yml/badge.svg)](https://code.lotusguild.org/LotusGuild/proxDoc/actions?workflow=lint.yml)

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

![ProxDoc quick check running on a Proxmox node](docs/img/demo.gif)

## ⚡ Quick run

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

```bash
# 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.

![proxDoc --quick](docs/img/quick-check.png)

<sub>Rendered from real command output with `scripts/render_terminal.py`; private IPs are masked.</sub>

## 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:
```bash
curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- [OPTION]
```

### Examples

```bash
# 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.