Title: SentryLab-PVE

A lightweight monitoring stack for Proxmox VE hosts. Collects system, storage, ZFS, NVMe wear/SMART metrics and publishes them to MQTT for Home Assistant (and ESPHome displays). Tested on Proxmox VE 9.1.4.

Highlights

• Split collectors: system, temp, wear, health, zfs, non-zfs; orchestrated by active/passive runners.
• Systemd timers for clean scheduling; start/stop helpers provided.
• Safe SMART usage to avoid waking sleeping devices (active cycle only).
• MQTT discovery for Home Assistant; CSV exports for quick hardware mapping.
• ESPHome example (Witty Cloud) for visual alerts.

Layout

install.sh                # Installer (copies scripts and units)
src/
    sentrylab.conf          # MQTT + host config
    utils.sh                # Shared helpers and topics
    discovery.sh            # HA MQTT discovery
    system.sh               # System metrics
    temp.sh                 # NVMe temps
    wear.sh                 # NVMe wear
    health.sh               # NVMe SMART health
    zfs.sh                  # ZFS pools
    non-zfs.sh              # Non-ZFS volumes
    monitor-passive.sh      # Lightweight cycle (no wake)
    monitor-active.sh       # Invasive cycle (SMART/ZFS sync)
    start.sh / stop.sh      # Enable/disable all timers
    system/
        *.service/*.timer   # systemd units
esphome/
    sentrylab-witty.yaml    # Witty Cloud example
    fragments.yaml          # Reusable RGB logic

Prerequisites

• MQTT broker and Home Assistant
• Proxmox host with bash + systemd
• Packages: git, jq, mosquitto-clients

apt update && apt install -y git jq mosquitto-clients

Install

git clone https://github.com/CmPi/SentryLab-PVE.git
cd SentryLab-PVE
sudo ./install.sh

Installer targets:

• Scripts: /usr/local/bin/sentrylab/
• Config: /usr/local/etc/sentrylab.conf
• Units: copied to /usr/local/bin/sentrylab/system/ (deployed to /etc/systemd/system/ only when start.sh is used, removed when stop.sh is used, subject to backup)
• CSV exports: /var/lib/sentrylab/exports/

Configure

Edit /usr/local/etc/sentrylab.conf:

• BROKER, PORT, USER, PASS
• HOST_NAME (defaults to hostname)
• Optional: MQTT_QOS, HA_BASE_TOPIC, DEBUG=true for dry-run

Quick Tests (DEBUG=true)

# Discovery (HA configs only)
DEBUG=true /usr/local/bin/sentrylab/discovery.sh

# Passive set (no wake): system + non-zfs
DEBUG=true /usr/local/bin/sentrylab/monitor-passive.sh

# Active set (may wake drives): temp, wear, health, zfs, non-zfs
DEBUG=true /usr/local/bin/sentrylab/monitor-active.sh

Set DEBUG=false to publish for real.

Automate (systemd)

sudo /usr/local/bin/sentrylab/start.sh   # enable+start timers
sudo /usr/local/bin/sentrylab/stop.sh    # disable all timers

Suggested cadences (edit timers if needed):

• Passive: every 3–5 minutes
• Active: 15–30 minutes (or daily for SMART)
• Discovery: at boot or when sensor set changes

Uninstall

cd SentryLab-PVE
sudo ./uninstall.sh

The uninstaller will:

1. Run stop.sh to disable and stop all services/timers
2. Remove any systemd units from /etc/systemd/system/ that weren't properly cleaned up
3. Remove all scripts from /usr/local/bin/sentrylab/
4. Remove the export directory /var/lib/sentrylab/ (CSV files will be regenerated by discovery.sh if reinstalled)
5. Remind you to manually remove the config file if desired: /usr/local/etc/sentrylab.conf

MQTT Topics (proxmox/)

• system: load/uptime/memory/storage summary
• temp: NVMe temps
• wear: NVMe wear metrics
• health: NVMe SMART health
• zfs: pool health/usage
• disks: non-ZFS usage
• availability: online/offline heartbeat

Topic Examples

Metric	Topic	Payload Example
CPU Load	proxmox/<host>/system/load	0.35
Uptime	proxmox/<host>/system/uptime_sec	86400
NVMe Temp	proxmox/<host>/temp/nvme0	42.1
NVMe Wear	proxmox/<host>/wear/nvme0_wearout	3
NVMe Health	proxmox/<host>/health/nvme0_media_errors	0
ZFS Pool	proxmox/<host>/zfs/<pool>	{ "health": "ONLINE", "alloc": 123456789, "free": 987654321 }
Non-ZFS Disks	proxmox/<host>/disks	{ "sda_size_bytes": 512110190592, "sda_free_bytes": 135239876608, ... }
Availability	proxmox/<host>/availability	online

Home Assistant

• MQTT Discovery is published by discovery.sh to homeassistant/ (or HA_BASE_TOPIC).
• If HA does not show the device, restart the MQTT integration or HA to consume retained configs, then run an active/passive cycle to publish states.

ESPHome (Witty Cloud)

• Use esphome/sentrylab-witty.yaml with your secrets.yaml (wifi, API, OTA keys).
• Set nas_hostname to match HOST_NAME in sentrylab.conf.
• LED logic: ZFS alert = red/blue blink; CPU temp drives green/orange/red; off when cool.

Hardware Mapping (CSV)

• Discovery exports land in /var/lib/sentrylab/exports/ for NVMe/ZFS maps.
• Use them to script HA dashboards or for quick inventory.

Contributing

Issues and PRs welcome.