tesm/README.md

TESM

Verwaltung von PoE-Geraeten und Aruba-Switchen: Inventar, Zustandsueberwachung, Portsteuerung, Neustart (PoE, SSH, RPC), DHCP ueber Kea, Dateifreigaben, Wartung ueber SSH, Protokolle, Papierkorb, verschluesselte Ein- und Ausfuhr und ein SSH-Terminal im Browser.

Der Lizenzserver liegt in einem eigenen Repository: alientim/tesm-license. Beide teilen sich den Kern (packages/tesm-core) und das Lizenzprotokoll (packages/tesm-licensing); diese Pakete sind hier mit enthalten, damit sich das Repository allein installieren laesst.

Zweige

Zweig	Inhalt
main	dieser Neubau (Version 2.0.0)
SONNET5	der Stand davor, unveraendert aufbewahrt

---

Installation auf einem Server

sudo bash deploy/install.sh --app tesm --https
sudo -u tesm tesm-admin create-admin

Danach https://<host>/. Ohne --domain entsteht ein selbstsigniertes Zertifikat; der Browser warnt einmal, die Verbindung ist verschluesselt.

Mit oeffentlichem Namen und Let's Encrypt stattdessen:

sudo bash deploy/install.sh --app tesm --https --domain tesm.firma.de --acme-email it@firma.de

Zielzustand: Port 443 mit TLS, Port 80 leitet dorthin um -- ausser dem ACME-Pfad, der erreichbar bleiben muss, sonst kann Let's Encrypt nie erneuern.

Sitzt ein eigener Reverse Proxy davor, der TLS beendet, laeuft TESM ohne --https schlicht auf Port 80.

Eine zweite Installation zum Testen stoert die laufende nicht:

sudo bash deploy/install.sh --app tesm --instance test --port 5100 --http-port 8080

Jede Instanz bekommt eigene Datenbank, eigene Schluessel, eigene nginx-Site und ein eigenes Sitzungscookie.

Aktualisieren

sudo bash deploy/update.sh --app tesm

Das laedt ein Release, entpackt es und ruft dessen install.sh auf. Vor jedem Update entsteht ein vollstaendiges Backup -- unabhaengig davon, ob sich das Schema geaendert hat -- und danach laeuft ein Health-Check mit automatischem Rollback.

---

Release bauen

git tag -a v2.0.0 -m "TESM 2.0.0" && git push origin v2.0.0
bash deploy/release.sh v2.0.0

Heraus kommt tesm-v2.0.0.tar.gz samt SHA-256. Der Name kommt aus dem Repository, nicht aus einer festen Zeichenkette.

---

Entwicklung

python -m venv .venv && . .venv/bin/activate
pip install -e packages/tesm-licensing -e packages/tesm-core -e apps/tesm
pip install pytest
pytest tests -q

Ohne gesetzte Umgebungsvariablen legt die Anwendung ihre Daten unter instance/tesm/ im Arbeitsverzeichnis an -- kein Zugriff auf /srv oder /var/log noetig.

TESM_DEBUG=1 flask --app tesm run

Im Debug-Modus wird COOKIE_SECURE abgeschaltet, sonst kaeme das Sitzungscookie ueber http://127.0.0.1 nie an.

---

Verwaltung von der Kommandozeile

sudo -u tesm tesm-admin status              # Zustand der Installation
sudo -u tesm tesm-admin create-admin        # Konto anlegen oder zuruecksetzen
sudo -u tesm tesm-admin check-now           # Ueberwachungsdurchlauf sofort
sudo -u tesm tesm-admin housekeeping        # Sitzungen und Protokolle aufraeumen
sudo -u tesm tesm-admin web-setup --https   # nginx und TLS einrichten

Umzug aus dem alten TESM

Ein Export des Vorgaengers laesst sich uebersetzen und dann ueber den normalen Import einlesen -- Clients, Switche, Zugangsdaten und die DHCP-Konfiguration:

tesm-admin convert-legacy tesm_export_20260813_195455.json --dry-run

--dry-run zeigt nur den Bericht. Ohne die Option entsteht eine Datei im neuen Format, die unter Verwaltung -> Sicherung eingelesen wird. Der Bericht nennt ausdruecklich, was nicht uebersetzt werden kann (lokale Konten, Rechte, Verzeichnisdienst, Webserver) -- das ist von Hand nachzuziehen.

Die Passphrase gehoert an die verdeckte Eingabeaufforderung. --passphrase existiert nur fuer Automatisierung: es schreibt sie in Shell-Historie und Prozessliste.

---

Dokumentation

docs/ARCHITEKTUR.md	Aufbau, Schnitte und die Gruende dafuer
docs/SICHERHEIT.md	Anmeldung, Sitzungen, CSRF, Geheimnisse, Rechtetrennung
docs/BETRIEB.md	Installation, Update, HTTPS, Sicherung, Fehlersuche

---

Tests

pytest tests -q

Dazu ein Skript, das auf dem Zielhost gegen die laufende Installation spricht -- ueber nginx, gunicorn und echtes TLS. Es wird nicht mitinstalliert (install.sh laesst tests/ aus); bei Bedarf dorthin kopieren. Jeder Lauf legt eigene Datensaetze an, ist also beliebig oft wiederholbar:

python3 tests/e2e_smoke.py https://host admin 'Passwort'

---

Was diese Fassung anders macht

Ein Neubau. Die Fehler des Vorgaengers sind bekannt; an den Stellen, an denen sie entstanden sind, steht jetzt ein Kommentar, der erklaert, warum es hier anders geloest ist. Die wichtigsten:

• Kein root fuer die Anwendung. Ein einziger allowlisted Helfer mit Argumentpruefung statt eines Webprozesses als root.
• CSRF-Schutz ueberhaupt. Der Vorgaenger hatte keinen.
• Rechte werden serverseitig geprueft, nicht nur im Template ausgeblendet.
• Die nginx-Site wird bei jedem Lauf inhaltlich verglichen und erneuert. Ein falscher alias-Pfad ueberlebte im Vorgaenger jahrelang jedes Update.
• Kein Hostname im Lizenz-Fingerabdruck. Umbenennen brach die Bindung.
• Zwei Installationen stoeren sich nicht -- eigener SITE_KEY fuer nginx-Site, netplan, logrotate, Zertifikate und Sitzungscookie.
• Verschachtelte Datenbankverbindungen sind ein Fehler, kein Deadlock.
• Jede Konfiguration wird vor dem Uebernehmen geprueft -- nginx wie Kea. Eine fehlerhafte Datei faellt beim Schreiben auf, nicht erst beim naechsten Start des Dienstes.