From b9bebe7b0cb2ecabc09bcb202eac4580a8cf93b3 Mon Sep 17 00:00:00 2001
From: alf <service@wralto.org>
Date: Sun, 23 Aug 2026 18:52:03 +0000
Subject: [PATCH] =?UTF-8?q?README.md=20hinzugef=C3=BCgt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6115ad7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# ts-menu — Tailscale Geräteverwaltung
+
+Kleines interaktives Kommandozeilen-Tool, um einzelne Geräte im eigenen
+Tailscale-Netz per Menü zu sperren (vom Tailnet trennen) und wieder
+zuzulassen.
+
+![gum](https://img.shields.io/badge/UI-gum-ff69b4)
+
+## Voraussetzungen
+
+| Tool | Zweck | Installation |
+|------|-------|---------------|
+| [`gum`](https://github.com/charmbracelet/gum) | Menüführung / UI | `brew install gum` (macOS) oder siehe [Charm-Repos](https://github.com/charmbracelet/gum#installation) (Linux) |
+| `curl` | API-Requests | meist vorinstalliert |
+| `jq` | JSON-Verarbeitung | `apt install jq` / `brew install jq` |
+
+Außerdem brauchst du einen **Tailscale API-Access-Token**:
+
+1. Admin-Konsole öffnen: <https://login.tailscale.com/admin/settings/keys>
+2. **Generate access token** klicken
+3. Token kopieren (wird nur einmal angezeigt!)
+
+## Installation
+
+```bash
+chmod +x ts-menu.sh
+```
+
+Optional irgendwo in den `PATH` legen, z. B.:
+
+```bash
+mkdir -p ~/.local/bin
+cp ts-menu.sh ~/.local/bin/ts-menu
+```
+
+## Konfiguration
+
+Lege eine Datei `~/.ts-toggle.conf` an:
+
+```bash
+TAILSCALE_API_KEY="tskey-api-xxxxxxxxxxxx"
+TAILSCALE_TAILNET="deine-org.ts.net"
+```
+
+- `TAILSCALE_API_KEY` — dein Access-Token von oben
+- `TAILSCALE_TAILNET` — Name deines Tailnets (in der Admin-Konsole oben
+  links sichtbar, z. B. `beispiel@gmail.com` oder `deine-firma.ts.net`)
+
+> ⚠️ Diese Datei enthält ein sensibles API-Token. Zugriffsrechte
+> einschränken, z. B. mit `chmod 600 ~/.ts-toggle.conf`.
+
+Alternativ lassen sich beide Werte auch als Umgebungsvariablen setzen,
+statt sie in die Datei zu schreiben:
+
+```bash
+export TAILSCALE_API_KEY="tskey-api-xxxxxxxxxxxx"
+export TAILSCALE_TAILNET="deine-org.ts.net"
+```
+
+## Nutzung
+
+```bash
+./ts-menu.sh
+```
+
+Du landest im Hauptmenü mit drei Optionen:
+
+- **Gerät sperren/entsperren** — wählt ein Gerät aus der Liste (Status
+  wird direkt angezeigt), erkennt automatisch den aktuellen Zustand und
+  schlägt die passende Gegenaktion vor. Vor der Ausführung wird per
+  Bestätigungsdialog nachgefragt.
+- **Geräteliste anzeigen** — zeigt alle Geräte des Tailnets mit Name,
+  Betriebssystem und Status in einer Tabelle.
+- **Beenden** — verlässt das Programm.
+
+## Wie das Sperren funktioniert
+
+Ein gesperrtes Gerät wird über die Tailscale-API **deautorisiert**
+(`authorized: false`). Das trennt es sofort und vollständig vom Tailnet —
+es hat dann zu keinem anderen Gerät mehr Verbindung, bis es wieder
+autorisiert wird. Das Gerät selbst bleibt in der Geräteliste sichtbar und
+kann jederzeit wieder freigeschaltet werden, ohne sich neu einzuloggen.
+
+> Hinweis: Das ist ein Alles-oder-nichts-Schalter pro Gerät. Für
+> feingranulare Regeln (z. B. "Gerät A darf nur mit B sprechen") braucht
+> es stattdessen ACL-Policies in der Admin-Konsole — das ist mit diesem
+> Tool nicht abgedeckt.
+
+## Fehlerbehebung
+
+| Problem | Ursache |
+|---------|---------|
+| `Fehler: gum wird benötigt` | `gum` ist nicht installiert oder nicht im `PATH` |
+| `Konnte Geräteliste nicht laden` | API-Key falsch/abgelaufen oder `TAILSCALE_TAILNET` falsch |
+| `Fehler: TAILSCALE_API_KEY ist nicht gesetzt` | `~/.ts-toggle.conf` fehlt oder Variable nicht gesetzt |
+
+## Dateien
+
+- `ts-menu.sh` — das interaktive Menü-Script
+- `~/.ts-toggle.conf` — deine lokale Konfiguration (nicht mit anderen teilen!)
\ No newline at end of file