Initial commit: Upterm setup documentation

README.md

@@ -0,0 +1,187 @@
+# Upterm – Terminal Session Sharing
+
+Upterm ermöglicht das einfache Teilen von SSH-Sessions. Ideal für Kunden-Support oder Pair-Programming mit externen Personen ohne Teleport-Zugang. Clients benötigen nur einen SSH-Client – keine zusätzliche Software nötig.
+
+## Architektur
+
+```
+[Host-Maschine]
+  └─ upterm host --server wss://upterm.ebesch.de -- bash
+       │
+       │  Reverse SSH Tunnel
+       ▼
+[uptermd  –  Server]
+       ▲                  ▲
+       │                  │
+  Port 2222          WSS :443
+  Portweiterleitung  NPM → Port 8080
+  Router → LAN-IP
+       │                  │
+[Client]              [Client]
+ssh -p 2222 ...       upterm proxy wss://...
+(kein Extra-Tool)     (upterm CLI nötig)
+```
+
+---
+
+## Installation & Build
+
+### Go installieren
+
+```bash
+curl -sL https://go.dev/dl/go1.22.4.linux-amd64.tar.gz -o /tmp/go.tar.gz
+rm -rf /usr/local/go && tar -C /usr/local -xzf /tmp/go.tar.gz
+echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
+echo 'export PATH=$PATH:~/go/bin' >> ~/.bashrc
+source ~/.bashrc
+go version
+```
+
+### upterm & uptermd aus Source bauen
+
+```bash
+git clone https://github.com/owenthereal/upterm.git
+cd upterm
+go build -o /usr/local/bin/uptermd ./cmd/uptermd/
+go build -o /usr/local/bin/upterm  ./cmd/upterm/
+```
+
+### Host-Keys generieren
+
+```bash
+mkdir -p /etc/uptermd/keys
+ssh-keygen -t ed25519 -f /etc/uptermd/keys/ed25519 -N ""
+ssh-keygen -t rsa -b 4096  -f /etc/uptermd/keys/rsa     -N ""
+
+# Berechtigungen für nobody
+chown -R nobody:nogroup /etc/uptermd/keys
+chmod 600 /etc/uptermd/keys/*
+```
+
+---
+
+## systemd Service
+
+Siehe [`uptermd.service`](uptermd.service).
+
+```bash
+systemctl daemon-reload
+systemctl enable --now uptermd
+systemctl status uptermd
+```
+
+> **Wichtig:** Kein `Type=forking` – uptermd daemonisiert sich nicht selbst.
+
+---
+
+## Erreichbarkeit
+
+### Primär: Port 2222 via Portweiterleitung im Router
+
+Einfachste Lösung – direkte TCP-Weiterleitung, kein Proxy nötig.
+
+| Feld | Wert |
+|------|------|
+| Externer Port | `2222` |
+| Internes Ziel | LAN-IP Server |
+| Interner Port | `2222` |
+| Protokoll | TCP |
+
+```bash
+ssh -p 2222 TOKEN:HASH@upterm.ebesch.de
+```
+
+### Alternativ: WebSocket via Nginx Proxy Manager (Port 443)
+
+Für Clients hinter restriktiven Firewalls. Erfordert `upterm` CLI auf Client-Seite.
+
+| Feld | Wert |
+|------|------|
+| Domain | `upterm.ebesch.de` |
+| Forward Host | LAN-IP Server |
+| Forward Port | `8080` |
+| WebSocket Support | ✅ aktivieren |
+| SSL | ✅ Let's Encrypt |
+
+```nginx
+# NPM Advanced – falls WebSocket-Header fehlen
+proxy_http_version 1.1;
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+```
+
+```bash
+ssh -o ProxyCommand='upterm proxy wss://TOKEN@upterm.ebesch.de' \
+    TOKEN@upterm.ebesch.de:443
+```
+
+---
+
+## Nutzung
+
+> **Wichtig:** Immer `--server` und `--accept` angeben.  
+> Ohne `--server` verbindet upterm mit dem öffentlichen uptermd.upterm.dev.  
+> Ohne `--accept` muss jede eingehende Verbindung manuell bestätigt werden.
+
+### Session starten
+
+```bash
+# Standard – eigener Server, automatisch akzeptieren
+upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash
+
+# Alternativ via WebSocket
+upterm host --server wss://upterm.ebesch.de --accept -- bash
+
+# tmux-Session teilen (empfohlen)
+upterm host --server ssh://upterm.ebesch.de:2222 --accept \
+  --force-command 'tmux attach -t shared' \
+  -- tmux new -t shared
+
+# Read-only (Kunde kann nur zuschauen)
+upterm host --server ssh://upterm.ebesch.de:2222 --accept --read-only -- bash
+```
+
+### Schnellstart per Alias
+
+```bash
+# ~/.bashrc oder ~/.zshrc
+alias share='upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash'
+```
+
+```bash
+share
+# Token erscheint sofort – kopieren und weitergeben
+```
+
+### Session-Info
+
+```bash
+upterm session current
+```
+
+### Client verbinden
+
+```bash
+# Ohne upterm CLI – nur SSH nötig (Port 2222)
+ssh -p 2222 TOKEN:HASH@upterm.ebesch.de
+
+# Mit upterm CLI via WebSocket (Port 443)
+ssh -o ProxyCommand='upterm proxy wss://TOKEN@upterm.ebesch.de' \
+    TOKEN@upterm.ebesch.de:443
+```
+
+---
+
+## Client-Anforderungen
+
+| Verbindungsweg | Client braucht |
+|---|---|
+| SSH Port 2222 (Portweiterleitung) | Nur `ssh` – nichts installieren |
+| WebSocket WSS Port 443 | `upterm` CLI |
+
+---
+
+## Referenzen
+
+- [GitHub – owenthereal/upterm](https://github.com/owenthereal/upterm)
+- [upterm.dev](https://upterm.dev)