321 lines
7.8 KiB
Markdown
321 lines
7.8 KiB
Markdown
# 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.
|
||
|
||
---
|
||
|
||
## ⚡ Schnellstart – Session teilen
|
||
|
||
> Voraussetzung: upterm installiert (siehe [Client Installation](#client-installation)).
|
||
|
||
### Linux
|
||
|
||
```bash
|
||
upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash
|
||
```
|
||
|
||
Per Alias (in `~/.bashrc`):
|
||
|
||
```bash
|
||
alias share='upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash'
|
||
share
|
||
```
|
||
|
||
### macOS
|
||
|
||
```bash
|
||
upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash
|
||
```
|
||
|
||
Per Alias (in `~/.zshrc`):
|
||
|
||
```bash
|
||
alias share='upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash'
|
||
share
|
||
```
|
||
|
||
### Windows (PowerShell)
|
||
|
||
```powershell
|
||
upterm host --server ssh://upterm.ebesch.de:2222 --accept
|
||
```
|
||
|
||
---
|
||
|
||
Nach dem Start erscheint der Verbindungstoken sofort im Terminal:
|
||
|
||
```
|
||
➤ SSH: ssh TOKEN:HASH@upterm.ebesch.de -p 2222
|
||
```
|
||
|
||
**Token kopieren und weitergeben** – der Empfänger verbindet sich mit:
|
||
|
||
```bash
|
||
ssh TOKEN:HASH@upterm.ebesch.de -p 2222
|
||
```
|
||
|
||
> Kein Tool auf Client-Seite nötig – nur ein SSH-Client.
|
||
|
||
---
|
||
|
||
## Client Installation
|
||
|
||
### macOS
|
||
|
||
Installation via [Homebrew](https://brew.sh):
|
||
|
||
```bash
|
||
brew install owenthereal/upterm/upterm
|
||
```
|
||
|
||
### Linux (Debian / Ubuntu)
|
||
|
||
Installation via `.deb`-Paket aus den GitHub Releases:
|
||
|
||
```bash
|
||
curl -sL https://github.com/owenthereal/upterm/releases/latest/download/upterm_linux_amd64.deb -o /tmp/upterm.deb
|
||
sudo dpkg -i /tmp/upterm.deb
|
||
```
|
||
|
||
ARM64 (z. B. Raspberry Pi):
|
||
|
||
```bash
|
||
curl -sL https://github.com/owenthereal/upterm/releases/latest/download/upterm_linux_arm64.deb -o /tmp/upterm.deb
|
||
sudo dpkg -i /tmp/upterm.deb
|
||
```
|
||
|
||
### Windows
|
||
|
||
**Option A – Build aus Source (empfohlen für Windows Server 2016)**
|
||
|
||
Kein Paketmanager nötig. Go wird direkt von golang.org geladen, upterm wird lokal kompiliert.
|
||
|
||
| Datei | Funktion |
|
||
|-------|----------|
|
||
| [`build-windows.bat`](build-windows.bat) | Doppelklick-Starter |
|
||
| [`build-windows.ps1`](build-windows.ps1) | Lädt Go, baut upterm per `go install`, kopiert nach System32 |
|
||
|
||
Schritte automatisch: Go 1.22.4 (MSI silent) → `go install github.com/owenthereal/upterm/cmd/upterm@latest` → `upterm.exe` nach `C:\Windows\System32`.
|
||
|
||
---
|
||
|
||
**Option B – Scoop (Windows 10 / Server 2019+)**
|
||
|
||
Schnellsetup auf neuem Gerät – beide Dateien herunterladen, `setup-windows.bat` doppelklicken:
|
||
|
||
| Datei | Funktion |
|
||
|-------|----------|
|
||
| [`setup-windows.bat`](setup-windows.bat) | Doppelklick-Starter, fordert Adminrechte an |
|
||
| [`setup-windows.ps1`](setup-windows.ps1) | Eigentliche Installationslogik |
|
||
|
||
Das Skript erledigt automatisch: Execution Policy, Scoop-Installation, 7zip-Workaround (lessmsi), upterm.
|
||
|
||
> **Windows Server 2016:** TLS 1.2 wird im Skript explizit erzwungen – kein manueller Eingriff nötig.
|
||
|
||
---
|
||
|
||
Manuelle Installation via [Scoop](https://scoop.sh):
|
||
|
||
**1. Berechtigungen – Execution Policy setzen** (einmalig, PowerShell als Administrator):
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
```
|
||
|
||
**2. Scoop installieren:**
|
||
|
||
```powershell
|
||
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
|
||
```
|
||
|
||
> Scoop installiert sich benutzerspezifisch nach `%USERPROFILE%\scoop\`.
|
||
> PowerShell nach der Installation neu starten, damit der PATH wirksam wird.
|
||
|
||
**3. upterm installieren:**
|
||
|
||
```powershell
|
||
scoop bucket add upterm https://github.com/owenthereal/scoop-upterm
|
||
scoop install upterm
|
||
```
|
||
|
||
#### Bekanntes Problem: 7zip Exit code 1640
|
||
|
||
Scoop benötigt `7zip` als Abhängigkeit. Auf manchen Systemen schlägt die MSI-Extraktion fehl:
|
||
|
||
```
|
||
ERROR Exit code was 1640!
|
||
Failed to extract files from ...\7z2601-x64.msi.
|
||
```
|
||
|
||
Ursache: UAC/Sitzungskonflikt bei MSI-Paketen. Workaround mit `lessmsi`:
|
||
|
||
```powershell
|
||
scoop uninstall 7zip
|
||
scoop cache rm 7zip
|
||
Remove-Item -Recurse -Force "$env:USERPROFILE\scoop\apps\7zip" -ErrorAction SilentlyContinue
|
||
|
||
scoop config use_lessmsi true
|
||
scoop install 7zip
|
||
```
|
||
|
||
Danach `scoop install upterm` erneut ausführen.
|
||
|
||
#### Troubleshooting Windows
|
||
|
||
| Problem | Ursache | Lösung |
|
||
|---------|---------|--------|
|
||
| `Skriptausführung deaktiviert` | Execution Policy zu restriktiv | `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |
|
||
| 7zip Exit code 1640 | MSI-Sitzungskonflikt (UAC) | `scoop config use_lessmsi true`, dann 7zip neu |
|
||
| Host-Key Warnung | Erster Verbindungsaufbau | Einmalig `yes` – Fingerprint: `SHA256:nOHK++kJYUJz1bqUY1AM6defn36vTXsgWuSEhr3ltLk` |
|
||
| `upterm` nicht gefunden | PATH noch nicht aktiv | PowerShell neu starten |
|
||
|
||
---
|
||
|
||
## Details & Server-Setup
|
||
|
||
### 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)
|
||
```
|
||
|
||
---
|
||
|
||
### Server: 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 ""
|
||
|
||
chown -R nobody:nogroup /etc/uptermd/keys
|
||
chmod 600 /etc/uptermd/keys/*
|
||
```
|
||
|
||
---
|
||
|
||
### Server: 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.
|
||
|
||
---
|
||
|
||
### Server: Erreichbarkeit
|
||
|
||
#### Primär: Port 2222 via Portweiterleitung im Router
|
||
|
||
| 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
|
||
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 (erweitert)
|
||
|
||
```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
|
||
|
||
# Session-Info anzeigen
|
||
upterm session current
|
||
```
|
||
|
||
---
|
||
|
||
### Zusammenspiel mit Teleport
|
||
|
||
| | Teleport | Upterm |
|
||
|---|---|---|
|
||
| Zweck | Access-Management, Audit | Session-Sharing / Pairing |
|
||
| Zielgruppe | Internes Team | Externe ohne Teleport-Zugang |
|
||
| Persistent | Ja (systemd) | Nur während aktiver Session |
|
||
| Ports | 3022, 3080 | 2222, 8080 |
|
||
|
||
> Faustregel: Teleport für das interne Team, Upterm für Kunden oder externe Kollegen die nur SSH benötigen.
|
||
|
||
---
|
||
|
||
## Referenzen
|
||
|
||
- [GitHub – owenthereal/upterm](https://github.com/owenthereal/upterm)
|
||
- [upterm.dev](https://upterm.dev)
|