mirror of
https://github.com/TimInTech/proxmox-manager.git
synced 2026-11-20 19:22:53 +03:00
docs: redesign READMEs and fix website anchors
This commit is contained in:
1 parent
34045b8784
commit
ed889e53d0
4 files changed
+939
-679
No files matched your search
@@ -125,7 +125,7 @@ jobs:
|
||||
for needle in ('HEALTH_CPU_RUNS', 'cat >/etc/cron.d/pman-health', '--filter running'):
|
||||
if needle not in guide:
|
||||
sys.exit(f'guide lost command: {needle}')
|
||||
for anchor in ('id="-installation"', 'id="health-monitoring--alerts"',
|
||||
for anchor in ('id="installation"', 'id="health-monitoring--alerts"',
|
||||
'id="relaying-through-an-external-smtp-provider"'):
|
||||
if anchor not in guide:
|
||||
sys.exit(f'guide lost anchor: {anchor}')
|
||||
|
||||
+526
-117
@@ -1,161 +1,570 @@
|
||||
# Proxmox Manager
|
||||
|
||||
**Sprache: [English](README.md) | Deutsch**
|
||||
Virtuelle Maschinen und LXC-Container auf Proxmox VE im Terminal verwalten.
|
||||
|
||||
Proxmox Manager verwaltet Proxmox-VMs und -Container mit einem eigenständigen
|
||||
Bash-Skript. Die optionale Speicher- und Wartungsoberfläche verwendet Python 3
|
||||
und die Standardbibliothek; der Bash-Kern kann ohne sie installiert werden. Die
|
||||
vollständige Befehls- und Konfigurationsreferenz steht im [englischen README](README.md).
|
||||
Proxmox Manager (`pman`) bietet interaktive Gastverwaltung, skriptfähige
|
||||
Inventarausgaben und Zustandsprüfungen auf dem lokalen Proxmox-Knoten. Der
|
||||
Bash-Kern nutzt die mit Proxmox VE gelieferten Werkzeuge und läuft bei Bedarf.
|
||||
Ein optionales Python-Modul ergänzt Speicherdiagnosen und Host-Wartung.
|
||||
|
||||
**Geplant für v2.14.1:** Fehlermeldungen bei Inventarabfragen, authentifizierte
|
||||
SPICE-Verbindungen und Korrekturen der Eingabebehandlung im Wartungsmodul.
|
||||
Siehe [Changelog](CHANGELOG.md).
|
||||
[](https://github.com/TimInTech/proxmox-manager/actions/workflows/ci.yml)
|
||||
[](https://github.com/TimInTech/proxmox-manager/actions/workflows/gitleaks.yml)
|
||||
[](LICENSE)
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/demo/out/proxmox-manager-demo.gif" alt="Proxmox Manager Live Demo" width="820">
|
||||
</p>
|
||||
[English](README.md) · Deutsch
|
||||
|
||||
<p align="center">
|
||||
<em>Deterministische, lesende Konsolen-Demo: VM/CT-Übersicht, Health-Diagnose, Host-Wartung & Helper-Scripts (Community).</em><br>
|
||||
<small>Headless PTY-Pipeline mit In-Stream-Pseudonymisierung · <a href="docs/demo/index.html">Interaktiver Web-Vektor-Player ▶</a> · <a href="docs/demo/README.md">Pipeline-Details →</a></small>
|
||||
</p>
|
||||

|
||||
|
||||
## Community & Tutorials
|
||||
Lesende Aufzeichnung: Inventar, Zustandsübersicht, Host-Wartung und die
|
||||
Bestätigung eines Community-Skripts mit Quellcode-Vorschau. Es werden keine
|
||||
Wartungsänderungen ausgeführt.
|
||||
[Lokaler interaktiver Player](docs/demo/index.html) ·
|
||||
[Details zur Aufzeichnung](docs/demo/README.md). Den Player aus einem lokalen
|
||||
Checkout als HTML-Datei öffnen; GitHub zeigt den Quelltext an.
|
||||
|
||||
Externe Veröffentlichungen über `proxmox-manager`:
|
||||
[Installation](#installation) · [Nutzung](#nutzung) ·
|
||||
[Zustandsprüfung & Alarme](#zustandsprüfung--alarme) ·
|
||||
[Konfiguration](#konfiguration) · [Wartung](#optionale-wartung)
|
||||
|
||||
- **[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/)**
|
||||
Anleitung und Vorstellung von askomputer.pl mit Beispielen und Screenshots (Polnisch).
|
||||
- **[Stop Wrestling Proxmox GUIs: Meet the Single-Bash TUI That Changes Everything](https://prompts.brightcoding.dev/blog/stop-wrestling-proxmox-guis-meet-the-single-bash-tui-that-changes-everything)**
|
||||
Überblick von Bright Coding über Installation, TUI und VM-/Container-Verwaltung (Englisch).
|
||||
- **[This Lightweight Proxmox Tool Makes CLI Management Faster](https://www.virtualizationhowto.com/2026/05/this-lightweight-proxmox-tool-makes-cli-management-faster/)**
|
||||
Praxistest von Brandon Lee zu Installation, VM-/LXC-Verwaltung, Snapshots,
|
||||
Konsolenzugriff und Einsatz im Homelab (Englisch).
|
||||
## Funktionen
|
||||
|
||||
- **Gastverwaltung.** VMs und Container auflisten, starten, herunterfahren und
|
||||
neu starten; Konsolen öffnen, IPv4-Adressen abfragen und Snapshots verwalten.
|
||||
- **Zustandsprüfung.** CPU, Arbeitsspeicher, Speicherplatz und Laufzeit je Gast
|
||||
mit einstellbaren Schwellenwerten und Alarmen über ntfy oder E-Mail.
|
||||
- **Automatisierung.** Inventar als Klartext oder JSON, Status- und Namensfilter,
|
||||
Nagios-kompatible Exit-Codes und optionale strukturierte Protokolle.
|
||||
- **SPICE-Zugriff.** QXL-Anzeige konfigurieren und authentifizierte
|
||||
`.vv`-Verbindungsdateien über den Proxmox-Proxy anfordern.
|
||||
- **Optionale Wartung.** Speicher-, Dateisystem- und SMART-Diagnosen,
|
||||
gastbezogene Wartung und ausgewählte Proxmox VE Helper-Scripts der Community.
|
||||
|
||||
## Installation
|
||||
|
||||
Auf einem Proxmox-Host als Administrator aus einem passenden Checkout:
|
||||
Als **root auf dem Proxmox-VE-Knoten** ausführen. Das Projekt richtet sich an
|
||||
PVE 7.x, 8.x und 9.x. Der Kern benötigt Bash 4 oder neuer, `qm`, `pct`, `pvesh`
|
||||
und Python 3; diese gehören zu PVE. Für das Klonen wird zusätzlich Git benötigt.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/TimInTech/proxmox-manager.git
|
||||
cd proxmox-manager
|
||||
./install_dependencies.sh
|
||||
./install_dependencies.sh --without-maintenance
|
||||
pman
|
||||
```
|
||||
|
||||
Der Installer fragt interaktiv nach dem optionalen Modul und installiert ohne
|
||||
Terminal standardmäßig nur den Kern. Zur ausdrücklichen Installation des Moduls:
|
||||
Der Installer legt atomar eine root-eigene Kopie unter `/usr/local/bin/pman`
|
||||
ab. Spätere Änderungen am Checkout verändern das installierte Programm nicht.
|
||||
Er installiert keine APT-Pakete, optionalen Anzeigeprogramme oder
|
||||
Entwicklungswerkzeuge.
|
||||
|
||||
Der Kern lässt sich auch direkt aus dem Checkout starten:
|
||||
|
||||
```bash
|
||||
./install_dependencies.sh --with-maintenance
|
||||
bash proxmox-manager.sh
|
||||
```
|
||||
|
||||
### Wartungsmodul hinzufügen
|
||||
|
||||
Das Modul benötigt Python 3.9 oder neuer mit `curses` und ein UTF-8-Terminal.
|
||||
Es verwendet ausschließlich die Python-Standardbibliothek.
|
||||
|
||||
```bash
|
||||
./install_dependencies.sh --with-maintenance --lang de
|
||||
pman --maintenance
|
||||
```
|
||||
|
||||
Die Oberfläche gibt es auf Deutsch (Standard) und Englisch. Im Terminal fragt der
|
||||
Installer zuerst (`Language / Sprache [de/en]`); ohne Terminal gibst du
|
||||
`--lang en` oder `--lang de` an. Die Wahl steht in `/etc/pman/language` und bleibt bei
|
||||
Updates erhalten; `PMAN_LANG=en pman --maintenance` überschreibt sie für einen Lauf.
|
||||
Ohne `--with-maintenance` oder `--without-maintenance` fragt der Installer im
|
||||
interaktiven Terminal nach; ohne Terminal installiert er nur den Kern.
|
||||
Die Wartungsoberfläche unterstützt Deutsch (Standard) und Englisch. Wenn keiner
|
||||
der beiden Modulparameter übergeben wird, fragt der Installer bei der ersten
|
||||
interaktiven Installation auch nach der Sprache.
|
||||
`--lang de|en` legt sie ausdrücklich in `/etc/pman/language` fest; Updates
|
||||
erhalten diese Wahl. `PMAN_LANG=de pman --maintenance` überschreibt sie für
|
||||
einen Aufruf.
|
||||
|
||||
Der Installer installiert keine zusätzlichen APT-Pakete. Für die Oberfläche ist
|
||||
Python 3.9 oder neuer mit `curses` sowie ein UTF-8-Terminal erforderlich.
|
||||
|
||||
## Wartungsoberfläche
|
||||
|
||||
`M` oder `m` öffnet im Hauptmenü die Host-Wartung; im Aktionsmenü eines Gastes
|
||||
öffnet dieselbe Taste die Wartung für genau den gewählten CT oder die VM.
|
||||
Pfeiltasten wählen eine Aktion, Enter startet eine Diagnose oder öffnet Details.
|
||||
Bild auf/ab blättert die Ausgabe, Esc führt zurück oder bricht eine Bestätigung
|
||||
ab, und `q` beendet die
|
||||
Ansicht. `Tab` wechselt beim CT den Scanpfad. Die Anzeige passt sich dem Terminal
|
||||
an und berücksichtigt `NO_COLOR`.
|
||||
|
||||
**Host-Wartungsmenü**
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/screenshot-maintenance-menu.png"
|
||||
alt="Host-Wartungsmenü des Proxmox Managers mit Speicher-, SMART- und TRIM-Diagnosen"
|
||||
width="720">
|
||||
</p>
|
||||
|
||||
Die eigenen Adapter zeigen unter anderem Storage, Dateisysteme und SMART-Daten.
|
||||
CT und VM bieten ausschließlich auf den gewählten Gast bezogene Diagnosen und
|
||||
bestätigungspflichtiges TRIM; für Debian-/Ubuntu-CTs ist auch eine Bereinigung
|
||||
des APT-Paketcache verfügbar. Gestoppte Gäste werden nicht automatisch gestartet.
|
||||
Jede Änderung verlangt eine eigene Bestätigung; `--force` umgeht sie nicht.
|
||||
Ein Abbruch laufender Änderungen ist kein Rollback.
|
||||
|
||||
Das Host-Menü enthält außerdem die **Proxmox VE Helper-Scripts (Community)**
|
||||
(<https://community-scripts.org>, MIT-Lizenz, Repository
|
||||
`community-scripts/ProxmoxVE`). Acht ausgewählte Werkzeuge laufen als fremder
|
||||
Code, der weder von pman noch von Proxmox stammt, mit eigenen interaktiven
|
||||
Dialogen; sie können Host-Einstellungen oder dort ausgewählte Gäste ändern. Die
|
||||
Werkzeuge sind nach Absicht gruppiert, und jedes trägt seine Gefahrenstufe als
|
||||
Text: `[LESEN]` (Diagnose; Disk Health installiert nur auf Nachfrage Pakete), `[ÄNDERT]` (verändert Host oder Gäste) oder
|
||||
`[LÖSCHT]` (entfernt Daten oder Pakete, kein Papierkorb); Farbe ist nur ein
|
||||
zusätzlicher Hinweis. Vor dem Bestätigungsschirm prüft das Modul den aktuellen
|
||||
Upstream und lädt die festgelegte Revision herunter. Der Schirm zeigt die genaue
|
||||
Quell-URL, den Befehl, den Hinweis „läuft als root auf diesem Host“ sowie
|
||||
Revision und Prüfsumme. Mit `v` lässt sich das geprüfte Skript ansehen; nach `j`
|
||||
werden genau diese Bytes gestartet. Die Prüfung wird unmittelbar vor dem Start
|
||||
wiederholt. Geänderte, fehlende oder nicht erreichbare Quellen verhindern den
|
||||
Start; die Meldung nennt dann die Datei sowie geprüfte und aktuelle Revision.
|
||||
Die Prüfung und die Downloads können bei Zeitlimits im ungünstigsten Fall etwa
|
||||
eine Minute dauern; die Oberfläche ist währenddessen blockiert. Die optionale
|
||||
Upstream-Telemetrie wird nicht bereitgestellt. Auswirkungen vor der Bestätigung
|
||||
sorgfältig prüfen.
|
||||
|
||||
Darstellung: `NO_COLOR=1` schaltet jede Farbe ab, `PMAN_ASCII=1` ersetzt Linien-
|
||||
und Pfeilzeichen durch ASCII (automatisch auch bei `TERM=linux`), und
|
||||
`PMAN_HYPERLINKS=1|0` erzwingt klickbare OSC-8-Links oder schaltet sie ab (die
|
||||
URL steht immer auch als Klartext da).
|
||||
|
||||
Bekannte Grenzen: Ein UTF-8-Terminal wird benötigt. Ein laufender CT-Scan kann
|
||||
bis zu 55 Sekunden weiterlaufen, auch wenn die Oberfläche den Abbruch angefordert
|
||||
hat. Community-Helper zeigen eigene Dialoge und ihre erneute Live-Quellprüfung
|
||||
kann während der Netzwerkanfrage kurzzeitig die Oberfläche blockieren. Ein
|
||||
Abbruch ist kein Rollback. Details stehen in [docs/maintenance.md](docs/maintenance.md).
|
||||
|
||||
## Deinstallation des Moduls
|
||||
Die Modulinstallation aktiviert normalerweise einen täglichen systemd-Timer,
|
||||
der öffentliche Quellenmetadaten prüft. Mit `--no-source-timer` wird er nicht
|
||||
aktiviert. Ein bereits aktiver Timer lässt sich so abschalten:
|
||||
|
||||
```bash
|
||||
./install_dependencies.sh --uninstall-maintenance
|
||||
systemctl disable --now pman-maintenance-sources.timer
|
||||
```
|
||||
|
||||
Der Bash-Kern bleibt installiert; private Diagnosezustände bleiben erhalten. Für
|
||||
den Rückweg auf die vorherige Modulversion nutze im passenden Checkout:
|
||||
Bedienung, Quellenprüfung, Rollback und Deinstallation sind unter
|
||||
[optionale Wartung](#optionale-wartung) beschrieben.
|
||||
|
||||
## Nutzung
|
||||
|
||||
### Interaktive Verwaltung
|
||||
|
||||
`pman` starten und die VMID eines Gastes eingeben, um dessen Aktionsmenü zu
|
||||
öffnen. `h` zeigt die Zustandsübersicht, `r` aktualisiert und `q` beendet die
|
||||
Ansicht. `M` oder `m` öffnet die optionale Wartung: im Hauptmenü für den Host,
|
||||
im Aktionsmenü für den ausgewählten Gast.
|
||||
|
||||
```text
|
||||
[+] running [-] stopped [~] paused [?] unknown
|
||||
```
|
||||
|
||||
| Gastinventar | Gastaktionen |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|
||||
Die Screenshots zeigen Beispielansichten. Versionsangaben und Ausgaben können
|
||||
vom aktuellen Checkout abweichen.
|
||||
|
||||
Stop fordert ein geordnetes Herunterfahren über `qm shutdown` oder
|
||||
`pct shutdown` an.
|
||||
Erst nach Ablauf des eingestellten Zeitlimits (standardmäßig 60 Sekunden)
|
||||
erzwingt Proxmox den Stopp. Destruktive Kernaktionen verlangen eine Bestätigung;
|
||||
Fehlermeldungen enthalten Proxmox-Details. Vor Rollback und Löschen wird der
|
||||
ausgewählte Snapshot angezeigt.
|
||||
|
||||
Container-Konsolen verwenden `pct enter`, VM-Konsolen `qm terminal` und eine
|
||||
eingerichtete serielle Konsole; als Rückfall dient `qm monitor`. Beide benötigen
|
||||
einen laufenden Gast.
|
||||
IPv4-Abfragen nutzen `pct exec` bei Containern und den QEMU Guest Agent bei VMs.
|
||||
|
||||
### Befehlsreferenz
|
||||
|
||||
| Befehl | Zweck |
|
||||
| --- | --- |
|
||||
| `pman` | Interaktive Gasttabelle mit Aktionsmenüs öffnen. |
|
||||
| `pman --list` | Inventar als Klartext ausgeben. |
|
||||
| `pman --json` | Inventar als JSON-Array ausgeben. |
|
||||
| `pman --list --filter running` | Nach `running`, `stopped` oder `paused` filtern. |
|
||||
| `pman --list --name 'web\|db'` | Namen mit einem erweiterten regulären Ausdruck filtern; mit `--filter` kombinierbar. |
|
||||
| `pman --health` | Zustand lokaler Gäste anzeigen; mit `--list` oder `--json` sowie Namens- und Statusfiltern kombinierbar. |
|
||||
| `pman --check` | Zustand prüfen und Änderungen melden; Exit-Code `0` OK, `1` WARN, `2` CRIT, `3` UNKNOWN. |
|
||||
| `pman --check --dry-run` | Ergebnis und vorgesehene Meldung anzeigen, ohne Versand oder Speicherung des Zustands. |
|
||||
| `pman --test-notify` | Testnachricht über alle eingerichteten Benachrichtigungskanäle senden. |
|
||||
| `pman --maintenance` | Optionale Host-Wartungsoberfläche öffnen. |
|
||||
| `pman --timeout 30` | Zeitlimit in Sekunden bis zum erzwungenen Stopp beim Herunterfahren setzen. |
|
||||
| `pman --force` | Unterstützte Kernbestätigungen überspringen; Wartungsbestätigungen bleiben verpflichtend. |
|
||||
| `pman --no-clear` | Terminalinhalt zwischen interaktiven Ansichten erhalten. |
|
||||
| `pman --once` | Einen interaktiven Aktualisierungszyklus ausführen, etwa für Aufzeichnungen. |
|
||||
| `pman --version` | Version des Kerns ausgeben. |
|
||||
| `pman --help` | Hilfe anzeigen; `-h` ist gleichbedeutend. |
|
||||
|
||||
`--list` und `--json` sind alternative Ausgabeformate. `--check` prüft immer
|
||||
alle lokalen Gäste und akzeptiert weder Namens- und Statusfilter noch andere
|
||||
Ausgabeformate. Auch `--maintenance` läuft getrennt von Inventar- und
|
||||
Zustandsansichten.
|
||||
|
||||
### JSON-Inventar
|
||||
|
||||
```bash
|
||||
pman --json
|
||||
```
|
||||
|
||||
Beispielausgabe:
|
||||
|
||||
```json
|
||||
[
|
||||
{"id": 100, "type": "VM", "status": "running", "symbol": "[+]", "name": "web-server"},
|
||||
{"id": 101, "type": "CT", "status": "stopped", "symbol": "[-]", "name": "db-container"}
|
||||
]
|
||||
```
|
||||
|
||||
Der eingebaute Filter erhält die Array-Struktur. Für weitere Umwandlungen lässt
|
||||
sich `jq` separat installieren:
|
||||
|
||||
```bash
|
||||
pman --json --filter running
|
||||
pman --json | jq '.[] | select(.status == "running")'
|
||||
```
|
||||
|
||||
Fehlschläge bei Inventarabfragen liefern einen Exit-Code ungleich null statt
|
||||
eines vermeintlich erfolgreichen leeren oder unvollständigen Ergebnisses.
|
||||
|
||||
### SPICE-Remotedesktop
|
||||
|
||||
**SPICE info** fordert für eine laufende VM mit QXL-Anzeige eine
|
||||
authentifizierte `.vv`-Verbindungsdatei über die Proxmox-API `spiceproxy` an.
|
||||
Dazu werden `pvesh` und Python 3 verwendet. Wenn `remote-viewer` installiert ist
|
||||
und eine grafische Sitzung besteht, startet pman das Programm automatisch.
|
||||
Unter Debian wird das Paket so installiert:
|
||||
|
||||
```bash
|
||||
apt install virt-viewer
|
||||
```
|
||||
|
||||
Andernfalls gibt pman den Pfad der privaten Verbindungsdatei aus. Diese zeitnah
|
||||
mit `remote-viewer` auf einem Desktop öffnen, der den Proxmox-Proxy auf TCP 3128
|
||||
erreichen kann. Die Datei enthält ein kurzlebiges Ticket und
|
||||
TLS-Vertrauensinformationen; ungenutzte Dateien löschen.
|
||||
`PROXMOX_MANAGER_SPICE_ADDR` bestimmt den vom Client erreichbaren Hostnamen
|
||||
oder die IP-Adresse des Proxys, nicht die Bind-Adresse der VM.
|
||||
|
||||
**Enable SPICE** setzt den VGA-Typ auf QXL und erhält benannte
|
||||
VGA-Eigenschaften sowie vorhandene QXL-Mehrmonitor-Einstellungen. Die Änderung
|
||||
der Anzeigehardware erfordert ein vollständiges Herunterfahren und Starten;
|
||||
pman startet die VM nicht automatisch neu.
|
||||
|
||||
## Zustandsprüfung & Alarme
|
||||
|
||||
`pman --health` zeigt CPU, Arbeitsspeicher, Speicherplatz, Laufzeit und
|
||||
Zustandsstufen der Gäste auf dem **lokalen Knoten**; Templates werden
|
||||
ausgelassen. `--list` liefert Klartext, `--json` maschinenlesbare Daten mit
|
||||
`null` für nicht verfügbare Werte. Dieselben Daten erscheinen unter `h` und in
|
||||
der Statusaktion eines Gastes.
|
||||
|
||||

|
||||
|
||||
### Benachrichtigungen einrichten
|
||||
|
||||
Die folgenden Schritte nach der Installation von `pman` als root ausführen.
|
||||
|
||||
1. Mindestens einen Kanal in einer privaten `/etc/pmanrc` einrichten. Den
|
||||
Topic-Namen durch einen eigenen, schwer zu erratenden Namen ersetzen: Wer
|
||||
den Namen eines öffentlichen ntfy-Topics kennt, kann es lesen. Für
|
||||
Zugriffsschutz ein geschütztes Topic mit Token-Datei verwenden; siehe
|
||||
[Benachrichtigungskanäle](#benachrichtigungskanäle).
|
||||
|
||||
```bash
|
||||
touch /etc/pmanrc
|
||||
chmod 600 /etc/pmanrc
|
||||
cat >>/etc/pmanrc <<'EOF'
|
||||
NTFY_URL="https://ntfy.sh/pman-alerts-CHANGE-ME"
|
||||
# HEALTH_MAIL_TO="admin@example.com"
|
||||
EOF
|
||||
```
|
||||
|
||||
2. Das Topic in der [ntfy-App](https://ntfy.sh/docs/subscribe/phone/) oder unter
|
||||
`https://ntfy.sh/<dein-topic>` abonnieren, anschließend den Versand testen
|
||||
und einen Probelauf prüfen. E-Mail erst aktivieren, wenn der Versand über
|
||||
das lokale `sendmail` funktioniert. Der Test verwendet alle eingerichteten
|
||||
Kanäle und gilt als erfolgreich, sobald mindestens einer funktioniert;
|
||||
Fehler einzelner Kanäle werden gemeldet.
|
||||
|
||||
```bash
|
||||
pman --test-notify
|
||||
pman --check --dry-run; echo "exit $?"
|
||||
```
|
||||
|
||||
3. Alle fünf Minuten prüfen lassen. Cron benötigt einen ausdrücklich gesetzten
|
||||
`PATH`, der `/usr/sbin` enthält.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Der erste Lauf legt den Ausgangsstand für die Aufgabenhistorie an; bestehende
|
||||
Zustandsprobleme der Gäste können bereits Alarme auslösen. Spätere Läufe melden
|
||||
neue oder verschärfte Probleme, Verbesserungen und `RESOLVED` einschließlich
|
||||
Dauer. Alle Änderungen eines Laufs werden in einer Nachricht zusammengefasst.
|
||||
|
||||
### Prüfungen und Schwellenwerte
|
||||
|
||||
| Prüfung | Stufe | Verhalten |
|
||||
| --- | --- | --- |
|
||||
| CPU | WARN / CRIT | Der erste Alarm erfordert `HEALTH_CPU_RUNS` aufeinanderfolgende Läufe. |
|
||||
| Arbeitsspeicher, Speicherplatz | WARN / CRIT | Sofort; die Speicherplatzmessung bei VMs benötigt den QEMU Guest Agent. |
|
||||
| Gast stoppt | — | Hebt dessen CPU-, Arbeitsspeicher- und Speicherplatzalarme auf. |
|
||||
| Gestoppt mit `onboot=1` | CRIT | WARN, wenn eine Proxmox-Aufgabe den Stopp erklärt. |
|
||||
| Unerwarteter Stopp | WARN | Zuvor laufend, ohne erklärende Stop-, Shutdown-, Suspend-, Migrate-, Destroy- oder Backup-Aufgabe. |
|
||||
| Fehlgeschlagene Knotenaufgabe | WARN / CRIT | Seit der letzten Prüfung erfolglos beendet; `WARNINGS` ergibt WARN. |
|
||||
|
||||
Schwellenwerte sind Prozentangaben; `0` deaktiviert die jeweilige Stufe.
|
||||
|
||||
| Einstellung | Standard | Einstellung | Standard |
|
||||
| --- | --- | --- | --- |
|
||||
| `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` | Leer; z. B. `105,210` |
|
||||
|
||||
Der Zustand wird in `HEALTH_STATE_DIR` gespeichert (Standard `/var/lib/pman`,
|
||||
Modus `0700`). Scheitern alle eingerichteten Kanäle, bleiben ungesendete
|
||||
Änderungen für den nächsten Lauf vorgemerkt. Die Ausgabe besteht aus einer
|
||||
Nagios-kompatiblen Zusammenfassung und einer Zeile pro Problem. Exit-Codes:
|
||||
`0` OK, `1` WARN, `2` CRIT und `3` UNKNOWN. Aufruf-, Konfigurations-, Sperr-
|
||||
und `pvesh`-Fehler führen im Prüfmodus zu UNKNOWN.
|
||||
|
||||

|
||||
|
||||
Ein im Gast ausgelöstes Herunterfahren erzeugt keine Proxmox-Aufgabe und wird
|
||||
als unerwarteter Stopp gemeldet. In Clustern die Prüfung auf jedem Knoten
|
||||
planen; jeder prüft nur seine lokalen Gäste. Die Erkennung fehlgeschlagener
|
||||
Aufgaben berücksichtigt die letzten 200 Knotenaufgaben.
|
||||
|
||||
### Benachrichtigungskanäle
|
||||
|
||||
Für öffentliches oder selbst gehostetes [ntfy](https://ntfy.sh) wird
|
||||
`NTFY_URL` gesetzt. Geschützte Topics können `NTFY_TOKEN_FILE` verwenden;
|
||||
das Token gehört nicht in die `pmanrc`:
|
||||
|
||||
```bash
|
||||
# /etc/pmanrc
|
||||
NTFY_URL="https://ntfy.sh/pman-alerts-CHANGE-ME"
|
||||
NTFY_TOKEN_FILE="/etc/pman/ntfy.token"
|
||||
```
|
||||
|
||||
Eine private Token-Datei anlegen und das Token im Editor eintragen:
|
||||
|
||||
```bash
|
||||
install -d -m 700 /etc/pman
|
||||
install -m 600 /dev/null /etc/pman/ntfy.token
|
||||
nano /etc/pman/ntfy.token
|
||||
```
|
||||
|
||||
Token-Datei und Verzeichnis dürfen nicht durch andere beschreibbar sein.
|
||||
Die Token-Authentifizierung erfordert HTTPS; eine HTTP-URL mit Token ist ein
|
||||
Konfigurationsfehler.
|
||||
|
||||
E-Mail nutzt das lokale `sendmail`, beispielsweise Postfix mit funktionierendem
|
||||
Relay-Versand. Empfänger werden ohne Leerzeichen durch Kommas getrennt;
|
||||
der Absender ist optional:
|
||||
|
||||
```bash
|
||||
# /etc/pmanrc
|
||||
HEALTH_MAIL_TO="admin@example.com"
|
||||
HEALTH_MAIL_FROM="pman@pve.example.com"
|
||||
```
|
||||
|
||||
Beide Kanäle verwenden denselben Nachrichtentext. E-Mails werden als Klartext
|
||||
mit `Auto-Submitted: auto-generated` versendet.
|
||||
|
||||
| ntfy-Benachrichtigung | E-Mail-Benachrichtigung |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|
||||
### Versand über einen externen SMTP-Anbieter
|
||||
|
||||
Hosts ohne direkten Mailversand benötigen einen Smarthost, etwa wenn Port 25
|
||||
gesperrt ist oder eine dynamische IP-Adresse abgelehnt wird. Dieses Beispiel
|
||||
richtet Postfix für Gmail-Submission auf Port 587 ein. Andere Anbieter können
|
||||
abweichende Authentifizierung, Absendervorgaben und Serveradressen erfordern.
|
||||
`you@example.com` durch das eigene Konto ersetzen. Gmail-App-Passwörter hängen
|
||||
von den Kontovoraussetzungen ab; siehe
|
||||
[Googles Anleitung zu App-Passwörtern](https://support.google.com/accounts/answer/185833).
|
||||
|
||||
SASL-Unterstützung installieren und das App-Passwort ohne Leerzeichen eingeben.
|
||||
Die interaktive Eingabe verhindert, dass es im Shell-Verlauf steht:
|
||||
|
||||
```bash
|
||||
apt install libsasl2-modules
|
||||
umask 077
|
||||
read -rsp "App-Passwort: " PMAN_SMTP_PASSWORD; echo
|
||||
printf '[smtp.gmail.com]:587 you@example.com:%s\n' "$PMAN_SMTP_PASSWORD" >/etc/postfix/sasl_passwd
|
||||
unset PMAN_SMTP_PASSWORD
|
||||
postmap /etc/postfix/sasl_passwd
|
||||
chmod 600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
|
||||
```
|
||||
|
||||
Verschlüsselten Versand einrichten und den Envelope-Absender auf das
|
||||
authentifizierte Konto umschreiben:
|
||||
|
||||
```bash
|
||||
postconf -e "relayhost = [smtp.gmail.com]:587" \
|
||||
"smtp_sasl_auth_enable = yes" \
|
||||
"smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd" \
|
||||
"smtp_sasl_security_options = noanonymous" \
|
||||
"smtp_sasl_tls_security_options = noanonymous" \
|
||||
"smtp_tls_security_level = encrypt" \
|
||||
"smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt" \
|
||||
"sender_canonical_classes = envelope_sender" \
|
||||
"sender_canonical_maps = regexp:/etc/postfix/sender_canonical"
|
||||
echo '/.+/ you@example.com' >/etc/postfix/sender_canonical
|
||||
echo 'root: you@example.com' >>/etc/aliases
|
||||
newaliases
|
||||
systemctl restart postfix
|
||||
```
|
||||
|
||||
Der root-Alias leitet auch Proxmox-Benachrichtigungen an root in dieses
|
||||
Postfach weiter. Scheitert der IPv6-Versand mit
|
||||
`Network is unreachable`, `postconf -e "inet_protocols = ipv4"` setzen und
|
||||
Postfix neu starten. Versand prüfen:
|
||||
|
||||
```bash
|
||||
pman --test-notify
|
||||
journalctl -t postfix/smtp -n 5 --no-pager
|
||||
mailq
|
||||
```
|
||||
|
||||
Auf `status=sent` und eine leere Warteschlange achten. Auf Systemen ohne
|
||||
`/var/log/mail.log` das Journal verwenden. Die Fehler `535 5.7.8` oder
|
||||
`534 5.7.9` weisen auf ein Authentifizierungsproblem hin; App-Passwort und
|
||||
Kontovoraussetzungen prüfen. Gmail kann die From-Adresse umschreiben; nach
|
||||
Betreff filtern oder eine Empfängeradresse wie `you+pman@example.com` nutzen.
|
||||
|
||||

|
||||
|
||||
## Konfiguration
|
||||
|
||||
Einstellungen werden in dieser Reihenfolge geladen: Umgebung und Standardwerte,
|
||||
`/etc/pmanrc`, `~/.pmanrc`, dann CLI-Optionen. Spätere Werte haben Vorrang.
|
||||
|
||||
```bash
|
||||
# ~/.pmanrc
|
||||
STOP_TIMEOUT=120
|
||||
LOG_FILE="/var/log/proxmox-manager.log"
|
||||
PROXMOX_MANAGER_SPICE_ADDR="spice.example.invalid"
|
||||
HEALTH_MEM_WARN=80
|
||||
NTFY_URL="https://ntfy.sh/pman-alerts-CHANGE-ME"
|
||||
```
|
||||
|
||||
Dateien werden als Daten eingelesen, niemals als Shell-Code ausgeführt.
|
||||
Zulässige Schlüssel:
|
||||
|
||||
| Gruppe | Schlüssel |
|
||||
| --- | --- |
|
||||
| Kern | `STOP_TIMEOUT`, `LOG_FILE`, `PROXMOX_MANAGER_SPICE_ADDR` |
|
||||
| Schwellenwerte | `HEALTH_CPU_WARN`, `HEALTH_CPU_CRIT`, `HEALTH_MEM_WARN`, `HEALTH_MEM_CRIT`, `HEALTH_DISK_WARN`, `HEALTH_DISK_CRIT` |
|
||||
| Prüfzustand | `HEALTH_CPU_RUNS`, `HEALTH_IGNORE_IDS`, `HEALTH_STATE_DIR` |
|
||||
| Benachrichtigungen | `NTFY_URL`, `NTFY_TOKEN_FILE`, `HEALTH_MAIL_TO`, `HEALTH_MAIL_FROM` |
|
||||
|
||||
Unbekannte Schlüssel werden mit einer Warnung ignoriert. Die Zustandsoptionen
|
||||
werden durch `--health`, `--check` und `--test-notify` validiert; Fehler darin
|
||||
blockieren die Gastverwaltung nicht. Dateien privat halten, beispielsweise mit
|
||||
`chmod 600 /etc/pmanrc`.
|
||||
|
||||
Bei leerem `LOG_FILE` ist die Protokollierung deaktiviert. Andernfalls muss der
|
||||
Pfad absolut sein und auf eine reguläre Datei ohne Symlink verweisen, die dem
|
||||
aktuellen Benutzer gehört und den Modus `0600` hat. Auch das übergeordnete
|
||||
Verzeichnis muss vom Eigentümer kontrolliert und für Gruppe und andere nicht
|
||||
beschreibbar sein. Die vollständige Proxmox-Fehlerausgabe steht im Protokoll;
|
||||
im Terminal erscheint die erste Zeile.
|
||||
|
||||
### Shell-Vervollständigung
|
||||
|
||||
```bash
|
||||
# Bash, systemweit
|
||||
cp completions/pman.bash /etc/bash_completion.d/pman
|
||||
|
||||
# Zsh
|
||||
mkdir -p ~/.zsh/completions
|
||||
cp completions/pman.zsh ~/.zsh/completions/_pman
|
||||
```
|
||||
|
||||
Bei Zsh `~/.zsh/completions` vor dem Aufruf von `compinit` in `fpath` aufnehmen.
|
||||
|
||||
## Optionale Wartung
|
||||
|
||||
Die Wartungsoberfläche zeigt Speicher-, Dateisystem- und SMART-Informationen
|
||||
des Hosts. Gastdiagnosen und Änderungen beziehen sich auf die ausgewählte VM
|
||||
oder den Container, darunter bestätigungspflichtiges TRIM und die Bereinigung
|
||||
des APT-Cache bei Debian-/Ubuntu-Containern. Eigene Gastaktionen starten keine
|
||||
gestoppten Gäste. Jede Änderung erfordert eine Bestätigung; `--force` kann sie
|
||||
nicht umgehen.
|
||||
|
||||

|
||||
|
||||
Pfeiltasten wählen eine Aktion, Enter öffnet sie. Bild auf/ab blättert die
|
||||
Ausgabe, Esc führt zurück oder bricht eine Bestätigung ab, und `q` beendet die
|
||||
Ansicht. `Tab` wechselt das CT-Scanverzeichnis. Die Anzeige passt sich der
|
||||
Terminalgröße an:
|
||||
|
||||
| Umgebungsvariable | Wirkung |
|
||||
| --- | --- |
|
||||
| `NO_COLOR=1` | Farben abschalten. |
|
||||
| `PMAN_ASCII=1` | ASCII-Linien und -Pfeile verwenden; automatisch bei `TERM=linux`. |
|
||||
| `PMAN_HYPERLINKS=1` oder `0` | OSC-8-Links erzwingen oder abschalten; URLs erscheinen auch als Klartext. |
|
||||
| `PMAN_LANG=de` oder `en` | Installierte Wartungssprache für einen Aufruf überschreiben. |
|
||||
|
||||
### Community-Helper-Skripte
|
||||
|
||||
Das Host-Menü enthält acht ausgewählte **Proxmox VE Helper-Scripts (Community)**
|
||||
aus [community-scripts/ProxmoxVE](https://github.com/community-scripts/ProxmoxVE)
|
||||
([Projektwebsite](https://community-scripts.org), MIT-Lizenz). Dies ist fremder
|
||||
Code, der getrennt von pman und Proxmox gepflegt wird. Die Helper haben eigene
|
||||
interaktive Dialoge und können den Host oder darin ausgewählte Gäste ändern.
|
||||
|
||||
Die Werkzeuge sind nach Zweck gruppiert und mit `[LESEN]`, `[ÄNDERT]` oder
|
||||
`[LÖSCHT]` gekennzeichnet (auf Englisch `[READ]`, `[CHANGE]`, `[DELETE]`).
|
||||
Disk Health kann nach eigener Rückfrage auch Pakete installieren. Beim Löschen
|
||||
gibt es keinen Papierkorb.
|
||||
|
||||
Vor der Bestätigung prüft pman die aktuelle Upstream-Quelle und lädt die
|
||||
festgelegte Revision herunter. Die Bestätigung zeigt Quell-URL, Befehl,
|
||||
Root-Ausführungshinweis, Revision und Prüfsumme. `v` zeigt das geprüfte Skript,
|
||||
`j` startet genau diese Bytes. Die Prüfung wird unmittelbar vor dem Start
|
||||
wiederholt. Geänderte, fehlende oder nicht erreichbare Quellen verhindern die
|
||||
Ausführung; die Meldung nennt Datei sowie geprüfte und aktuelle Revision.
|
||||
Die optionale Upstream-Telemetrie wird nicht bereitgestellt.
|
||||
|
||||
Ein abgebrochener CT-Scan kann im Gast bis zu seinem Zeitlimit von 55 Sekunden
|
||||
weiterlaufen. Quellenprüfungen und Downloads können die Oberfläche während der
|
||||
Netzwerk-Zeitlimits etwa eine Minute blockieren. Ein Abbruch laufender
|
||||
Änderungen macht diese nicht rückgängig. Die
|
||||
[Wartungsdokumentation](docs/maintenance.md) beschreibt den Funktionsumfang,
|
||||
Quellenprüfungen und Betriebsgrenzen.
|
||||
|
||||
### Rollback und Deinstallation
|
||||
|
||||
Aus einem Checkout lässt sich zur zuvor installierten Modulversion
|
||||
zurückwechseln oder ausschließlich das optionale Modul entfernen:
|
||||
|
||||
```bash
|
||||
./install_dependencies.sh --rollback-maintenance
|
||||
```
|
||||
|
||||
## Tests
|
||||
```bash
|
||||
./install_dependencies.sh --uninstall-maintenance
|
||||
```
|
||||
|
||||
Auf einem Entwicklungsrechner ohne Proxmox-Host laufen die Mock- und TUI-Tests
|
||||
mit:
|
||||
Beide Vorgänge erhalten den Bash-Kern. Bei der Deinstallation bleiben auch die
|
||||
Cron-Konfiguration der Zustandsprüfung und private Diagnosezustände erhalten.
|
||||
|
||||
## Sicherheit
|
||||
|
||||
Der Kern läuft als root mit der Proxmox-Authentifizierung des Hosts; separate
|
||||
Proxmox-API-Zugangsdaten oder ein pman-Daemon werden nicht benötigt. Gastagenten
|
||||
sind für bestimmte Metriken und VM-IP-Abfragen erforderlich, nicht für die
|
||||
grundlegende Inventarisierung und Verwaltung.
|
||||
|
||||
Benachrichtigungen sind optional. Das Wartungsmodul kann öffentliche
|
||||
Quellendienste kontaktieren, festgelegte Helper-Versionen herunterladen und
|
||||
den täglichen Metadaten-Timer ausführen. ntfy-Tokens werden aus privaten Dateien
|
||||
gelesen, über stdin an `curl` übergeben und nur mit HTTPS verwendet.
|
||||
SPICE-Verbindungsdateien enthalten temporäre Authentifizierungstickets.
|
||||
|
||||
Die CI umfasst ShellCheck, Mock-Tests und Gitleaks-Prüfungen. Schwachstellen
|
||||
gemäß [SECURITY.md](SECURITY.md) melden.
|
||||
|
||||
## Community & Tutorials
|
||||
|
||||
Externe Artikel über das Projekt; Befehle und Screenshots können ältere
|
||||
Versionen beschreiben.
|
||||
|
||||
- [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/)
|
||||
— askomputer.pl. Polnische Installations- und Nutzungsanleitung mit Screenshots.
|
||||
- [Stop Wrestling Proxmox GUIs: Meet the Single-Bash TUI That Changes Everything](https://prompts.brightcoding.dev/blog/stop-wrestling-proxmox-guis-meet-the-single-bash-tui-that-changes-everything)
|
||||
— Bright Coding. Englischer Überblick zu Installation und Gastverwaltung.
|
||||
- [This Lightweight Proxmox Tool Makes CLI Management Faster](https://www.virtualizationhowto.com/2026/05/this-lightweight-proxmox-tool-makes-cli-management-faster/)
|
||||
— Brandon Lee, Virtualization Howto. Englischer Praxistest zu
|
||||
VM-/LXC-Verwaltung, Snapshots, Konsolen und Homelab-Nutzung.
|
||||
|
||||
## Entwicklung
|
||||
|
||||
Lokale Tests verwenden Mocks und benötigen weder einen Proxmox-Host noch
|
||||
Aktionen an echten Gästen:
|
||||
|
||||
```bash
|
||||
python3 -B -m unittest discover -s tests/maintenance
|
||||
shellcheck proxmox-manager.sh
|
||||
bash tests/run.sh
|
||||
bash tests/test_inventory.sh
|
||||
bash tests/test_spice.sh
|
||||
python3 -B -m unittest discover -s tests/maintenance -v
|
||||
```
|
||||
|
||||
Die echten Proxmox-Aktionen brauchen einen Testhost. Siehe [Wartungsdokumentation](docs/maintenance.md).
|
||||
Sie prüfen CLI-Verarbeitung, Konfiguration, Inventar, Snapshots, SPICE,
|
||||
Zustandsprüfungen, Benachrichtigungen und das optionale Wartungsmodul.
|
||||
Entwicklungswerkzeuge separat installieren. Vorgaben zu Stil, Tests und Pull
|
||||
Requests stehen in [CONTRIBUTING.md](CONTRIBUTING.md); außerdem gilt der
|
||||
[Code of Conduct](CODE_OF_CONDUCT.md). Laufzeitabhängigkeiten auf Host-Werkzeuge
|
||||
und die Python-Standardbibliothek begrenzen; keine generierten Berichte oder
|
||||
großen Testartefakte einchecken.
|
||||
|
||||
## Weitere Nutzung
|
||||
Für Fehlerberichte und Funktionsdiskussionen die
|
||||
[Issues](https://github.com/TimInTech/proxmox-manager/issues) nutzen.
|
||||
Versionshistorie und die in diesem Checkout enthaltenen, noch nicht
|
||||
veröffentlichten Änderungen für 2.14.1 stehen im [CHANGELOG.md](CHANGELOG.md).
|
||||
|
||||
`pman` öffnet die VM-/CT-Tabelle, `pman --list` und `pman --json` geben den
|
||||
Bestand aus. `pman --health` zeigt den Zustand und `pman --check` führt den
|
||||
optionalen Alarm-Check aus. Konfiguration, Befehle und Beispiele erläutert das
|
||||
[englische README](README.md). Lizenz: [MIT](LICENSE).
|
||||
## Lizenz
|
||||
|
||||
### SPICE
|
||||
|
||||
„Enable SPICE“ setzt den VGA-Typ auf QXL und erhält benannte VGA-Eigenschaften.
|
||||
Vorhandene QXL-Mehrmonitor-Konfigurationen bleiben erhalten. Die Änderung benötigt
|
||||
ein vollständiges Herunterfahren und Starten; pman startet die VM nicht automatisch neu.
|
||||
„SPICE info“ fordert für eine laufende VM mit QXL eine authentifizierte `.vv`-Datei
|
||||
über die Proxmox-API an. `remote-viewer` (Paket `virt-viewer`) öffnet sie bei
|
||||
vorhandener grafischer Sitzung. Der Desktop muss den Proxy auf TCP 3128 erreichen.
|
||||
`PROXMOX_MANAGER_SPICE_ADDR` bezeichnet dessen erreichbaren Hostnamen oder IP,
|
||||
nicht eine VM-Bind-Adresse. Die private Datei enthält ein kurzlebiges Ticket;
|
||||
zeitnah öffnen und ungenutzte Dateien löschen.
|
||||
[MIT](LICENSE). Gepflegt von [TimInTech](https://github.com/TimInTech).
|
||||
[Projekt unterstützen](https://buymeacoffee.com/timintech).
|
||||
@@ -39,6 +39,14 @@ md.renderer.rules.heading_open = (tokens, idx, options, env, self) => {
|
||||
}
|
||||
return renderToken ? renderToken(tokens, idx, options, env, self) : self.renderToken(tokens, idx, options);
|
||||
};
|
||||
const renderLink = md.renderer.rules.link_open;
|
||||
md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
|
||||
const href = tokens[idx].attrGet('href');
|
||||
if (env.prefix && href?.startsWith('#')) {
|
||||
tokens[idx].attrSet('href', `#${env.prefix}${href.slice(1)}`);
|
||||
}
|
||||
return renderLink ? renderLink(tokens, idx, options, env, self) : self.renderToken(tokens, idx, options);
|
||||
};
|
||||
const render = (text, prefix = '') => md.render(prepare(text), { prefix });
|
||||
const sections = [...english.matchAll(/^## (.+)$/gm)].map((match, i, all) => ({
|
||||
title: match[1],
|
||||
|
||||
Reference in new issue
Block a user