Add architecture and backbone networking documentation

README.md

@@ -1,5 +1,10 @@
 # server-scripts
 
+## Dokumentation
+
+Eine Übersicht über die Architektur des Repositories sowie eine Erklärung, wie das
+Freifunk-Backbone auf Netzwerkebene funktioniert, findet sich unter [`docs/`](docs/README.md).
+
 ## Skripte installieren
 
 ```

docs/README.md

@@ -0,0 +1,17 @@
+# Dokumentation
+
+Diese Dokumentation ergänzt die Installationsanleitung in der [Haupt-README](../README.md) um
+einen Überblick über die Architektur des Repositories und die dahinterliegenden Netzwerkkonzepte.
+
+- [Architektur](architektur.md) — Kernkomponenten des Repositories, ihre Beziehungen
+  zueinander und der Start-/Stop-/Watchdog-Ablauf.
+- [Komponenten](komponenten.md) — jede einzelne Komponente (Software und eigene Skripte)
+  im Detail: was sie ist und wozu sie dient.
+- [Backbone-Netzwerk](backbone-netzwerk.md) — wie GRE, batman-adv, fastd und BGP (BIRD)
+  zusammen das Freifunk-Chemnitz-Backbone bilden.
+- [IP-Adressplan](ip-adressplan.md) — alle IPv4-/IPv6-Adressbereiche und -Schemata an
+  einem Ort, inklusive der Aufteilung in die Regionen Chemnitz und Umland.
+- [Sicherheitsmodell](sicherheitsmodell.md) — welche Verbindungen verschlüsselt und/oder
+  zugangskontrolliert sind, und welches Vertrauensmodell sich daraus ergibt.
+- [Betrieb](betrieb.md) — Runbook für wiederkehrende Aufgaben: neuen Server hinzufügen,
+  toten GRE-Tunnel debuggen, fastd-Schlüssel rotieren, Watchdog-Mails einordnen.

docs/architektur.md

@@ -0,0 +1,99 @@
+# Architektur
+
+Dieses Repository konfiguriert und betreibt einen **Freifunk-Chemnitz-Backbone-Server**
+(auch **„Uplink-Server“** genannt, siehe [Backbone-Netzwerk](backbone-netzwerk.md)):
+einen Server, der als Gateway/Supernode für Freifunk-Router (Mesh-Knoten) dient und
+gleichzeitig mit den anderen Backbone-Servern des Netzes verbunden ist. Das Repository ist
+als Sammlung von Bash-Skripten aufgebaut, die wie ein SysV-Init-Dienst gestartet, gestoppt
+und per Cron überwacht werden.
+
+## Verzeichnisstruktur
+
+| Pfad | Zweck |
+|---|---|
+| `ffc-server.sh` | Zentrales Steuerskript: `start`, `stop`, `watchdog`. Lädt Konfiguration und alle `lib/*.sh`-Module. |
+| `initd-ffc.sh` | Dünner Wrapper, der `ffc-server.sh` als `/etc/init.d/ffc` einbindet (SysV-Init). |
+| `lib/*.sh` | Ein Modul pro Dienst/Funktion (siehe unten). Jedes Modul stellt `<name>_init`, `<name>_start`, `<name>_stop` und optional `<name>_cron` bereit. |
+| `conf/*.conf` | Eingecheckte Vorlagen/Defaults. Pro Server werden daraus `*.local.conf`-Dateien erzeugt bzw. von Hand angelegt (siehe `conf/.gitignore`: `*.local.*` und `bird-routes.country.conf` sind lokal/generiert und nicht versioniert). |
+
+## Die Module in `lib/`
+
+Eine ausführlichere Beschreibung jeder einzelnen Komponente (Software und Skript) samt
+ihrem Zweck findet sich in [Komponenten](komponenten.md).
+
+| Modul | Verantwortlich für |
+|---|---|
+| `log.sh` | Logging nach syslog (`logger`) und optional per Mail (`LOG_TO`), inkl. `log_fatal_error` zum Abbruch bei Fehlkonfiguration. |
+| `gre.sh` | Aufbau der GRE-Tunnel (`gretap`) zu allen anderen Backbone-Servern aus `GRE_PEERS`; Watchdog-Check per ICMPv6-Ping auf die Tunnel-Interfaces. |
+| `batman.sh` | Initialisiert `batman-adv`, hängt die GRE-Interfaces (aus `BATMAN_IFS`) und später `fastd`-Interfaces als Slaves ein, konfiguriert `bat0` (Service-Adressen, Bridge-Loop-Avoidance, Bonding, Gateway-Modus) und startet `alfred`/`batadv-vis` für die Meshviewer-Daten. |
+| `fastd.sh` | Startet das fastd-VPN (einen Prozess pro CPU-Kern, jeweils auf eigenem Port), über das sich Freifunk-Router mit dem Server verbinden. |
+| `bird.sh` / `bird6.sh` | Generieren die BIRD-/BIRD6-Konfiguration aus Templates (`conf/bird*.conf`), tragen alle GRE-Peers als BGP-Nachbarn ein, setzen Policy-Routing (`ip rule`/`ip -6 rule`) für das Mesh-Netz und starten die Routing-Daemons. |
+| `dnsmasq.sh` | DHCP/DNS für Endgeräte im Mesh (`bat0`), optional, nur auf Servern mit `USE_DNSMASQ=1`. |
+| `radvd.sh` | IPv6 Router Advertisements für `bat0`, nur auf IPv6-Gateway-Servern (`USE_RADVD=1`), setzt zusätzlich eine Default-Route in BIRD6. |
+| `meshviewer.sh` | Startet `alfred`/`batadv-vis` unabhängig von `batman.sh`, falls der Server primär als Meshviewer-Datenquelle dient. |
+
+## Ablauf: Start, Stop, Watchdog
+
+`ffc-server.sh` (siehe dort) lädt zunächst `conf/general.conf` und `conf/general.local.conf`
+sowie alle `lib/*.sh`-Module und verzweigt dann anhand des Arguments:
+
+```mermaid
+flowchart TD
+    conf["conf/general.conf +\nconf/general.local.conf"] --> ffc[ffc-server.sh]
+    lib["lib/*.sh Module"] --> ffc
+
+    ffc -->|start| gre_i[gre_init] --> bat_i[batman_init]
+    bat_i --> fastd_i["fastd_init (USE_FASTD)"]
+    fastd_i --> bird_i["bird_init / bird6_init (USE_BIRD)"]
+    bird_i --> dns_i["dnsmasq_init (USE_DNSMASQ)"]
+    dns_i --> radvd_i["radvd_init (USE_RADVD)"]
+    radvd_i --> mv_i[meshviewer_init]
+    mv_i --> tunnels[gre_add_all_tunnels]
+    tunnels --> peers[batman_add_all_peers]
+    peers --> daemons["fastd_start / bird_start / bird6_start /\ndnsmasq_start / radvd_start"]
+    daemons --> sysctl[sysctl -p conf/sysctl.conf]
+
+    ffc -->|stop| stop["fastd_stop, gre_stop, batman_stop,\nbird_stop, bird6_stop, dnsmasq_stop,\nradvd_stop, meshviewer_stop"]
+    stop --> rules[ip rule delete lookup 100]
+
+    ffc -->|watchdog, jedes 1 Min| wd1["meshviewer_cron, radvd_cron,\ndnsmasq_cron (Prozess-Check)"]
+    ffc -->|watchdog, alle 5 Min| wd2["gre_cron (Tunnel-Ping-Check),\nbird_cron (Länder-Routen nachladen)"]
+```
+
+Wichtige Details zum Ablauf:
+
+- **Reihenfolge beim Start:** Erst werden alle Dienste initialisiert (`*_init`, meist reine
+  Konfigurationsgenerierung/-validierung), dann werden GRE-Tunnel und batman-adv-Peers
+  aufgebaut, und erst danach die eigentlichen Daemons gestartet. So existieren die
+  Netzwerk-Interfaces bereits, wenn z. B. BIRD versucht, BGP-Sessions über sie aufzubauen.
+- **Feature-Flags:** `USE_FASTD`, `USE_BIRD`, `USE_DNSMASQ`, `USE_RADVD`, `USE_MESHVIEWER` in
+  `general.local.conf` steuern, welche Module überhaupt aktiv werden — ein Server muss nicht
+  alle Rollen gleichzeitig übernehmen (z. B. ist `USE_DNSMASQ`/`USE_RADVD` nur auf
+  ausgewählten Gateway-Servern gesetzt).
+- **Watchdog:** `ffc-server.sh watchdog` wird minütlich per Cron aufgerufen (siehe README).
+  Jede Minute werden laufende Prozesse (dnsmasq, radvd, alfred) geprüft und bei Bedarf neu
+  gestartet; alle 5 Minuten wird zusätzlich die Erreichbarkeit der GRE-Tunnel per Ping
+  geprüft und die länderspezifische Routen-Datei von der Freifunk-Chemnitz-API neu geladen.
+  Fehler werden über `log_error`/`log_fatal_error` sowohl nach syslog als auch (im
+  Watchdog-Kontext) per Mail an `LOG_TO` gemeldet.
+- **Konfigurations-Templating:** `bird.sh`, `bird6.sh` und `dnsmasq.sh` erzeugen aus den
+  eingecheckten `conf/*.conf`-Vorlagen (Platzhalter wie `__BIRD_ROUTER_ID__`,
+  `__DNSMASQ_SERVICE_IP__`) bei jedem Start neue `*.local.conf`-Dateien anhand der Werte aus
+  `general.local.conf` — die eingecheckten Vorlagen sind also keine fertigen Configs,
+  sondern Templates.
+
+## Kopplung zwischen den Modulen
+
+Die Module sind nicht unabhängig, sondern bauen aufeinander auf:
+
+- `bird.sh`/`bird6.sh` iterieren über dieselbe `GRE_PEERS`-Liste wie `gre.sh`, um pro
+  GRE-Tunnel eine BGP-Session zum jeweiligen Nachbarserver zu konfigurieren.
+- `batman.sh` bindet die von `gre.sh` erzeugten Interfaces (`BATMAN_IFS`) sowie die von
+  `fastd.sh` erzeugten Client-Tunnel in dieselbe batman-adv-Instanz (`bat0`) ein.
+- `radvd.sh` erfordert `USE_BIRD=1` und trägt seine Default-Route direkt in BIRD6 ein
+  (`bird6_add_route`).
+- `dnsmasq.sh` und die BGP-Konfiguration nutzen dieselben `SERVICE_ADDRESSES` (die
+  Dnsmasq-Gateway-Adresse wird zugleich als Route über BIRD announced).
+
+Das Zusammenspiel dieser Module ergibt das eigentliche Backbone-Netz — siehe
+[Backbone-Netzwerk](backbone-netzwerk.md) für die konzeptionelle Erklärung.