Files
==TIM.©.B ==andClaude Sonnet 5.5 c9168107c8 feat(maintenance): Sprachwahl Deutsch/Englisch bei der Installation (gestapelt auf #50) (#51)
* feat(maintenance): German/English display language, chosen at installation

German source text is the catalog key and English comes from catalog_en.py, so a
missing entry falls back to German. The installer asks 'Language / Sprache' in a
terminal or takes --lang de|en and stores the choice in /etc/pman/language;
PMAN_LANG overrides it per run. Persisted source-check statuses stay language
neutral and are translated on display. Tests check catalog completeness,
placeholder parity, the installer flow (including the interactive prompt) and
English golden snapshots. Module version 1.0.5.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(maintenance): parenthesise the 'last checked' fallback in the source report

The stored check time was concatenated before the 'or' fallback, so an empty
state raised TypeError instead of showing 'not checked yet'. Regression test
covers both languages.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(installer): avoid A && B || C in the language handling (SC2015)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* fix(installer): validate the language file directory before install, rollback and removal

A staged uninstall followed an etc/pman symlink and deleted a language file
outside --destdir. The directory chain is now checked with the other
destinations before any operation.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-07 01:07:21 +01:00

9.9 KiB
Raw Permalink Blame History

Optional storage and maintenance module

The pman core remains a standalone Bash file. The optional module runs on the Proxmox host using Python 3.9+ and its standard curses library. It installs no software inside guests and uses no pip packages. The existing health cron is not changed.

Install and start

From the matching repository checkout or unpacked release bundle:

./install_dependencies.sh --with-maintenance
pman --maintenance

The display language is German (default) or English. Interactive installation asks Language / Sprache [de/en] first (once; an existing choice is kept), noninteractive installation takes --lang de|en. The installer writes the choice to /etc/pman/language (root-owned, removed by --uninstall-maintenance). The environment variable PMAN_LANG=de|en overrides the file for one run. Without either, the module uses German. A text without an English translation is shown in German instead of failing; stored source-check results stay language neutral.

Interactive installation asks about the module, defaulting to No. Without a terminal, installation defaults to the core. --without-maintenance installs the core and leaves an existing module alone. The installer performs no apt package installation. If SMART support is missing, the UI explains that smartmontools is optional and must be installed by the administrator.

From the main menu, press m for host maintenance. From a VM/CT action menu, press m to open maintenance for exactly that guest. The module can also run independently:

pman-maintenance --scope ct --id 101
pman-maintenance --scope vm --id 100
pman-maintenance --scope host --report storage
pman-maintenance --scope ct --id 101 --report volumes --json

Use arrow keys to select, Enter to open, Page Up/Down to move by one visible page, and Esc to cancel/back. The output pane shows its current line range. q exits on a fresh shell line. CT directory scans use Tab to select /var, /home, /opt, or /srv; the scan stays within the selected filesystem. Resizing and NO_COLOR=1 are supported. A UTF-8 terminal is required; the module restores a UTF-8 locale even when the Bash core runs with LC_ALL=C.

Available actions

Scope Diagnostics Confirmed changes
Host Storage/filesystems/inodes, LVM thin pools and metadata, ZFS if installed, SMART history, TRIM schedules/logs, kernel packages, backup storage None
CT Configured volumes resolved through pvesm path, filesystem/inode use, bounded directory scans pct fstrim ID; Debian/Ubuntu apt-get clean
VM Configured disks/storage/discard, filesystem information via QEMU Guest Agent Guest-agent TRIM on recognised Linux distributions

CT/VM operations verify the selected guest and running state immediately before execution. Guests are never automatically started. Missing commands, an inactive QEMU Guest Agent and unsupported guest operating systems are reported as unavailable. VM filesystem output can include read-only filesystems at 100%; it is diagnostic information and is not automatically interpreted as an alarm.

SMART output presents the overall health, temperature and power-on hours, plus common error counters. Vendor-specific raw fields are not presented as standardized measurements. The provenance view summarizes source status and shows abbreviated reviewed/upstream commits.

The UI shows the target, exact command and impact before a change. Only j confirms it; the core's --force does not bypass this. Cancelling a running change is not a rollback. A cancelled CT directory scan may continue inside the guest until its independent 55-second timeout; the outer command is also bounded. Changes are serialized by a private lock. There is no unattended mutation CLI.

The interface separates the action list from its detail or confirmation view. At smaller widths the list is stacked; below the minimum size, actions are blocked until the terminal is resized. While a job runs, Esc or q requests cancellation and other input is ignored; after cancellation, q exits.

The host menu also has Proxmox VE Helper-Scripts (Community) (https://community-scripts.org; repository community-scripts/ProxmoxVE, MIT licence, "Copyright (c) 2021-2026 tteck | community-scripts ORG"). It offers eight selected Host Management tools in three groups:

Group Tool Level
Prüfen & Sichern Disk Health (installs packages only if you agree) [LESEN]
Prüfen & Sichern Host Backup [ÄNDERT]
Aktualisieren & Optimieren LXC Updater, LXC Filesystem Trim, CPU Scaling Governor [ÄNDERT]
Aufräumen – löscht Daten Kernel Clean, LXC Cleaner, Clean Orphaned LVM [LÖSCHT]

The level is always written out; colour (fixed 256-colour badge pairs with a contrast of at least 4.5:1, none under NO_COLOR) is only an additional cue. This is third-party code that runs as root on the host; its own interactive prompts and target selection remain intact.

Before the confirmation screen, pman checks the live GitHub metadata for the tool and its core library, downloads only the reviewed commit and verifies the Git blob SHA-1. The screen shows the exact source URL, the command, the "runs as root on this host" notice, the pinned revisions and checksum and the impact. v opens the verified script (read only); after j exactly these bytes are executed, following a second metadata check. A changed, missing or unreachable upstream source blocks the start; the message names the file and the reviewed and current revision. The menu header shows the last stored source check (from the daily timer, no network access when opening the menu) and marks affected tools with !. With network timeouts the checks and downloads can block the interface for up to about one minute. The core runtime library is pinned and checked as well. Its optional telemetry API is intentionally omitted. A helper can still install packages, delete selected logs/volumes, change host settings or update guests as described in its impact text; pman asks for a separate confirmation before starting it.

Display environment variables: NO_COLOR=1 (no colour), PMAN_ASCII=1 (ASCII glyphs instead of box and arrow characters; automatic for TERM=linux, vt100, vt220) and PMAN_HYPERLINKS=1|0 (force OSC 8 links on or off). The URL is always shown as plain text; links are only added in terminals known to support them (VTE 0.50+, kitty, iTerm2, WezTerm, Windows Terminal, foot, VS Code) and never inside tmux or screen unless forced.

TRIM reports unused blocks to lower storage layers. Its reported byte count is not a guarantee of newly available pool space. Guest filesystem use, thin-volume allocation and pool data/metadata use are displayed separately. Volume names are read from the actual guest configuration, not guessed from the VMID.

The native adapters do not offer broad log deletion, kernel removal, backup deletion or filesystem/partition reconfiguration. Some community helpers do offer log or kernel removal and other changes, as described above.

Community Scripts provenance and freshness

The standard maintenance actions are independent local implementations using native commands. maintenance/sources.json records their references and the reviewed Community tools, commits, Git blob checksums and upstream licence. The UI's provenance view exposes these details and the last source-check result. Only the eight tools listed above are launchable; other category entries are not exposed as arbitrary shell commands.

The installed pman-maintenance-sources.timer runs daily with random delay. It requests public GitHub directory listings containing file metadata, not script contents. It compares file blob hashes with the reviewed manifest, including launchable tools and their pinned Core dependency. ETag requests reduce traffic. No credentials, guest data or SMART history are sent. Results include timestamps and one of: geprüfter Stand, Upstream geändert, Quelle fehlt, or Prüfung fehlgeschlagen. A failed network/API request never means "up to date". A missing file triggers review, not an automatic search for a replacement URL.

pman-maintenance --check-sources
pman-maintenance --sources
systemctl disable --now pman-maintenance-sources.timer

To install without enabling the timer:

./install_dependencies.sh --with-maintenance --no-source-timer

A manually disabled timer stays disabled on upgrades. To re-enable it explicitly:

systemctl enable --now pman-maintenance-sources.timer

An upstream change is a review signal. Code and reviewed checksums are updated only in a new module release after compatibility review; checksums are an integrity identifier, not a security assessment. Ordinary maintenance actions work offline. The core's existing opt-in notification networking is separate.

Updates, rollback and removal

Use a reviewed matching checkout/release and rerun the installation command. Packages are root-owned under /usr/local/lib/pman/maintenance/releases/; current switches atomically and previous supports rollback. The isolated Python launcher ignores PYTHONPATH and checks ownership and write permissions. An incompatible interface is rejected by the core.

./install_dependencies.sh --rollback-maintenance
./install_dependencies.sh --uninstall-maintenance

Removal stops/removes only the module and its source-check service/timer. It retains the core, health configuration and private diagnostic state under /var/lib/pman-maintenance (SMART baseline and source-check cache).

Release assets include the core, installer, optional module bundle and SHA256SUMS. The bundle contains its matching core and installer for deployment. Verify downloaded assets against the release checksums before installation. For development, run python3 -I -B maintenance/launcher.py --interface or start the same launcher as root on a Proxmox test host. --destdir stages installation files without touching services; it is intended for packaging/tests.