Basis aus 2nd-brain für LPIC-Prüfungsvorbereitung übernommen

Regeln, Standards, Kontextstruktur und Werkzeuge übernommen; 2nd-brain- Inhalte (Stacks, Ansible-Inventar, Architektur, Knowledge) entfernt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 21:56:53 +01:00
commit 7f6b8ebe07
@@ -0,0 +1,16 @@
+# ai/context/ – Kontext & Knowledge-DB
+
+> **Für wen, wo, womit.** Datenklassen beachten: hier höchstens „intern“ (`rules/privacy.md`). Geheimnisse nie.
+
+| Datei | Inhalt | Lesen |
+|---|---|---|
+| [responsible.md](responsible.md) | Verantwortliche – **Quelle für `@author`/`@owner`** in Headern | immer |
+| [style.md](style.md) | Zielgruppe, Ansprache, Ton, Ausführlichkeit | immer |
+| [environment.md](environment.md) | Infrastruktur-Überblick + zentrale Werte (Secret-Store, Logging, Domains) | immer |
+| [knowledge/](knowledge/README.md) | Knowledge-DB: Systeme, Netz, Dienste, Entscheidungen, Anleitungen, Recherchen | gezielt über `INDEX.md` |
+
+Ziel und Stand des Projekts: [`../../context.md`](../../context.md).
+
+## Pflege
+- Überblicksdateien (`*.md` hier) kurz halten (≤ 1 Bildschirmseite); Details gehören in die Knowledge-DB und werden verlinkt.
+- Änderungen mit Datum (`> Stand: TT.MM.JJJJ`). Widersprüche zwischen Überblick und Knowledge: Knowledge gilt, Überblick korrigieren.
@@ -0,0 +1,33 @@
+# Umgebung – Überblick & zentrale Werte
+
+> Stand: 29.10.2026 · Klasse: intern · Details je System/Dienst in der Knowledge-DB (`knowledge/`).
+> Werte hier sind die **Platzhalter-Auflösung** für die Standards in `ai/common/` (`<VAULT_ADDR>`, `<GELF_HOST>` …).
+
+## Zentrale Werte
+| Platzhalter | Bedeutung | Wert | Knowledge |
+|---|---|---|---|
+| `<VAULT_ADDR>` | Secret-Store (HashiCorp Vault o. ä.) | <!-- TODO --> | <!-- services/… --> |
+| `<projekt>` (KV-Pfad) | Pfadpräfix im Secret-Store | <!-- TODO --> | |
+| `<GELF_HOST>` / Port | zentrales Logging (Graylog, GELF/UDP) | `192.168.218.122` / `12201` | |
+| `<STACK_BASE>` | Basisverzeichnis Docker-Stacks | `/docker` (eigenes LV, btrfs, Label `DOCKER`) | |
+| `TRAEFIK_NETWORK` / `TRAEFIK_CERTRESOLVER` | Reverse Proxy | <!-- TODO --> | |
+| `<STANDARDHOST>` | Default-Ziel für Ansible (Lab-VM) | <!-- TODO: Lab-VM festlegen --> | |
+| `<ANSIBLE_USER>` | SSH-Benutzer für Ansible | `nafvoyr` (sudo) | |
+| Domains intern/extern | DNS | <!-- TODO --> | <!-- network/… --> |
+
+## Topologie (Kurzfassung)
+- **Standort A – Keller:** `kellerbeast` – GPU-Compute (Ollama, faster-whisper), TrueNAS ZFS.
+- **Standort B – Cloud-RZ:** Docker-VMs (Compose, Ansible).
+- **Verbindung:** NetBird-Mesh zwischen Standorten und Clients.
+
+## Werkzeuge
+| Bereich | Werkzeug | Ort | Status |
+|---|---|---|---|
+| Git-Server | Gitea (self-hosted, **vertrauenswürdig**) – Remote dieses Repos: <!-- TODO: z. B. `ssh://git@git.everdc.eu:10022/br/lpic.git` anlegen --> | eigener Server | in Betrieb |
+| Secret-Store | HashiCorp Vault (Auto-Unseal) | `vp.chmln.de` | in Betrieb |
+| Logging | Graylog (GELF) | `192.168.218.122:12201/udp` | in Betrieb |
+| Reverse Proxy | Traefik | <!-- TODO: Host(s) --> | in Betrieb |
+| Monitoring | Checkmk | <!-- TODO: Host --> | <!-- TODO --> |
+| Backup | Borgmatic → ZFS / Proxmox Backup Server | `kellerbeast` | geplant |
+| VPN | NetBird | Mesh | geplant/in Betrieb? |
+| Messenger | Mattermost | <!-- TODO: Host --> | <!-- TODO --> |
@@ -0,0 +1,10 @@
+# Knowledge-Index
+
+> Automatisch erzeugt von `bin/kb_index.sh` – nicht von Hand bearbeiten.
+> Format der Einträge: [README.md](README.md)
+
+## services
+
+| id | Titel | Status | Stand | Tags |
+|---|---|---|---|---|
+| sultan | [sultan – verteiltes Ingress-Routing für Traefik (Eigenentwicklung)](services/sultan.md) | active | 2026-10-23 | traefik, ingress, docker, netbird, checkmk, eigenentwicklung |
@@ -0,0 +1,43 @@
+# Knowledge-DB (Markdown)
+
+> Dauerhaftes Wissen über Umgebung und Projekt – eine Datei pro Eintrag, Metadaten im YAML-Frontmatter,
+> Übersicht in [`INDEX.md`](INDEX.md) (erzeugt von `bin/kb_index.sh`, nicht von Hand bearbeiten).
+
+## Ablage
+| Ordner | `type` | Inhalt | Beispiel |
+|---|---|---|---|
+| `systems/` | `system` | Hosts, VMs, Geräte (Server, Switch, AP, Firewall) | `systems/host01.md` |
+| `network/` | `network` | Netze, VLANs, IP-Pläne, DNS-Zonen, VPN, Routing | `network/ip_plan.md` |
+| `services/` | `service` | Dienste/Anwendungen (DNS, RADIUS, Backup, Mail) | `services/dns_resolver.md` |
+| `decisions/` | `decision` | ADRs – Entscheidungen mit Begründung | `decisions/adr_0001_secret_store.md` |
+| `howto/` | `howto` | Anleitungen, Runbooks, wiederkehrende Handgriffe | `howto/restore_backup.md` |
+| `research/` | `research` | Recherchen mit Quellen und Datum | `research/wifi_controller_vergleich.md` |
+| `topics/` | `topic` | Lerninhalte je LPIC-Prüfungsthema (Objective-Nummer im `id`) | `topics/lpic1_103_1_command_line.md` |
+
+Dateiname = `id` + `.md` (Englisch/ASCII, klein, `_`). ADRs: `adr_NNNN_<slug>`.
+
+## Frontmatter (Schlüssel englisch, Werte in Amtssprache)
+```yaml
+---
+id: host01                      # Pflicht, eindeutig, = Dateiname ohne .md
+title: Virtualisierungshost 1   # Pflicht
+type: system                    # Pflicht: system|network|service|decision|howto|research|topic
+status: active                  # Pflicht: draft|active|deprecated|superseded
+updated: 2026-10-07             # Pflicht, ISO
+owner: br                       # Pflicht: Kürzel aus ../responsible.md
+tags: [proxmox, server]         # optional
+sources: []                     # optional: URLs (mit Abrufdatum im Text)
+related: [dns_resolver]         # optional: ids verwandter Einträge
+supersedes:                     # optional (v. a. ADRs)
+classification: intern          # optional, Default intern; nie höher (rules/privacy.md)
+---
+```
+Vorlage: [`../../common/templates/markdown/knowledge_entry.md`](../../common/templates/markdown/knowledge_entry.md), ADR: [`adr.md`](../../common/templates/markdown/adr.md).
+
+## Regeln für Agenten
+- **Lesen:** zuerst `INDEX.md`, dann gezielt Einträge. Suche: `grep -rl "tags:.*dns" ai/context/knowledge/`.
+- **Schreiben:** bestehenden Eintrag aktualisieren statt neuen anlegen; `updated` setzen; Quellen mit Datum.
+- **Fakten statt Erzählung:** Tabellen (Adressen, Ports, Versionen), Abschnitt „Stand/Änderungen“ unten mit Datum.
+- **Nach jeder Änderung:** `bin/kb_index.sh` (prüft Pflichtfelder, doppelte ids, aktualisiert `INDEX.md`). `--check` für reine Prüfung.
+- Veraltetes nicht löschen: `status: deprecated`/`superseded`, Verweis auf Nachfolger.
+- Keine Geheimnisse, keine Personennamen außer Kürzeln aus `responsible.md`.
@@ -0,0 +1,4 @@
+# decisions/
+
+Architekturentscheidungen als ADR (`type: decision`), Dateiname `adr_NNNN_<slug>.md`, fortlaufend nummeriert.
+Vorlage: [../../../common/templates/markdown/adr.md](../../../common/templates/markdown/adr.md). Überholte ADRs bleiben (`status: superseded`).
@@ -0,0 +1,4 @@
+# howto/
+
+Anleitungen und Runbooks (`type: howto`): Voraussetzungen → Schritte (kopierbare Befehle) → Prüfung → Rückweg.
+Wiederkehrende Fragen des Bedieners landen hier.
@@ -0,0 +1,4 @@
+# network/
+
+Netze, VLANs, IP-Pläne, DNS-Zonen, VPN, Routing (`type: network`). Format: [../README.md](../README.md).
+IP-Pläne als Tabelle (Netz | VLAN | Zweck | Gateway | DHCP-Bereich). Diagramme als Mermaid/ASCII.
@@ -0,0 +1,4 @@
+# research/
+
+Recherchen mit Bestand (`type: research`): Fragestellung, Ergebnis/Empfehlung, Quellen (URL + Abrufdatum), Einschätzung vs. Beleg getrennt.
+Keine internen Daten in Suchanfragen (`rules/web_search.md`).
@@ -0,0 +1,4 @@
+# services/
+
+Dienste und Anwendungen (`type: service`). Format: [../README.md](../README.md).
+Mindestinhalt: Zweck, Host(s), Version, Bereitstellung (Ansible-Rolle / Docker-Stack), Ports, Abhängigkeiten, Secret-Store-Pfad (nur Pfad), Healthcheck, Logging, Backup/Restore, Original-Doku (URL + Datum).
@@ -0,0 +1,49 @@
+---
+id: sultan
+title: sultan – verteiltes Ingress-Routing für Traefik (Eigenentwicklung)
+type: service
+status: active
+updated: 2026-10-23
+owner: br
+tags: [traefik, ingress, docker, netbird, checkmk, eigenentwicklung]
+sources: [https://git.everdc.eu/chmln-app-dev/sultan]
+related: []
+classification: intern
+---
+# sultan – verteiltes Ingress-Routing für Traefik
+
+> Eigenentwicklung des Betreibers (Go), Ersatz für HashiCorp Consul im eigenen Bedarf: Dienste deklarieren ihr Routing
+> per Traefik-Labels, ein Agent meldet es an den sultan-Server, Traefik holt die Konfiguration per HTTP-Provider.
+
+## Fakten
+| Merkmal | Wert |
+|---|---|
+| Repo | `ssh://git@git.everdc.eu:10022/chmln-app-dev/sultan.git`, lokal `~/git/sultan` |
+| Image | `zot.chmln.de/sultan:<version>` (distroless, nonroot UID 65532) – feste Version in `.env` |
+| Rollen | `sultan server` (neben Traefik), `sultan agent` (je Docker-Host), `sultan accountant` (Inventar) |
+| Agent → Server | TCP 8443, TLS, nur ausgehend |
+| Traefik → Backend | HTTP auf den **veröffentlichten** Host-Port des Containers |
+| Monitoring | Checkmk Local Checks (`/metrics/checkmk`) |
+
+## Details – was das für unsere Compose-Stacks heißt
+| Punkt | Folge |
+|---|---|
+| Traefik läuft auf anderer VM | kein externes Netz `traefik-net` und kein Label `traefik.docker.network` auf dem Docker-Host |
+| Port muss veröffentlicht sein | `ports: "${APP_PORT}:<intern>"` Pflicht für Web-Services; Bindung an `127.0.0.1` wird verworfen. Bindung an eine andere IP (z. B. NetBird-IP) wird akzeptiert (Code: `pkg/agent/workloads.go`, `reachablePorts`). Festlegung je Host in dessen Knowledge-Eintrag |
+| Port-Label | `loadbalancer.server.port` = Port **im Container**; der Agent rechnet auf den Host-Port um |
+| Entrypoints/Certresolver | Labels müssen Namen aus der Traefik-Konfiguration nutzen (`websecure`, `le`); sultan prüft das nicht |
+| Domains | nur Domains, die dem Mandanten im sultan-Server erlaubt sind (sonst „Policy-Verstoß“ im Server-Log) |
+| Namen | IDs: `a-z0-9`, `-`, `_`; **`__` ist reserviert** (Trenner `<mandant>__<knoten>__<router>`) – unser `_`-Schema passt, doppelter Unterstrich verboten |
+| Backend-Adresse | Agent meldet die Host-IP, über die er den Server erreicht; mit `SULTAN_BACKEND_INTERFACE=wt0` die NetBird-IP |
+| Wartung | gestoppter Container → Wartungsseite; **entfernter** Container (`down`) → 404 (siehe `docs/wartung.md` im Repo) |
+
+## Betrieb
+- Bereitstellung Agent: Compose mit `network_mode: host`, Docker-Socket `:ro`, `group_add: DOCKER_GID`, `suldata/` (enthält `node.key`) persistent und im Backup
+- Einladung: `sultan token invite --tenant=…` auf dem Server, als `SULTAN_TOKEN` in die `.env` des Agents (nur beim ersten Start)
+- Prüfung: Agent-Log „Mit Server verbunden / Lease erhalten“; vom Ingress `curl -sI http://<backend-ip>:<port> -H 'Host: …'`
+
+## Quellen
+- `~/git/sultan/README.md`, `docs/community.md`, `deploy/compose/agent/` (gelesen 23.10.2026, Commit `dd93277`)
+
+## Änderungen
+- 23.10.2026 – angelegt (br)
@@ -0,0 +1,4 @@
+# systems/
+
+Hosts, VMs und Geräte – ein Eintrag pro System (`type: system`). Format: [../README.md](../README.md).
+Mindestinhalt: Rolle, Standort (grob), Hardware/VM, OS + Version, Adressen, Dienste darauf, Zugriff (ohne Geheimnisse), Verantwortlich, Backup.
@@ -0,0 +1,5 @@
+# topics/
+
+Lerninhalte je LPIC-Prüfungsthema (`type: topic`), ein Eintrag pro Objective.
+`id` enthält Stufe und Objective-Nummer, z. B. `lpic1_103_1_command_line` für 103.1.
+Aufbau: Lernziel (Wortlaut/Version der Objectives mit Abrufdatum) → Kernbefehle und Dateien → Übungen → typische Fallen.
@@ -0,0 +1,17 @@
+# Verantwortliche
+
+> Stand: 23.10.2026 · **Quelle für die Header-Felder** `@author` / `@owner` (`rules/headers.md`).
+> Nur hier stehen Personennamen. Weitere Personen nur als Rolle (`rules/privacy.md`).
+
+| Kürzel | Header-String (`Name <mail>`) | Rolle | Header-Feld | Zuständig für |
+|---|---|---|---|---|
+| br | Björn Runden <br@runden.de> | Bediener, Autor und Verantwortlicher | `@author` (Standard) | Scripts, Ansible, Doku |
+| br | Björn Runden <br@runden.de> | Bediener, Autor und Verantwortlicher | `@owner` (Standard) | fachliche Freigabe |
+
+## Regeln für Agenten
+- **Standard:** `@author` = Eintrag mit „`@author` (Standard)“, `@owner` = Eintrag mit „`@owner` (Standard)“.
+- Weitere `@author` (Team): nur wer an der Datei tatsächlich mitarbeitet; je Person eine `@author`-Zeile, Hauptautor zuerst.
+- Header-String exakt übernehmen (`Name <mail>`), nichts kürzen oder ändern.
+- Abweichende Zuständigkeit für einzelne Bereiche: in `context.md` → Metadaten festlegen; das gilt dann vorrangig.
+- Tabelle leer/Platzhalter → Platzhalter `<AUTOR>`/`<VERANTWORTLICH>` im Header lassen und den Bediener darauf hinweisen. Keine Namen erfinden.
+- KI-Beteiligung: `@assist KI-unterstützt (<Modell>), geprüft von <author>`.
@@ -0,0 +1,18 @@
+# Stil & Ansprache
+
+> Stand: 23.10.2026
+
+## Zielgruppe
+Der Betreiber (`br`) selbst: knapp, technisch, Empfehlung statt Optionsliste; Markdown und Code.
+
+## Standard
+- Amtssprache laut `AGENTS.md`; direkt, knapp, sachlich. Empfehlung statt Optionsliste.
+- Ansprache des Betreibers: du.
+- Quellen nennen, Unsicheres kennzeichnen.
+
+## Ausführlichkeit
+| Stufe | Wann |
+|---|---|
+| kurz | Rückfragen, Statusmeldungen, Chat |
+| normal | Lösungsbeschreibung, Projektdoku |
+| ausführlich | Konzepte, Entscheidungsvorlagen, Anleitungen |