docs(readme): feature health monitoring & alerts with screenshots (#39)
* docs(readme): add health and alert screenshots, regenerate v2.13.0 TUI shots Real captures from pve (PVE 9.2.20): pman --health, --check WARN -> RESOLVED, status health line, ntfy web app and the alert e-mail (sender redacted). Demo pushes used a throwaway ntfy topic and an isolated state directory. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(readme): feature health monitoring and alerts prominently - screenshot gallery with health view, check, ntfy and e-mail - health/alerts first in the feature table, 'alerts in 3 steps' quick start - architecture diagram shows --health/--check, pvesh and notifications - reference section illustrated; postfix relay hint for e-mail - README is markdownlint-clean; tables are exempt from MD013 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(changelog): make CHANGELOG markdownlint-clean Formatting only, no wording changes: blank line after each section heading, wrapped at 80 columns. MD024 gets siblings_only so the repeated Added/Changed/ Fixed headings of Keep a Changelog are allowed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Tim Baumann <tim@timintech.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
No files matched your search
@@ -1,11 +1,16 @@
|
||||
# markdownlint configuration
|
||||
# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
|
||||
|
||||
# Repeated section names per release (Keep a Changelog)
|
||||
MD024:
|
||||
siblings_only: true
|
||||
|
||||
# Line length
|
||||
MD013:
|
||||
line_length: 80
|
||||
heading_line_length: 80
|
||||
code_blocks: false
|
||||
tables: false
|
||||
|
||||
# Inline HTML allowed
|
||||
MD033: false
|
||||
|
||||
@@ -11,137 +11,188 @@ Versions follow [Semantic Versioning](https://semver.org/).
|
||||
## [2.13.0] - 2026-09-19
|
||||
|
||||
### Added
|
||||
- `--health` (boxed), `--health --list` and `--health --json`: CPU, memory and disk usage, uptime
|
||||
and a health level per local VM/CT, read from `pvesh get /cluster/resources`; templates and guests
|
||||
on other cluster nodes are skipped. `--filter` and `--name` apply.
|
||||
- Main menu key `h` opens the health overview; the status action prints an extra `Health:` line.
|
||||
- `--check` for cron: alerts only on changes (new, escalated, improved, resolved) for resource
|
||||
thresholds (CPU after `HEALTH_CPU_RUNS` consecutive runs; resolved when the guest stops), guests
|
||||
stopped with `onboot=1`, guests whose latest lifecycle task does not explain a stop (stop, shutdown,
|
||||
suspend, migrate, destroy, backup), and failed node tasks (read with `--source all`).
|
||||
Nagios-style summary and exit codes 0 OK, 1 WARN, 2 CRIT, 3 UNKNOWN (also for usage errors).
|
||||
- `--dry-run` (with `--check`) prints the result and the composed message without sending or
|
||||
writing state; `--test-notify` sends a test message.
|
||||
- Notifications via ntfy (`NTFY_URL`, optional `NTFY_TOKEN_FILE`) and e-mail through the local
|
||||
`sendmail` (`HEALTH_MAIL_TO`, `HEALTH_MAIL_FROM`); one combined message per run.
|
||||
- New config keys `HEALTH_{CPU,MEM,DISK}_{WARN,CRIT}` (`0` disables a level), `HEALTH_CPU_RUNS`,
|
||||
`HEALTH_IGNORE_IDS`, `HEALTH_STATE_DIR` (default `/var/lib/pman`) and the notification keys above.
|
||||
- CI runs the test suite (`tests/run.sh`); shell completions gained `--name`, `--health`,
|
||||
`--check`, `--dry-run` and `--test-notify`.
|
||||
|
||||
- `--health` (boxed), `--health --list` and `--health --json`: CPU, memory and
|
||||
disk usage, uptime and a health level per local VM/CT, read from `pvesh get
|
||||
/cluster/resources`; templates and guests on other cluster nodes are skipped.
|
||||
`--filter` and `--name` apply.
|
||||
- Main menu key `h` opens the health overview; the status action prints an extra
|
||||
`Health:` line.
|
||||
- `--check` for cron: alerts only on changes (new, escalated, improved,
|
||||
resolved) for resource thresholds (CPU after `HEALTH_CPU_RUNS` consecutive
|
||||
runs; resolved when the guest stops), guests stopped with `onboot=1`, guests
|
||||
whose latest lifecycle task does not explain a stop (stop, shutdown, suspend,
|
||||
migrate, destroy, backup), and failed node tasks (read with `--source all`).
|
||||
Nagios-style summary and exit codes 0 OK, 1 WARN, 2 CRIT, 3 UNKNOWN (also for
|
||||
usage errors).
|
||||
- `--dry-run` (with `--check`) prints the result and the composed message
|
||||
without sending or writing state; `--test-notify` sends a test message.
|
||||
- Notifications via ntfy (`NTFY_URL`, optional `NTFY_TOKEN_FILE`) and e-mail
|
||||
through the local `sendmail` (`HEALTH_MAIL_TO`, `HEALTH_MAIL_FROM`); one
|
||||
combined message per run.
|
||||
- New config keys `HEALTH_{CPU,MEM,DISK}_{WARN,CRIT}` (`0` disables a level),
|
||||
`HEALTH_CPU_RUNS`, `HEALTH_IGNORE_IDS`, `HEALTH_STATE_DIR` (default
|
||||
`/var/lib/pman`) and the notification keys above.
|
||||
- CI runs the test suite (`tests/run.sh`); shell completions gained `--name`,
|
||||
`--health`, `--check`, `--dry-run` and `--test-notify`.
|
||||
|
||||
### Changed
|
||||
- `STOP_TIMEOUT` and `PROXMOX_MANAGER_SPICE_ADDR` are validated after the command line is parsed.
|
||||
- With `--json` the `--force` warning goes to stderr, so the JSON output stays valid.
|
||||
- Outbound traffic is now possible, but only when notifications are configured (opt-in).
|
||||
|
||||
- `STOP_TIMEOUT` and `PROXMOX_MANAGER_SPICE_ADDR` are validated after the
|
||||
command line is parsed.
|
||||
- With `--json` the `--force` warning goes to stderr, so the JSON output stays
|
||||
valid.
|
||||
- Outbound traffic is now possible, but only when notifications are configured
|
||||
(opt-in).
|
||||
|
||||
### Security
|
||||
- The ntfy access token is read from a `0600` file owned by the caller in a directory nobody else can
|
||||
write; the open descriptor is verified before reading (no swap between check and use). An inline
|
||||
`NTFY_TOKEN` in a config file and a token with an `http://` URL are configuration errors.
|
||||
- The token, URL and headers reach `curl` only via its stdin config, never argv; `curl -q` ignores
|
||||
`~/.curlrc`, redirects are not followed, a token forces `https` only, and requests are not retried.
|
||||
|
||||
- The ntfy access token is read from a `0600` file owned by the caller in a
|
||||
directory nobody else can write; the open descriptor is verified before
|
||||
reading (no swap between check and use). An inline `NTFY_TOKEN` in a config
|
||||
file and a token with an `http://` URL are configuration errors.
|
||||
- The token, URL and headers reach `curl` only via its stdin config, never argv;
|
||||
`curl -q` ignores `~/.curlrc`, redirects are not followed, a token forces
|
||||
`https` only, and requests are not retried.
|
||||
- Logs name only the ntfy host, never the topic path or the token.
|
||||
- Mail headers are built from validated single-line values (no header injection).
|
||||
- JSON output escapes all control characters; `_truncate` never cuts inside a UTF-8 character.
|
||||
- `qm`/`pct` config fallbacks run with a timeout; the `--check` lock descriptor is not inherited by
|
||||
child processes and the lock file is never truncated; the state directory's parent must not be
|
||||
group/world-writable.
|
||||
- The `--check` state lives in a `0700` directory, is written atomically with mode `0600`, is parsed
|
||||
as validated data (never sourced), and parallel runs are prevented with `flock`.
|
||||
- Mail headers are built from validated single-line values (no header
|
||||
injection).
|
||||
- JSON output escapes all control characters; `_truncate` never cuts inside a
|
||||
UTF-8 character.
|
||||
- `qm`/`pct` config fallbacks run with a timeout; the `--check` lock descriptor
|
||||
is not inherited by child processes and the lock file is never truncated; the
|
||||
state directory's parent must not be group/world-writable.
|
||||
- The `--check` state lives in a `0700` directory, is written atomically with
|
||||
mode `0600`, is parsed as validated data (never sourced), and parallel runs
|
||||
are prevented with `flock`.
|
||||
|
||||
## [2.12.1] - 2026-09-19
|
||||
|
||||
### Fixed
|
||||
- Action and snapshot menus now draw a closed frame: every row is padded to the box width and gets a right
|
||||
border; long guest names in the menu titles are truncated instead of overflowing.
|
||||
|
||||
- Action and snapshot menus now draw a closed frame: every row is padded to the
|
||||
box width and gets a right border; long guest names in the menu titles are
|
||||
truncated instead of overflowing.
|
||||
|
||||
### Changed
|
||||
- README screenshots regenerated from v2.12.1 on a real PVE 9.2 host; the obsolete, unreferenced
|
||||
`docs/screenshots/Screenshot.png` (pre-2.8 UI) was removed.
|
||||
|
||||
- README screenshots regenerated from v2.12.1 on a real PVE 9.2 host; the
|
||||
obsolete, unreferenced `docs/screenshots/Screenshot.png` (pre-2.8 UI) was
|
||||
removed.
|
||||
|
||||
## [2.12.0] - 2026-09-19
|
||||
|
||||
### Security
|
||||
- Configuration files are now parsed as allowlisted data instead of being executed with `source`.
|
||||
- Log files must be private, owner-controlled regular files; unsafe paths and symlinks are rejected.
|
||||
- The system-wide `pman` command is installed as an atomic root-owned copy instead of a symlink to a potentially user-writable checkout.
|
||||
- GitHub Actions are commit-SHA pinned, remote tool downloads are checksum-verified, workflow permissions are minimized, and checkout credentials are not persisted.
|
||||
- User-controlled status and message text is no longer interpreted as `printf %b` escape sequences.
|
||||
|
||||
- Configuration files are now parsed as allowlisted data instead of being
|
||||
executed with `source`.
|
||||
- Log files must be private, owner-controlled regular files; unsafe paths and
|
||||
symlinks are rejected.
|
||||
- The system-wide `pman` command is installed as an atomic root-owned copy
|
||||
instead of a symlink to a potentially user-writable checkout.
|
||||
- GitHub Actions are commit-SHA pinned, remote tool downloads are
|
||||
checksum-verified, workflow permissions are minimized, and checkout
|
||||
credentials are not persisted.
|
||||
- User-controlled status and message text is no longer interpreted as `printf
|
||||
%b` escape sequences.
|
||||
|
||||
### Fixed
|
||||
- Broken TUI frames (#33): header and table rows are now padded by visible width, so right borders line up;
|
||||
the table gained a closing border, the NAME column grows with long guest names (capped at the terminal
|
||||
width, then truncated), and header/data columns are aligned in `--list` output too.
|
||||
- The header showed `PVE: (running` instead of the version; it now parses `pveversion` correctly and shows a
|
||||
compact uptime (e.g. `12d 1h 25m`).
|
||||
- VM IP lookup now accepts the native QEMU Guest Agent list payload from `qm agent ... network-get-interfaces`
|
||||
as well as the earlier wrapped shape, preventing parser errors on hosts that return a bare JSON array.
|
||||
- Snapshot name validation now matches Proxmox `pve-configid` rules before calling `pct` / `qm`;
|
||||
numeric-only and single-letter names are rejected locally with a clearer message.
|
||||
- SPICE `.vv` files now prefer the actual SPICE bind address/port from Proxmox instead of always
|
||||
using the host LAN IP, preventing mismatched connection targets on loopback-bound SPICE setups.
|
||||
- `spice_info()` no longer claims success launching `virt-viewer` from a non-graphical shell; it
|
||||
falls back to the `.vv` file with a clear desktop-session hint.
|
||||
- VM console guidance now tells the user to follow the escape hint printed by Proxmox instead of
|
||||
hardcoding a potentially wrong key sequence.
|
||||
|
||||
- Broken TUI frames (#33): header and table rows are now padded by visible
|
||||
width, so right borders line up; the table gained a closing border, the NAME
|
||||
column grows with long guest names (capped at the terminal width, then
|
||||
truncated), and header/data columns are aligned in `--list` output too.
|
||||
- The header showed `PVE: (running` instead of the version; it now parses
|
||||
`pveversion` correctly and shows a compact uptime (e.g. `12d 1h 25m`).
|
||||
- VM IP lookup now accepts the native QEMU Guest Agent list payload from `qm
|
||||
agent ... network-get-interfaces` as well as the earlier wrapped shape,
|
||||
preventing parser errors on hosts that return a bare JSON array.
|
||||
- Snapshot name validation now matches Proxmox `pve-configid` rules before
|
||||
calling `pct` / `qm`; numeric-only and single-letter names are rejected
|
||||
locally with a clearer message.
|
||||
- SPICE `.vv` files now prefer the actual SPICE bind address/port from Proxmox
|
||||
instead of always using the host LAN IP, preventing mismatched connection
|
||||
targets on loopback-bound SPICE setups.
|
||||
- `spice_info()` no longer claims success launching `virt-viewer` from a
|
||||
non-graphical shell; it falls back to the `.vv` file with a clear
|
||||
desktop-session hint.
|
||||
- VM console guidance now tells the user to follow the escape hint printed by
|
||||
Proxmox instead of hardcoding a potentially wrong key sequence.
|
||||
|
||||
### Added
|
||||
- New **IP info** menu item: shows current IPv4 addresses for running VMs and CTs. VMs use the
|
||||
QEMU Guest Agent, CTs use `pct exec ... ip -j addr show`, with clear fallback messages when
|
||||
no address is available.
|
||||
|
||||
- New **IP info** menu item: shows current IPv4 addresses for running VMs and
|
||||
CTs. VMs use the QEMU Guest Agent, CTs use `pct exec ... ip -j addr show`,
|
||||
with clear fallback messages when no address is available.
|
||||
|
||||
## [2.9.0 – 2.11.1] - 2026-04-09 – 2026-05-04
|
||||
|
||||
Consolidated notes for the releases between 2.8.4 and 2.11.1 (tagged `v2.9.0` and `v2026.05.04`).
|
||||
Consolidated notes for the releases between 2.8.4 and 2.11.1 (tagged `v2.9.0`
|
||||
and `v2026.05.04`).
|
||||
|
||||
### Added
|
||||
- `--filter STATUS` flag: filter `--list` / `--json` output to `running`, `stopped`, or `paused`
|
||||
instances; invalid values exit 1 with a clear error message.
|
||||
- `--timeout SECS` flag: set a timeout (default 60 s) for stop operations; on exit code 124
|
||||
(timeout fired) automatically retries with `--overrule-shutdown 1` as a force-stop fallback.
|
||||
- `--force` flag: skip all `confirm()` prompts automatically; prints a warning at startup and
|
||||
logs each bypassed prompt in yellow so the action is always visible.
|
||||
- `filtered_instances()` wrapper around `collect_instances()`; used by `print_table` and
|
||||
`print_json` so filter logic is in one place.
|
||||
- Bash completion script: `completions/pman.bash` — tab-completes all flags; suggests
|
||||
`running|stopped|paused` after `--filter` and common timeout values after `--timeout`.
|
||||
- Zsh completion script: `completions/pman.zsh` — `_arguments`-based with value specs for
|
||||
`--filter` and `--timeout`.
|
||||
- GitHub issue templates (YAML form format): `bug_report.yml`, `feature_request.yml`.
|
||||
- GitHub `ISSUE_TEMPLATE/config.yml`: blank issues disabled, link to Discussions.
|
||||
- GitHub `PULL_REQUEST_TEMPLATE.md` with ShellCheck / test / changelog checklist.
|
||||
- GitHub `workflows/release.yml`: auto-creates a GitHub Release with `proxmox-manager.sh`
|
||||
as an asset on every `v*` tag push.
|
||||
|
||||
- `--filter STATUS` flag: filter `--list` / `--json` output to `running`,
|
||||
`stopped`, or `paused` instances; invalid values exit 1 with a clear error
|
||||
message.
|
||||
- `--timeout SECS` flag: set a timeout (default 60 s) for stop operations; on
|
||||
exit code 124 (timeout fired) automatically retries with `--overrule-shutdown
|
||||
1` as a force-stop fallback.
|
||||
- `--force` flag: skip all `confirm()` prompts automatically; prints a warning
|
||||
at startup and logs each bypassed prompt in yellow so the action is always
|
||||
visible.
|
||||
- `filtered_instances()` wrapper around `collect_instances()`; used by
|
||||
`print_table` and `print_json` so filter logic is in one place.
|
||||
- Bash completion script: `completions/pman.bash` — tab-completes all flags;
|
||||
suggests `running|stopped|paused` after `--filter` and common timeout values
|
||||
after `--timeout`.
|
||||
- Zsh completion script: `completions/pman.zsh` — `_arguments`-based with value
|
||||
specs for `--filter` and `--timeout`.
|
||||
- GitHub issue templates (YAML form format): `bug_report.yml`,
|
||||
`feature_request.yml`.
|
||||
- GitHub `ISSUE_TEMPLATE/config.yml`: blank issues disabled, link to
|
||||
Discussions.
|
||||
- GitHub `PULL_REQUEST_TEMPLATE.md` with ShellCheck / test / changelog
|
||||
checklist.
|
||||
- GitHub `workflows/release.yml`: auto-creates a GitHub Release with
|
||||
`proxmox-manager.sh` as an asset on every `v*` tag push.
|
||||
- GitHub `FUNDING.yml`: GitHub Sponsors link for TimInTech.
|
||||
|
||||
### Fixed
|
||||
- `do_action restart`: replaced manual `stop → sleep 1 → start` sequence with native
|
||||
`pct reboot` / `qm reboot` — atomic, no unnecessary 1-second delay, cleaner error output.
|
||||
|
||||
- `do_action restart`: replaced manual `stop → sleep 1 → start` sequence with
|
||||
native `pct reboot` / `qm reboot` — atomic, no unnecessary 1-second delay,
|
||||
cleaner error output.
|
||||
|
||||
### Changed
|
||||
- `type_of_id()` now checks a global `_type_cache` associative array before querying
|
||||
`pct list` / `qm list`; cache is populated as a zero-cost side-effect of the existing
|
||||
`main_menu` instance loop (no extra Proxmox call required).
|
||||
- `collect_instances()`: replaced three `awk '{print $N}' <<<` subshells per VM/CT with a
|
||||
single parameter-expansion trim + `IFS=' ' read -r` — eliminates 6 subshells per iteration.
|
||||
- `print_table` "no results" message is context-aware: when `--filter` is active it shows
|
||||
"No \<status\> VMs or containers found." rather than the generic root-hint message.
|
||||
|
||||
- `type_of_id()` now checks a global `_type_cache` associative array before
|
||||
querying `pct list` / `qm list`; cache is populated as a zero-cost side-effect
|
||||
of the existing `main_menu` instance loop (no extra Proxmox call required).
|
||||
- `collect_instances()`: replaced three `awk '{print $N}' <<<` subshells per
|
||||
VM/CT with a single parameter-expansion trim + `IFS=' ' read -r` — eliminates
|
||||
6 subshells per iteration.
|
||||
- `print_table` "no results" message is context-aware: when `--filter` is active
|
||||
it shows "No \<status\> VMs or containers found." rather than the generic
|
||||
root-hint message.
|
||||
|
||||
---
|
||||
|
||||
## [2.8.4] - 2026-03-06
|
||||
|
||||
### Fixed
|
||||
- `validate_snapshot_name()` now applied to rollback and delete operations (previously only
|
||||
enforced on create).
|
||||
- `snapshots_menu`: rollback and delete show Proxmox error details via `_rb_out` / `_del_out`
|
||||
variables, consistent with create.
|
||||
- `open_console`: guard added for VM terminal — checks `qm status` before calling
|
||||
`qm terminal`; prints `Ctrl+]` exit hint before entering.
|
||||
- `_pve_out` correctly declared `local` in stop and restart branches of `do_action()`;
|
||||
fixes potential variable bleed between branches.
|
||||
|
||||
- `validate_snapshot_name()` now applied to rollback and delete operations
|
||||
(previously only enforced on create).
|
||||
- `snapshots_menu`: rollback and delete show Proxmox error details via `_rb_out`
|
||||
/ `_del_out` variables, consistent with create.
|
||||
- `open_console`: guard added for VM terminal — checks `qm status` before
|
||||
calling `qm terminal`; prints `Ctrl+]` exit hint before entering.
|
||||
- `_pve_out` correctly declared `local` in stop and restart branches of
|
||||
`do_action()`; fixes potential variable bleed between branches.
|
||||
|
||||
### Added
|
||||
|
||||
- Keyboard legend in the main menu (`<VMID>`, `r`, `q`).
|
||||
|
||||
---
|
||||
@@ -149,32 +200,40 @@ Consolidated notes for the releases between 2.8.4 and 2.11.1 (tagged `v2.9.0` an
|
||||
## [2.8.3] - 2026-03-06
|
||||
|
||||
### Added
|
||||
|
||||
- `pman` global command: `install_dependencies.sh` now installs a symlink at
|
||||
`/usr/local/bin/pman`; idempotent.
|
||||
|
||||
### Fixed
|
||||
|
||||
- `_pve_out` declared `local` in all do_action() branches.
|
||||
- Rollback and delete snapshot errors now captured and displayed.
|
||||
- VM console guard: `open_console` checks VM running status before `qm terminal`.
|
||||
- VM console guard: `open_console` checks VM running status before `qm
|
||||
terminal`.
|
||||
|
||||
---
|
||||
|
||||
## [2.8.2] - 2026-03-06
|
||||
|
||||
### Fixed
|
||||
- Proxmox error details surfaced on start / stop / restart failure via stderr capture.
|
||||
|
||||
- Proxmox error details surfaced on start / stop / restart failure via stderr
|
||||
capture.
|
||||
- Snapshot name validated before any Proxmox call (create path).
|
||||
- UX polish: VMID-not-found message hints to press `r` to refresh; empty Enter in
|
||||
action menu treated as "Back".
|
||||
- UX polish: VMID-not-found message hints to press `r` to refresh; empty Enter
|
||||
in action menu treated as "Back".
|
||||
|
||||
---
|
||||
|
||||
## [2.8.1] - 2026-03-06
|
||||
|
||||
### Fixed
|
||||
- `open_console`: CT status checked before `pct enter`; clear error if not running.
|
||||
|
||||
- `open_console`: CT status checked before `pct enter`; clear error if not
|
||||
running.
|
||||
|
||||
### Added
|
||||
|
||||
- `print_table` appends colour-coded count line: `Count: N running M stopped`.
|
||||
- `header()` shows system uptime via `uptime -p`.
|
||||
|
||||
@@ -183,12 +242,16 @@ Consolidated notes for the releases between 2.8.4 and 2.11.1 (tagged `v2.9.0` an
|
||||
## [2.8.0] - 2026-03-06
|
||||
|
||||
### Changed
|
||||
- Full modular rewrite: `collect_instances`, `print_table`, `print_json`, `do_action`,
|
||||
`snapshots_menu`, `spice_info`, `spice_enable` separated into distinct functions.
|
||||
- Status symbols changed to ASCII: `[+]` running, `[-]` stopped, `[~]` paused, `[?]` unknown.
|
||||
|
||||
- Full modular rewrite: `collect_instances`, `print_table`, `print_json`,
|
||||
`do_action`, `snapshots_menu`, `spice_info`, `spice_enable` separated into
|
||||
distinct functions.
|
||||
- Status symbols changed to ASCII: `[+]` running, `[-]` stopped, `[~]` paused,
|
||||
`[?]` unknown.
|
||||
- Output normalised to English throughout.
|
||||
- `set -Eeuo pipefail` + `IFS=$'\n\t'` + `LC_ALL=C` hardened at the top.
|
||||
- `confirm()` added before all destructive actions (stop, restart, rollback, delete).
|
||||
- `confirm()` added before all destructive actions (stop, restart, rollback,
|
||||
delete).
|
||||
- `log()` added for optional structured file logging via `$LOG_FILE`.
|
||||
- `validate_vmid()` added — rejects non-numeric or out-of-range VMIDs.
|
||||
- `header()` shows node hostname and PVE version when available.
|
||||
@@ -200,7 +263,8 @@ Consolidated notes for the releases between 2.8.4 and 2.11.1 (tagged `v2.9.0` an
|
||||
|
||||
## [1.5.0] - (pre-rewrite)
|
||||
|
||||
Early version with basic console and snapshot management. Replaced by the v2.8.0 rewrite.
|
||||
Early version with basic console and snapshot management. Replaced by the v2.8.0
|
||||
rewrite.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<!-- markdownlint-disable MD033 MD041 -->
|
||||
<div align="center">
|
||||
|
||||
```
|
||||
```text
|
||||
╔══════════════════════════════════════════════════════════╗
|
||||
║ ██████╗ ███╗ ███╗ █████╗ ███╗ ██╗ ║
|
||||
║ ██╔══██╗ ████╗ ████║ ██╔══██╗ ████╗ ██║ ║
|
||||
@@ -17,35 +17,50 @@
|
||||
**Single-file Bash tool for managing Proxmox VMs and containers.**
|
||||
No daemons. No agents. No dependencies beyond what ships with Proxmox VE.
|
||||
|
||||
**New in v2.13.0:** 🩺 health view per guest and 🔔 ntfy / e-mail alerts from a
|
||||
cron check — [set up alerts in 3 steps](#-quick-start-alerts-in-3-steps).
|
||||
|
||||
[](https://github.com/TimInTech/proxmox-manager/actions)
|
||||
[](https://github.com/TimInTech/proxmox-manager/actions)
|
||||
[](LICENSE)
|
||||
[](https://www.gnu.org/software/bash/)
|
||||
[](https://www.proxmox.com/)
|
||||
[](https://www.proxmox.com/)
|
||||
|
||||

|
||||
|
||||
<a href="https://buymeacoffee.com/timintech" target="_blank" rel="noopener noreferrer">
|
||||
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60" width="217">
|
||||
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png"
|
||||
alt="Buy Me A Coffee" height="60" width="217">
|
||||
</a>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📖 Community & Tutorials
|
||||
|
||||
Check out how others are using `proxmox-manager`:
|
||||
|
||||
* 🇵🇱 **[Proxmox Manager – Co to jest, jak działa, instalacja i obsługa](https://blog.askomputer.pl/proxmox-manager-timintech-co-to-jest-jak-dziala-instalacja-i-obsluga/)** *A detailed walkthrough and review by askomputer.pl featuring usage examples and screenshots (in Polish).*
|
||||
- 🇵🇱 **[Proxmox Manager – Co to jest, jak działa, instalacja i
|
||||
obsługa](https://blog.askomputer.pl/proxmox-manager-timintech-co-to-jest-jak-dziala-instalacja-i-obsluga/)**
|
||||
*A detailed walkthrough and review by askomputer.pl featuring usage examples
|
||||
and screenshots (in Polish).*
|
||||
|
||||
## 📸 Screenshots
|
||||
|
||||
<div align="center">
|
||||
|
||||
| Main Menu — VM/CT Table | Action Menu |
|
||||
| Main menu — VM/CT table | Action menu — status with health line |
|
||||
|:---:|:---:|
|
||||
|  |  |
|
||||
| Live status for all VMs & containers | Per-instance controls: start, stop, console, snapshots |
|
||||
| Live status for all VMs & containers | Start, stop, console, snapshots; `Status` adds CPU / MEM / DISK |
|
||||
| **Health view — `pman --health`** | **Cron check — `pman --check`** |
|
||||
|  |  |
|
||||
| CPU / MEM / DISK %, uptime and level per guest | WARN → RESOLVED with Nagios exit codes |
|
||||
| **ntfy push — web app** | **E-mail alert** |
|
||||
|  |  |
|
||||
| Same message on phone, desktop or browser | Plain-text mail via the local `sendmail` |
|
||||
|
||||
</div>
|
||||
|
||||
@@ -55,57 +70,112 @@ Check out how others are using `proxmox-manager`:
|
||||
|
||||
| | Feature | Details |
|
||||
|---|---|---|
|
||||
| 🩺 | **Health Monitoring** | CPU / RAM / disk per guest, uptime and OK / WARN / CRIT — `pman --health`, key `h` in the TUI, `Health:` line in the status action |
|
||||
| 🔔 | **Alerts** | `pman --check` for cron: thresholds, stopped `onboot` guests, unexpected stops and failed tasks; ntfy / e-mail only when something changes (opt-in) |
|
||||
| 📋 | **List & Status** | All VMs and containers with live status — `[+]` running · `[-]` stopped · `[~]` paused · `[?]` unknown |
|
||||
| ⚡ | **Start / Stop / Restart** | Confirmation prompt for destructive actions. Proxmox error details on failure. Configurable timeout with force-stop fallback |
|
||||
| 🖥️ | **Console Access** | LXC shell via `pct enter` or QEMU terminal via `qm terminal`. Verifies running state before entering |
|
||||
| 🌐 | **IP Address Lookup** | Shows current IPv4 addresses for running VMs and CTs — VM via QEMU Guest Agent, CT via `pct exec` |
|
||||
| 📦 | **Snapshot Management** | List, create, rollback, delete — with name validation and snapshot preview before destructive actions |
|
||||
| 🖱️ | **SPICE Integration** | Enable SPICE for VMs and retrieve `.vv` connection files. Auto-launches `virt-viewer` when installed |
|
||||
| 🩺 | **Health & Alerts** | CPU / RAM / disk per guest, stopped-with-onboot, unexpected stops and failed tasks — `--health` view, `--check` for cron with ntfy / e-mail alerts (opt-in) |
|
||||
| 🤖 | **Automation-Ready** | `--json` output, `--filter` by status, `--name` ERE filter, `--force` mode, structured logging via `LOG_FILE` |
|
||||
| ⚙️ | **Config File** | Persistent allowlisted defaults via `/etc/pmanrc` or `~/.pmanrc` — CLI flags always win |
|
||||
|
||||
---
|
||||
|
||||
## 🔔 Quick start: alerts in 3 steps
|
||||
|
||||
Run as root on the Proxmox node after [installing `pman`](#-installation).
|
||||
|
||||
### 1 — Pick a channel in `/etc/pmanrc`
|
||||
|
||||
```bash
|
||||
touch /etc/pmanrc && chmod 600 /etc/pmanrc
|
||||
cat >>/etc/pmanrc <<'EOF'
|
||||
NTFY_URL="https://ntfy.sh/pman-alerts-CHANGE-ME" # hard-to-guess topic name
|
||||
HEALTH_MAIL_TO="admin@example.com" # optional, needs sendmail
|
||||
EOF
|
||||
```
|
||||
|
||||
Anyone who knows a public ntfy.sh topic can read it — treat the name like a
|
||||
password, or use a [protected topic](#health-monitoring--alerts) with a token.
|
||||
|
||||
### 2 — Send a test message
|
||||
|
||||
```bash
|
||||
pman --test-notify
|
||||
pman --check --dry-run; echo "exit $?" # what would be sent, nothing saved
|
||||
```
|
||||
|
||||
Subscribe to the same topic in the [ntfy
|
||||
app](https://ntfy.sh/docs/subscribe/phone/) or at `https://ntfy.sh/<your-topic>`
|
||||
in the browser; the test message shows up there.
|
||||
|
||||
### 3 — Let cron check every 5 minutes
|
||||
|
||||
```bash
|
||||
cat >/etc/cron.d/pman-health <<'EOF'
|
||||
PATH=/usr/sbin:/usr/bin:/sbin:/bin
|
||||
*/5 * * * * root /usr/local/bin/pman --check >/dev/null 2>&1
|
||||
EOF
|
||||
```
|
||||
|
||||
The first run only records a baseline. From then on, you get one message per
|
||||
change — new or escalated problems, improvements and `RESOLVED`:
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/screenshot-ntfy.png"
|
||||
alt="ntfy web app with WARN and RESOLVED alerts from pman"
|
||||
width="720">
|
||||
</p>
|
||||
|
||||
Details, thresholds and limitations: [Health monitoring &
|
||||
alerts](#health-monitoring--alerts).
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ How It Works
|
||||
|
||||
A single `proxmox-manager.sh` script — no build step, no service, no config files. Runs on-demand as root directly on the Proxmox VE node.
|
||||
A single `proxmox-manager.sh` script — no build step, no service, config
|
||||
optional. Runs on-demand as root directly on the Proxmox VE node; alerts run
|
||||
from cron.
|
||||
|
||||
```
|
||||
User / Automation
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ pman (proxmox-manager.sh) │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌─────────────┐ │
|
||||
│ │ --list │ │ interactive │ │
|
||||
│ │ --json │ │ TUI │ │
|
||||
│ │ --filter │ │ │ │
|
||||
│ └────┬─────┘ └──────┬──────┘ │
|
||||
└───────┼───────────────┼─────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────────────────────┐
|
||||
│ qm (VMs) · pct (CTs) │ ← Proxmox CLI (bundled with PVE)
|
||||
└───────────────────────────────┘
|
||||
```text
|
||||
User / Automation cron (*/5)
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────────────────────────────────────────────┐
|
||||
│ pman (proxmox-manager.sh) │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌─────────────┐ ┌──────────────────┐ │
|
||||
│ │ --list │ │ interactive │ │ --health │ │
|
||||
│ │ --json │ │ TUI │ │ --check ─────────┼──┼──▶ ntfy / e-mail
|
||||
│ │ --filter │ │ │ │ state: /var/lib │ │ (on change)
|
||||
│ └────┬─────┘ └──────┬──────┘ └────────┬─────────┘ │
|
||||
└───────┼───────────────┼──────────────────┼────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────────────────────────────────────────────────┐
|
||||
│ qm (VMs) · pct (CTs) · pvesh (usage, tasks) │ ← Proxmox CLI
|
||||
└───────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────┐
|
||||
│ Proxmox VE Host (local) │
|
||||
│ QEMU Virtual Machines │
|
||||
│ LXC Containers │
|
||||
└───────────────────────────────┘
|
||||
┌───────────────────────────────────────────────────────┐
|
||||
│ Proxmox VE Host (local) │
|
||||
│ QEMU Virtual Machines · LXC Containers │
|
||||
└───────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
> ✅ No network calls (unless alerts are configured) · ✅ No background process · ✅ Bash ≥ 4.0 · ✅ PVE 7.x / 8.x / 9.x
|
||||
> ✅ No network calls (unless alerts are configured) · ✅ No background process ·
|
||||
> ✅ Bash ≥ 4.0 · ✅ PVE 7.x / 8.x / 9.x
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Installation
|
||||
|
||||
**Requirements:** Proxmox VE host · Bash ≥ 4.0 · Root privileges · `qm` / `pct` / `pvesh` and
|
||||
`python3` (all bundled with PVE) · optional: `sendmail` (e.g. postfix) for e-mail alerts
|
||||
**Requirements:** Proxmox VE host · Bash ≥ 4.0 · Root privileges · `qm` / `pct`
|
||||
/ `pvesh` and `python3` (all bundled with PVE) · optional: `sendmail` (e.g.
|
||||
postfix) for e-mail alerts
|
||||
|
||||
### Step 1 — Clone
|
||||
|
||||
@@ -121,13 +191,14 @@ chmod +x proxmox-manager.sh
|
||||
./proxmox-manager.sh
|
||||
```
|
||||
|
||||
### Step 3 — Or register as `pman` system-wide _(optional, requires root)_
|
||||
### Step 3 — Or register as `pman` system-wide *(optional, requires root)*
|
||||
|
||||
```bash
|
||||
./install_dependencies.sh
|
||||
```
|
||||
|
||||
Installs an atomic, root-owned copy at `/usr/local/bin/pman` so later edits to the checkout cannot change the privileged executable.
|
||||
Installs an atomic, root-owned copy at `/usr/local/bin/pman` so later edits to
|
||||
the checkout cannot change the privileged executable.
|
||||
|
||||
---
|
||||
|
||||
@@ -153,13 +224,13 @@ Installs an atomic, root-owned copy at `/usr/local/bin/pman` so later edits to t
|
||||
|
||||
### Interactive mode
|
||||
|
||||
```
|
||||
```text
|
||||
pman
|
||||
```
|
||||
|
||||
Displays a table of all VMs/containers. Enter a VMID to open the action menu.
|
||||
|
||||
```
|
||||
```text
|
||||
[+] running [-] stopped [~] paused [?] unknown
|
||||
```
|
||||
|
||||
@@ -180,21 +251,33 @@ pman --json | jq '.[] | select(.status == "running")'
|
||||
|
||||
### SPICE remote desktop
|
||||
|
||||
The SPICE integration generates a `.vv` connection file for any VM. If [`virt-viewer`](https://virt-manager.org/) is installed, it is launched automatically:
|
||||
The SPICE integration generates a `.vv` connection file for any VM. If
|
||||
[`virt-viewer`](https://virt-manager.org/) is installed, it is launched
|
||||
automatically:
|
||||
|
||||
```bash
|
||||
# Install virt-viewer (Debian / Proxmox host)
|
||||
apt install virt-viewer
|
||||
```
|
||||
|
||||
When `virt-viewer` is **not** installed, the path to the generated `.vv` file is printed together with the install hint. The SPICE bind address defaults to `127.0.0.1` and can be overridden via `PROXMOX_MANAGER_SPICE_ADDR` (env var or `~/.pmanrc`).
|
||||
When `virt-viewer` is **not** installed, the path to the generated `.vv` file is
|
||||
printed together with the install hint. The SPICE bind address defaults to
|
||||
`127.0.0.1` and can be overridden via `PROXMOX_MANAGER_SPICE_ADDR` (env var or
|
||||
`~/.pmanrc`).
|
||||
|
||||
### Health monitoring & alerts
|
||||
|
||||
`pman --health` shows every guest on the **local node** (templates skipped) with CPU, memory and
|
||||
disk usage, uptime and a health level; `--list` prints plain text, `--json` machine-readable
|
||||
data (`null` where a value is not available). The same data backs the `h` key in the TUI and
|
||||
the `Health:` line of the status action.
|
||||
`pman --health` shows every guest on the **local node** (templates skipped) with
|
||||
CPU, memory and disk usage, uptime and a health level; `--list` prints plain
|
||||
text, `--json` machine-readable data (`null` where a value is not available).
|
||||
The same data backs the `h` key in the TUI and the `Health:` line of the status
|
||||
action.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/screenshot-health.png"
|
||||
alt="pman --health: CPU, memory, disk, uptime and level per guest"
|
||||
width="720">
|
||||
</p>
|
||||
|
||||
`pman --check` is meant for cron. It evaluates:
|
||||
|
||||
@@ -202,7 +285,7 @@ the `Health:` line of the status action.
|
||||
|---|---|---|
|
||||
| CPU | WARN / CRIT | Must stay above the threshold for `HEALTH_CPU_RUNS` runs in a row |
|
||||
| Memory, disk | WARN / CRIT | Immediately. VM disk usage needs the QEMU guest agent, otherwise n/a |
|
||||
| _(guest stops)_ | — | CPU / memory / disk alerts of a stopped guest are resolved |
|
||||
| *(guest stops)* | — | CPU / memory / disk alerts of a stopped guest are resolved |
|
||||
| Stopped with `onboot=1` | CRIT | Configured to start at boot but not running (WARN if stopped by a task) |
|
||||
| Stopped unexpectedly | WARN | Was running at the last check; its latest task is no stop/shutdown/suspend/migrate/destroy/backup |
|
||||
| Failed task | WARN / CRIT | Any node task that ended not `OK` since the last run (`WARNINGS` → WARN) |
|
||||
@@ -214,16 +297,25 @@ Thresholds (percent; `0` disables that level):
|
||||
| `HEALTH_CPU_WARN` | 85 | `HEALTH_CPU_CRIT` | 95 |
|
||||
| `HEALTH_MEM_WARN` | 90 | `HEALTH_MEM_CRIT` | 95 |
|
||||
| `HEALTH_DISK_WARN` | 85 | `HEALTH_DISK_CRIT` | 95 |
|
||||
| `HEALTH_CPU_RUNS` | 3 | `HEALTH_IGNORE_IDS` | _(empty)_ e.g. `105,210` |
|
||||
| `HEALTH_CPU_RUNS` | 3 | `HEALTH_IGNORE_IDS` | *(empty)* e.g. `105,210` |
|
||||
|
||||
A notification is sent only when something changes: new or escalated problems, improvements and
|
||||
`RESOLVED` (with duration). All changes of one run go into one message. The first run only
|
||||
records a baseline, so old failed tasks are not reported. State is kept in `HEALTH_STATE_DIR`
|
||||
(default `/var/lib/pman`, mode `0700`); if every channel fails, the unsent changes stay pending and
|
||||
are sent by the next run. Exit codes: `0` OK · `1` WARN · `2` CRIT · `3` UNKNOWN (usage, config,
|
||||
lock or `pvesh` error) — the output is a Nagios-style summary line plus one line per problem.
|
||||
A notification is sent only when something changes: new or escalated problems,
|
||||
improvements and `RESOLVED` (with duration). All changes of one run go into one
|
||||
message. The first run only records a baseline, so old failed tasks are not
|
||||
reported. State is kept in `HEALTH_STATE_DIR` (default `/var/lib/pman`, mode
|
||||
`0700`); if every channel fails, the unsent changes stay pending and are sent by
|
||||
the next run. Exit codes: `0` OK · `1` WARN · `2` CRIT · `3` UNKNOWN (usage,
|
||||
config, lock or `pvesh` error) — the output is a Nagios-style summary line plus
|
||||
one line per problem.
|
||||
|
||||
**ntfy** — push to phone/desktop via [ntfy](https://ntfy.sh) (public or self-hosted):
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/screenshot-check.png"
|
||||
alt="pman --check: three memory warnings, RESOLVED minutes later"
|
||||
width="720">
|
||||
</p>
|
||||
|
||||
**ntfy** — push to phone/desktop via [ntfy](https://ntfy.sh) (public or
|
||||
self-hosted):
|
||||
|
||||
```bash
|
||||
# /etc/pmanrc
|
||||
@@ -235,9 +327,10 @@ install -d -m 700 /etc/pman
|
||||
install -m 600 /dev/null /etc/pman/ntfy.token && nano /etc/pman/ntfy.token
|
||||
```
|
||||
|
||||
The token file and its directory must not be writable by others; a token requires an `https://`
|
||||
URL (`http://` plus a token is a configuration error). **E-mail** uses the local `sendmail` (postfix, which PVE
|
||||
installs for its own notifications, works out of the box when it can relay):
|
||||
The token file and its directory must not be writable by others; a token
|
||||
requires an `https://` URL (`http://` plus a token is a configuration error).
|
||||
**E-mail** uses the local `sendmail` (postfix, which PVE installs for its own
|
||||
notifications, works out of the box when it can relay):
|
||||
|
||||
```bash
|
||||
# /etc/pmanrc
|
||||
@@ -245,22 +338,36 @@ HEALTH_MAIL_TO="admin@example.com" # comma separated, no spaces
|
||||
HEALTH_MAIL_FROM="pman@pve.example.com" # optional
|
||||
```
|
||||
|
||||
Test the channels, then add the cron job (set `PATH`, cron's default lacks `/usr/sbin`):
|
||||
Subject and body match the ntfy message (plain text, `Auto-Submitted:
|
||||
auto-generated`):
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/screenshot-mail.png"
|
||||
alt="pman WARN alert e-mail in a web mail client"
|
||||
width="720">
|
||||
</p>
|
||||
|
||||
If postfix cannot deliver directly, point it at a smarthost (`relayhost` in
|
||||
`/etc/postfix/main.cf`); `mailq` lists mail that is stuck in the queue.
|
||||
|
||||
Test the channels, then add the cron job (set `PATH`, cron's default lacks
|
||||
`/usr/sbin`):
|
||||
|
||||
```bash
|
||||
pman --test-notify
|
||||
pman --check --dry-run; echo "exit $?"
|
||||
```
|
||||
|
||||
```
|
||||
```text
|
||||
# /etc/cron.d/pman-health
|
||||
PATH=/usr/sbin:/usr/bin:/sbin:/bin
|
||||
*/5 * * * * root /usr/local/bin/pman --check >/dev/null 2>&1
|
||||
```
|
||||
|
||||
Limitations: a shutdown from **inside** a guest has no Proxmox task and is reported as
|
||||
"stopped unexpectedly"; in a cluster, run the cron job on **every node** (each checks only its own
|
||||
guests); failed tasks are read from the last 200 node tasks.
|
||||
Limitations: a shutdown from **inside** a guest has no Proxmox task and is
|
||||
reported as "stopped unexpectedly"; in a cluster, run the cron job on **every
|
||||
node** (each checks only its own guests); failed tasks are read from the last
|
||||
200 node tasks.
|
||||
|
||||
### Configuration
|
||||
|
||||
@@ -282,13 +389,17 @@ HEALTH_MEM_WARN=80 # health thresholds, see "Health monit
|
||||
NTFY_URL="https://ntfy.sh/pman-alerts-CHANGE-ME"
|
||||
```
|
||||
|
||||
Configuration files are parsed as data, not executed as shell code. Accepted keys:
|
||||
`STOP_TIMEOUT`, `LOG_FILE`, `PROXMOX_MANAGER_SPICE_ADDR`, `HEALTH_CPU_WARN`, `HEALTH_CPU_CRIT`,
|
||||
`HEALTH_MEM_WARN`, `HEALTH_MEM_CRIT`, `HEALTH_DISK_WARN`, `HEALTH_DISK_CRIT`, `HEALTH_CPU_RUNS`,
|
||||
`HEALTH_IGNORE_IDS`, `HEALTH_STATE_DIR`, `NTFY_URL`, `NTFY_TOKEN_FILE`, `HEALTH_MAIL_TO` and
|
||||
`HEALTH_MAIL_FROM`; anything else is ignored with a warning. Health settings are validated only
|
||||
by `--health`, `--check` and `--test-notify`, so a typo never blocks the TUI. Because the file
|
||||
may name alert targets, keep it private: `chmod 600 /etc/pmanrc`. When enabled, `LOG_FILE` must be an absolute, non-symlinked regular file owned by the current user with mode `0600`; its parent directory must also be owner-controlled and not group/world-writable.
|
||||
Configuration files are parsed as data, not executed as shell code. Accepted
|
||||
keys: `STOP_TIMEOUT`, `LOG_FILE`, `PROXMOX_MANAGER_SPICE_ADDR`,
|
||||
`HEALTH_CPU_WARN`, `HEALTH_CPU_CRIT`, `HEALTH_MEM_WARN`, `HEALTH_MEM_CRIT`,
|
||||
`HEALTH_DISK_WARN`, `HEALTH_DISK_CRIT`, `HEALTH_CPU_RUNS`, `HEALTH_IGNORE_IDS`,
|
||||
`HEALTH_STATE_DIR`, `NTFY_URL`, `NTFY_TOKEN_FILE`, `HEALTH_MAIL_TO` and
|
||||
`HEALTH_MAIL_FROM`; anything else is ignored with a warning. Health settings are
|
||||
validated only by `--health`, `--check` and `--test-notify`, so a typo never
|
||||
blocks the TUI. Because the file may name alert targets, keep it private: `chmod
|
||||
600 /etc/pmanrc`. When enabled, `LOG_FILE` must be an absolute, non-symlinked
|
||||
regular file owned by the current user with mode `0600`; its parent directory
|
||||
must also be owner-controlled and not group/world-writable.
|
||||
|
||||
### Shell Completions
|
||||
|
||||
@@ -305,11 +416,14 @@ cp completions/pman.zsh ~/.zsh/completions/_pman
|
||||
|
||||
## 🔐 Security
|
||||
|
||||
- **Root required:** `qm` and `pct` need elevated privileges — there's no workaround.
|
||||
- **Root required:** `qm` and `pct` need elevated privileges — there's no
|
||||
workaround.
|
||||
- **No credentials stored:** Relies entirely on Proxmox host authentication.
|
||||
- **No outbound traffic unless notifications are configured:** alerts via ntfy / e-mail are opt-in;
|
||||
the ntfy token is read from a `0600` file, passed to `curl` via stdin and never sent over plain http.
|
||||
- **CI hardening:** ShellCheck on every push · Gitleaks scan for accidental secrets.
|
||||
- **No outbound traffic unless notifications are configured:** alerts via ntfy /
|
||||
e-mail are opt-in; the ntfy token is read from a `0600` file, passed to `curl`
|
||||
via stdin and never sent over plain http.
|
||||
- **CI hardening:** ShellCheck on every push · Gitleaks scan for accidental
|
||||
secrets.
|
||||
|
||||
---
|
||||
|
||||
@@ -317,8 +431,8 @@ cp completions/pman.zsh ~/.zsh/completions/_pman
|
||||
|
||||
### 🆕 [v2.13.0](CHANGELOG.md) — 2026-09-19
|
||||
|
||||
> Health view (`--health`, key `h`) · `--check` for cron with ntfy / e-mail alerts on changes ·
|
||||
> exit codes 0/1/2/3 · `--test-notify`
|
||||
> Health view (`--health`, key `h`) · `--check` for cron with ntfy / e-mail
|
||||
> alerts on changes · exit codes 0/1/2/3 · `--test-notify`
|
||||
|
||||
### [v2.12.1](CHANGELOG.md) — 2026-09-19
|
||||
|
||||
@@ -347,7 +461,8 @@ cp completions/pman.zsh ~/.zsh/completions/_pman
|
||||
|
||||
### [v2.9.0](CHANGELOG.md) — 2026-04-09
|
||||
|
||||
> `--filter STATUS` · `--timeout SECS` with force-stop fallback · `--force` mode · 29 unit tests · Bash & Zsh shell completions
|
||||
> `--filter STATUS` · `--timeout SECS` with force-stop fallback · `--force` mode
|
||||
> · 29 unit tests · Bash & Zsh shell completions
|
||||
|
||||
**→ [View full CHANGELOG](CHANGELOG.md)**
|
||||
|
||||
@@ -363,9 +478,9 @@ shellcheck proxmox-manager.sh
|
||||
tests/run.sh
|
||||
```
|
||||
|
||||
131 tests covering `validate_vmid`, `validate_snapshot_name`, `ip_info`, `--filter`, CLI flags, config
|
||||
parsing, the health view, the `--check` engine and notifications (mocked `pvesh`, `curl`, `sendmail`;
|
||||
no network, no root).
|
||||
131 tests covering `validate_vmid`, `validate_snapshot_name`, `ip_info`,
|
||||
`--filter`, CLI flags, config parsing, the health view, the `--check` engine and
|
||||
notifications (mocked `pvesh`, `curl`, `sendmail`; no network, no root).
|
||||
|
||||
---
|
||||
|
||||
@@ -378,7 +493,8 @@ Contributions welcome — keep it simple, keep it Bash.
|
||||
3. Commit with conventional format: `feat(vm): add suspend action`
|
||||
4. Open a Pull Request.
|
||||
|
||||
**Do not commit:** generated files, scan outputs, binary files, or large test data.
|
||||
**Do not commit:** generated files, scan outputs, binary files, or large test
|
||||
data.
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 58 KiB |
|
After Width: | Height: | Size: 104 KiB |
|
After Width: | Height: | Size: 140 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 463 KiB |
|
Before Width: | Height: | Size: 168 KiB After Width: | Height: | Size: 117 KiB |