From d8bd14ab1bc7de200cd7cf7a9f52fea67ae52bc4 Mon Sep 17 00:00:00 2001 From: Ben_Kosytorz Date: Thu, 24 Sep 2026 18:46:47 +0200 Subject: [PATCH] Add pilot handbook and document sn-fair v0 pilot.md: step-by-step for connecting two households (link-agnostic), measurement protocol M0-M4 (link baseline, uplink baseline, pooled, concurrent downloads, sn-fair Soll/Ist comparison), safety/legal checklist, and a results section to be filled after the pilot. Cross-linked from Home, documentation README, roadmap, architecture and server README; roadmap marks sn-fair v0 done. --- README.md | 7 +- documentation/Home.md | 3 + documentation/README.md | 10 +- documentation/ideen/architektur.md | 5 + documentation/ideen/pilot.md | 206 +++++++++++++++++++++++++++++ documentation/ideen/roadmap.md | 9 +- server/README.md | 24 +++- 7 files changed, 251 insertions(+), 13 deletions(-) create mode 100644 documentation/ideen/pilot.md diff --git a/README.md b/README.md index 003d9f4..07b3b64 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Datensammlung, keine Bezahlung. | Ordner/Datei | Inhalt | Einstieg | |---|---|---| | `documentation/` | Idee, Ethos, Architektur, Rechtslage, Roadmap (Deutsch, Obsidian-freundlich mit `[[Wikilinks]]`; `documentation/Home.md` ist die Map of Content) | [README](documentation/README.md) | -| `server/` | Die Software (Rust): `sn-fetch`, `sn-node`, `sn-exit`; geplant `sn-fair`, `sn-cache`, `sn-freenet` | [README](server/README.md) | +| `server/` | Die Software (Rust): `sn-fetch`, `sn-node`, `sn-exit`, `sn-fair`; geplant `sn-cache`, `sn-freenet` | [README](server/README.md) | | `scripts/` | Repo-Setup (`bootstrap-gitea.sh`) | — | | `AGENTS.md` | Arbeitsanweisungen für Coding-Agents und Contributor:innen | [AGENTS.md](AGENTS.md) | | `LICENSE` | Code-Lizenz: AGPL-3.0-only | [LICENSE](LICENSE) | @@ -53,8 +53,11 @@ Prototyp (Konzeptphase + erster Code): - **`sn-exit` v0** funktioniert: kontingentierter Uplink-Proxy (Byte-Relay, CONNECT-Tunnel für HTTPS, SSRF-Schutz, Source-Allowlist) — End-to-End mit `sn-fetch` gegen einen echten Server verifiziert +- **`sn-fair` v0** funktioniert: Fairness-Engine (gewichtetes Max-Min, + Leech-Politik) + Demo-CLI — die Soll-Aufteilung für den Piloten - **Nächste Schritte:** Pilot mit 2–3 Haushalten (Yggdrasil-Overlay - verkabeln, Messwerte), Fairness-Scheduler — siehe + verkabeln, Messwerte — Handbuch: + [pilot.md](documentation/ideen/pilot.md)), `sn-node`-Daemon — siehe [Roadmap](documentation/ideen/roadmap.md) ## Doku lesen (Obsidian) diff --git a/documentation/Home.md b/documentation/Home.md index 6d2e4f0..8e5c904 100644 --- a/documentation/Home.md +++ b/documentation/Home.md @@ -26,6 +26,7 @@ Nachbarschaft betreibt ihre eigene Instanz nach eigenen Regeln. | [[Splitting]] | Was sich splitten lässt: Ranges, Flow-Verteilung, Realtime | | [[Lizenz]] | Lizenz-Optionen (Code & Doku) | | [[Roadmap]] | Phasen: Pilot → MVP → Rollout → Freenet → Backbone | +| [[Pilot]] | Pilot-Handbuch: 2 Haushalte verkabeln, messen, dokumentieren | | [[Server-README|Server-Konzept]] | Software-Komponenten, Code-Standards | ## Lesereihenfolge zum Einstieg @@ -44,6 +45,8 @@ Nachbarschaft betreibt ihre eigene Instanz nach eigenen Regeln. - [[Splitting]] ↔ [[Architektur]] (Schicht 2) — was der Exit-Pool tatsächlich nutzen kann - [[Overlay]] ↔ [[Architektur]] (Schicht 1) — Routing-Entscheidung und deren Grenzen - [[Overlay]] ↔ [[Server-README]] — `sn-node` generiert die Yggdrasil-Config, `sn-fetch` nutzt `Egress::Proxy` +- [[Pilot]] ↔ [[Roadmap]] (Phase 1) und [[Overlay]] §Deployment — der Pilot ist der erste Real-Test +- [[Pilot]] §M4 ↔ [[Architektur]] §Fairness-Scheduler — `sn-fair` berechnet die Soll-Aufteilung - [[Lizenz]] ↔ [[Ethos]] §6 (Transparenz) und `freenet-core` (AGPL) ## Außerhalb der Doku diff --git a/documentation/README.md b/documentation/README.md index b716d65..4d2f53f 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -17,6 +17,7 @@ unabhängige SpiderNet-Instanzen geben; wir providen nur die Werkzeuge. - [[Splitting]] — Was sich über mehrere Exits splitten/verteilen lässt (und was nicht) - [[Lizenz]] — Lizenz-Optionen und Empfehlung - [[Roadmap]] — Phasenplan vom Pilot bis zum Nachbarschafts-Backbone +- [[Pilot]] — Pilot-Handbuch: Schritt-für-Schritt + Messprotokoll (Phase 1) - [[Server-README|Server-Konzept]] — geplante Software (`sn-node`, `sn-fetch`, …) ## Die Idee in einem Satz @@ -29,10 +30,11 @@ ist — ohne Mehrkosten und mit besserer Versorgung schwacher Haushalte. ## Status Prototypphase (siehe [[Roadmap]]): `sn-fetch` (segmentierter Multi-Exit- -Download mit Retry + Egress), `sn-node` v0 (Yggdrasil-Config + Status) -und `sn-exit` v0 (kontingentierter Uplink-Proxy mit SSRF-Schutz) sind -implementiert und getestet — Details in [`server/README.md`](../server/README.md). -Nächster Meilenstein: Pilot mit 2–3 Haushalten (echtes Overlay, Messwerte). +Download mit Retry + Egress), `sn-node` v0 (Yggdrasil-Config + Status), +`sn-exit` v0 (kontingentierter Uplink-Proxy mit SSRF-Schutz) und `sn-fair` +v0 (Fairness-Engine + Demo-CLI) sind implementiert und getestet — +Details in [`server/README.md`](../server/README.md). Nächster +Meilenstein: Pilot mit 2–3 Haushalten (Handbuch: [[Pilot]]). ## Verwandte Projekte (Prior Art) diff --git a/documentation/ideen/architektur.md b/documentation/ideen/architektur.md index 7b3aac3..1baa581 100644 --- a/documentation/ideen/architektur.md +++ b/documentation/ideen/architektur.md @@ -133,6 +133,11 @@ siehe [[Splitting]]. - Exit-Kontingente (Volumenlimit, Wartungszeit) werden respektiert - Leech-Nodes: niedrigste Priorität bei Knappheit, nie ausgeschlossen +Status: **v0 implementiert** — gewichtetes Max-Min in zwei Klassen: +Contributors teilen die volle Kapazität nach Max-Min, Leeches teilen +die Restkapazität (bei Sättigung zuerst gedrosselt, nie ausgeschlossen). +Details in `server/README.md`; Soll-Ist-Vergleich im Piloten: [[Pilot]] §M4. + ### Nachbarschafts-Cache (`sn-cache`) - Transparenter Shared-Cache (lancache-Prinzip): große, populäre Objekte diff --git a/documentation/ideen/pilot.md b/documentation/ideen/pilot.md new file mode 100644 index 0000000..806e6ef --- /dev/null +++ b/documentation/ideen/pilot.md @@ -0,0 +1,206 @@ +# Pilot: zwei Haushalte verbinden und messen + +> Prototyp-Betrieb, **keine Garantie** (AGPL §§ 15/16) — Nutzung auf eigene +> Verantwortung, siehe [[Recht]] und [[Server-README]]. Persönliche Daten +> (Namen, Adressen, Keys realer Nachbarn) bleiben **außerhalb des Repos**. + +Ziel der Phase 1 (siehe [[Roadmap]]) ist der Beweis, dass Bandbreiten- +Pooling über zwei echte Anschlüsse real funktioniert — nicht auf dem +Papier. Der Pilot liefert: + +1. **Messwerte:** 1-Exit-Baseline vs. 2-Exit-gepoolt (gleiche Datei) +2. **Fairness-Daten:** zwei gleichzeitige Downloads teilen sich den Pool +3. **Stolpersteine:** was die Doku/Software dadurch lernen muss + +Der Pilot ist **link-agnostisch**: Ob die Häuser per Glasfaser, +SFP+-Direktkabel, Switch im Keller, 60-GHz-Richtfunk oder normalem +Ethernet verbunden sind, entscheidet die Nachbarschaft — die Software +misst, was da ist (siehe [[Architektur]], Schicht 0). Alle +Angaben zu Link-Typen in dieser Datei sind Beispiele. + +## Voraussetzungen + +### Teilnehmer + +- 2 Haushalte (ideal 3, der dritte als **Leech** — Empfang ohne + Exit-Angebot, um genau diesen Modus mitzutesten) +- Ein persönlicher Termin; technisches Onboarding gesicht zu gesicht + (Nachbarn sind der Trust-Anchor, siehe [[Architektur]]) + +### Hardware (je Haushalt, Beispiele) + +- Ein Mini-PC oder Einplatinenrechner (≥ 2 GB RAM, Debian o. ä.) als + Node-Host — je eine NIC Richtung Heim-Router und Richtung + Nachbarschafts-Link (übergangsweise reicht auch eine NIC am + Mesh-Switch) +- Verbindungsweg — **eins davon genügt:** + - Glasfaser/DAC-Direktkabel zwischen den SFP/SFP+-Ports + - gemeinsamer Switch im Keller/Treppenhaus + - 60-GHz-Richtfunk-Pair (Sichtlinie nötig, siehe [[Recht]] §3) + - vorhandenes Ethernet/WLAN (langsamer, aber null Aufwand) + +### Software + +- [yggdrasil](https://yggdrasil-network.github.io/) (Binary oder + Debian-Paket) +- SpiderNet-Binaries bauen und rüberkopieren: + +```sh +cd server +cargo build --release --workspace +# → target/release/sn-node, sn-exit, sn-fetch, sn-fair +``` + +### Vor dem Termin (Checkliste) + +- [ ] ISP-AGB der Teilnehmenden geprüft (Weitergabe an Dritte, + siehe [[Recht]] §2) +- [ ] Nachbarschafts-Abkommen geklärt: wer spendiert wie viel + (Quota), Leechen ausdrücklich erlaubt, alles jederzeit widerruflich +- [ ] Hardware vorhanden und bootfähig +- [ ] Binaries gebaut und auf beide Nodes kopiert +- [ ] Testdatei gewählt: Range-fähiger Server, ~750 MB, bekannte + SHA-256 (im PoC hat sich eine Debian-Netinst-ISO bewährt; die + offizielle `SHA256SUMS` der jeweiligen Version nutzen) + +## Termintag: Schritt-für-Schritt + +Die technischen Details (Config, Schlüssel, Admin-Socket) stehen in +[[Overlay]] §Deployment — hier die Reihenfolge mit Checkpunkten. + +1. **Physik verbinden.** Link herstellen, L2-Test: `ping` über die + lokale Verbindung. Optional `iperf3` über den Link → das ist + **Messpunkt M0** (Kapazität des Nachbarschafts-Links). +2. **Yggdrasil einrichten (beide Häuser).** + + ```sh + sn-node genconf --listen "tcp://[::]:1337" \ + --peer "tcp://[]:1337" \ + --allow-key \ + --private-key-path /etc/spidernet/node.key \ + --out /etc/yggdrasil.conf + yggdrasil -useconffile /etc/yggdrasil.conf + sn-node status # eigene Overlay-Adresse + Peering-Status + ``` + + - Im selben LAN reicht Multicast-Auto-Peering (ohne `--peer`). + - Config enthält den **privaten** Key (`chmod 600` macht + `genconf` selbst) — niemals teilen oder committen. + - Die eigenen Adressen/Keys werden **persönlich** ausgetauscht, + nicht per Chat/Repo. +3. **Overlay-Test.** `sn-node status` zeigt auf *beiden* Seiten den + Nachbarn als Peer; `ping ` geht. +4. **Exit starten (Haus B spendiert):** + + ```sh + sn-exit --bind "[]:8080" \ + --allow \ + --quota-mib 1024 + ``` + + - `--allow` nie offen lassen (ohne Liste ist nur Loopback + erlaubt, das ist der Dev-Mode). + - Test von Haus A: ein HTTP-Request gegen einen Origin über + `http://[]:8080` als Proxy (z. B. mit + `sn-fetch --probe-only` oder `curl -x`). +5. **Erster gepoolter Download (Haus A):** + + ```sh + sn-fetch -o testdatei.iso \ + -e "1=1,2=1@http://[]:8080" \ + --sha256 + ``` + +6. **Kill-Switch-Test.** `sn-exit` auf B stoppen → laufender und + nächster Download fällt auf den eigenen Uplink zurück (Retry mit + Exit-Reassignment). Danach B wieder starten. Beides dokumentieren: + Dauer der Störung, verlorene Segmente. + +Wichtig zur Beruhigung: SpiderNet v0 installiert **keine +Routing-Änderung** im Heimnetz. Geräte nutzen wie gewohnt den eigenen +Router; nur `sn-fetch`-Downloads gehen (explizit) in den Pool. Alles +stoppen (`sn-exit`, `yggdrasil`) = das Haus ist wie vorher. + +## Messprotokoll + +Regeln für belastbare Werte: + +- Gleiche Testdatei, gleiche Uhrzeit ± 1 h (ISP-Congestion schwankt + tageszeitabhängig) +- Pro Szenario **3 Läufe**, Median notieren; zwischen Läufen Pause +- Nichts anderes auf den Nodes laufen lassen; Messwerte immer mit + Datum/Uhrzeit und den beidseitigen Uplink-Tarifen notieren + +### Szenarien + +| # | Szenario | Wo | Was gemessen wird | +|---|---|---|---| +| M0 | Nachbarschafts-Link-Kapazität | A↔B | `iperf3` über den lokalen Link | +| M1 | Uplink-Baseline | je Haus | nur eigener Uplink (`-e "1=1"`), ISP-Kapazität | +| M2 | Gepoolt, 1 Download | A | 2 Exits (`-e "1=1,2=1@http://[B]:8080"`), Gesamt-Durchsatz vs. M1 | +| M3 | Gepoolt, Konkurrenz | A + B | zwei `sn-fetch`-Läufe gleichzeitig, beide über beide Exits — wie teilen sich die Aufstellung | +| M4 | Fairness-Soll | (Simulation) | `sn-fair` mit den M1/M2-Werten → Soll-Aufteilung zum Vergleich mit M3 | + +### Tabelle M2/M3 (Vorlage, pro Lauf eine Zeile) + +| Lauf | Szenario | Datum/Zeit | Durchsatz Mbit/s | Dauer | Segmente | Retries | Bemerkung | +|---|---|---|---|---|---|---|---| +| 1 | M2 | | | | | | | +| 2 | M2 | | | | | | | +| 3 | M2 | | | | | | | + +Zusätzlich notieren: Quota-Rest auf B, CPU/RAM der Node-Hosts, +(evtl.) Firmware/Treiber des Link-Wegs. + +### Fairness-Soll mit `sn-fair` (M4) + +Die gemessenen Uplink-Kapazitäten (M1) als Pool-Kapazität und die +gleichzeitigen Nachfragen (M3) einsetzen — das CLI arbeitet in +Mbit/s: + +```sh +sn-fair --capacity \ + --participant 1=contributing \ + --participant 2=contributing \ + --participant 3=leeching \ + --demand 1= \ + --demand 2= \ + --demand 3= +``` + +Erwartung (Regelwerk in [[Architektur]] §Fairness-Scheduler): +Contributors bekommen die Kapazität nach max-min Fairness (gewichtet), +Leeches profitieren von Restkapazität — bei Sättigung zuerst gedrosselt, +nie ausgeschlossen. Weicht M3 (Ist) deutlich von M4 (Soll) ab, landet +das als Erkenntnis in der Ergebnisse-Sektion unten (die echte +Runtime-Integration in `sn-fetch` ist Phase 2, siehe [[Roadmap]]). + +## Sicherheit & Recht (Checkliste während des Piloten) + +- [ ] `sn-exit` nur mit `--allow` (Allowlist) und Quota laufen lassen +- [ ] SSRF-Schutz nie deaktivieren (verhindert Nachbarn-Zugriff auf + Heim-LAN/Admin-Sockets des Exit-Haushalts) +- [ ] Keine Port-Forwards ins Internet, außer ein Peering braucht es + zwingend (siehe [[Overlay]] §Grenzen) +- [ ] Logs minimal und lokal (keine Inhaltslogs, siehe [[Recht]] §4) +- [ ] Haftungsausschluss ist den Teilnehmenden bekannt gezeigt +- [ ] Sperrbarkeit praktisch geübt: Exit stoppen = Kill-Switch, + Teilnehmersperre = `--allow`-Liste ändern + +## Ergebnisse + +*(wird nach dem Piloten gefüllt — Messwerte, Erkenntnisse und +Stolpersteine gehören hier ins Repo, nicht in den Chat)* + +### Messwerte + +*(Tabelle ergänzen — M0 bis M4, Mediane der 3 Läufe)* + +### Erkenntnisse + +*(kurz, ehrlich, mit Quellen/Logs wo sinnvoll)* + +### Stolpersteine & Anpassungen + +*(was in [[Architektur]], [[Overlay]], [[Roadmap]] oder der Software +geändert werden muss, damit der nächste Pilot weniger stolpert)* diff --git a/documentation/ideen/roadmap.md b/documentation/ideen/roadmap.md index 61c0bee..6f918a7 100644 --- a/documentation/ideen/roadmap.md +++ b/documentation/ideen/roadmap.md @@ -14,6 +14,7 @@ endet mit etwas, das man benutzen kann. ## Phase 1 — Pilot (2–3 Haushalte) Ziel: Beweis, dass Pooling über zwei Anschlüsse real funktioniert. +Handbuch mit Messprotokoll: [[Pilot]]. - [x] `sn-fetch` PoC (lokal): Range-Probe, gewichteter Planner, parallele Segment-Downloads, Reassembly + SHA-256 — verifiziert gegen einen @@ -27,10 +28,12 @@ Ziel: Beweis, dass Pooling über zwei Anschlüsse real funktioniert. WLAN/60-GHz), `sn-node`-Daemon orchestriert den Node - [x] `sn-exit` v0: HTTP-Proxy auf der Yggdrasil-Adresse (Kontingente, SSRF-Schutz, Kill-Switch = Prozess stoppen) +- [x] `sn-fair` v0: Fairness-Engine (gewichtetes Max-Min über zwei + Klassen, Leech-Politik) + Demo-CLI; Runtime-Integration in + `sn-fetch` ist Phase 2 - [ ] `sn-fetch` PoC über 2 echte Exits, plus Baseline-Messung - (1-Exit vs. 2-Exit, gleiche Datei) -- [ ] Fair-Share-Scheduler v0: zwei gleichzeitige Downloads, faire Aufteilung -- [ ] Doku: Messwerte, Erkenntnisse, Stolpersteine → hier in das Repo + (1-Exit vs. 2-Exit, gleiche Datei — Protokoll in [[Pilot]]) +- [ ] Doku: Messwerte, Erkenntnisse, Stolpersteine → in [[Pilot]] §Ergebnisse ## Phase 2 — MVP-Software diff --git a/server/README.md b/server/README.md index 70f9ecd..9f1ef35 100644 --- a/server/README.md +++ b/server/README.md @@ -60,10 +60,26 @@ SHA-256 entspricht der offiziellen `SHA256SUMS`). - Verifiziert end-to-end: `sn-fetch` über einen laufenden `sn-exit` lädt die Debian-ISO (756 MB, 4 Segmente, SHA-256 korrekt) -**Noch nicht drin:** `sn-node`-Daemon (Supervisor, der yggdrasil + sn-exit -+ sn-fetch orchestriert), Fairness-Scheduler. +**`sn-fair` v0 ist implementiert** (siehe `crates/sn-fair/`): -Details zum Overlay: [[Overlay]]. +- Gewichtetes Max-Min-Fairness-Engine (zwei Klassen): **Contributors** + (Haushalte mit Exit-Angebot, konfigurierbares Gewicht) teilen sich + die Gesamtkapazität nach Max-Min-Fairness; **Leeches** (Empfang ohne + Beitrag, ausdrücklich legitim) bekommen die Restkapazität — bei + Sättigung zuerst gedrosselt, nie ausgeschlossen +- Deterministische, overflow-sichere Berechnung (u128-Arithmetik, + Restverteilung in ID-Ordnung), validierte Newtypes + (`ParticipantId`, `Weight`, `Rate`, `Capacity`) +- Demo-CLI in Mbit/s für den Piloten: Soll-Aufteilung simulieren und + gegen die gemessene Ist-Aufteilung halten (siehe [[Pilot]], M4) +- Runtime-Integration in `sn-fetch` (echte gleichzeitige Downloads + drosseln) ist Phase 2, siehe [[Roadmap]] + +**Noch nicht drin:** `sn-node`-Daemon (Supervisor, der yggdrasil + +sn-exit + sn-fetch orchestriert), Freenet-Integration, Cache. + +Details zum Overlay: [[Overlay]]. Pilot-Handbuch mit Messprotokoll: +[[Pilot]]. ## Haftungsausschluss (muss im Produkt sichtbar sein) @@ -96,7 +112,7 @@ Einplatinenrechner), der: | `sn-node` | Node-Glue: Yggdrasil-Config (`genconf`), Overlay-Status (`status`), später Daemon/Supervisor | | `sn-exit` | Exit-Dienst: kontingentierter Uplink-Proxy auf der Yggdrasil-Adresse (v0: Byte-Relay + Quota + SSRF-Schutz) | | `sn-fetch` | Segmentierter Multi-Exit-Downloader (HTTP-API + CLI) | -| `sn-fair` | Fairness-Scheduler (max-min, Exit-Kontingente, Karma, Leech-Modus) | +| `sn-fair` | Fairness-Scheduler (max-min, Exit-Kontingente, Karma, Leech-Modus) — v0: zwei-Klassen-Max-Min-Engine + Demo-CLI | | `sn-cache` | Transparenter Nachbarschafts-Cache (DNS-basiert) | | `sn-freenet` | Integration von `freenet-core` (Contracts für Nachbarschafts-Inhalte) |