rpwolff/upterm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure: quick start first, client install per OS (brew/apt/scoop), details at bottom

Browse Source
This commit is contained in:
Ralf-Peter Wolff
2026-05-04 11:37:54 +02:00
parent 59fe939b27
commit 227567d5db
1 changed files with 120 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
README.md
View File

@ -1,24 +1,36 @@
# 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 unten). Server läuft auf `upterm.ebesch.de`.
> Voraussetzung: upterm installiert (siehe [Client Installation](#client-installation)).
### Linux / macOS
### Linux
```bash
upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash
```
Per Alias (in `~/.bashrc` / `~/.zshrc`):
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
```
@ -46,10 +58,94 @@ ssh TOKEN:HASH@upterm.ebesch.de -p 2222
---
## Client Installation
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.
### macOS
## Architektur
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
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]
@ -71,9 +167,9 @@ ssh -p 2222 ... upterm proxy wss://...
---
## Installation & Build
### Server: Installation & Build
### Go installieren
#### Go installieren
```bash
curl -sL https://go.dev/dl/go1.22.4.linux-amd64.tar.gz -o /tmp/go.tar.gz
@ -84,7 +180,7 @@ source ~/.bashrc
go version
```
### upterm & uptermd aus Source bauen
#### upterm & uptermd aus Source bauen
```bash
git clone https://github.com/owenthereal/upterm.git
@ -93,21 +189,20 @@ go build -o /usr/local/bin/uptermd ./cmd/uptermd/
go build -o /usr/local/bin/upterm ./cmd/upterm/
```
### Host-Keys generieren
#### 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
### Server: systemd Service
Siehe [`uptermd.service`](uptermd.service).
@ -121,11 +216,9 @@ systemctl status uptermd
---
## Erreichbarkeit
### Server: Erreichbarkeit
### Primär: Port 2222 via Portweiterleitung im Router
Einfachste Lösung – direkte TCP-Weiterleitung, kein Proxy nötig.
#### Primär: Port 2222 via Portweiterleitung im Router
| Feld | Wert |
|------|------|
@ -138,7 +231,7 @@ Einfachste Lösung – direkte TCP-Weiterleitung, kein Proxy nötig.
ssh -p 2222 TOKEN:HASH@upterm.ebesch.de
```
### Alternativ: WebSocket via Nginx Proxy Manager (Port 443)
#### Alternativ: WebSocket via Nginx Proxy Manager (Port 443)
Für Clients hinter restriktiven Firewalls. Erfordert `upterm` CLI auf Client-Seite.
@ -151,7 +244,6 @@ Für Clients hinter restriktiven Firewalls. Erfordert `upterm` CLI auf Client-Se
| 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";
@ -164,21 +256,9 @@ ssh -o ProxyCommand='upterm proxy wss://TOKEN@upterm.ebesch.de' \
---
## 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
### Nutzung (erweitert)
```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' \
@ -186,45 +266,23 @@ upterm host --server ssh://upterm.ebesch.de:2222 --accept \
# 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
# Session-Info anzeigen
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
### Zusammenspiel mit Teleport
| Verbindungsweg | Client braucht |
|---|---|
| SSH Port 2222 (Portweiterleitung) | Nur `ssh` – nichts installieren |
| WebSocket WSS Port 443 | `upterm` CLI |
| | 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.
---
@ -232,115 +290,3 @@ ssh -o ProxyCommand='upterm proxy wss://TOKEN@upterm.ebesch.de' \
- [GitHub – owenthereal/upterm](https://github.com/owenthereal/upterm)
- [upterm.dev](https://upterm.dev)
---
## Windows Client
### Voraussetzungen & Berechtigungen
PowerShell muss Skripte aus dem Internet ausführen dürfen. Standard-Installation blockiert dies.
**Execution Policy setzen** (einmalig, PowerShell als Administrator):
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
> **Hinweis:** Der Log zeigt die Installation unter dem `Administrator`-Konto (`C:\Users\Administrator>`).
> Scoop installiert sich dabei in `%USERPROFILE%\scoop\` – also benutzerspezifisch, nicht systemweit.
> Auf normalen Benutzerkonten ist das Vorgehen identisch.
---
### Installation via Scoop
**1. Scoop installieren:**
```powershell
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
```
Scoop fügt `~\scoop\shims` automatisch zum PATH hinzu.
**PowerShell nach der Installation neu starten**, damit der PATH wirksam wird.
**2. upterm-Bucket hinzufügen und upterm installieren:**
```powershell
scoop bucket add upterm https://github.com/owenthereal/scoop-upterm
scoop install upterm
```
---
### Bekanntes Problem: 7zip Exit code 1640
Scoop installiert `7zip` als Abhängigkeit via MSI. Auf manchen Systemen schlägt die MSI-Extraktion fehl:
```
ERROR Exit code was 1640!
Failed to extract files from ...\7z2601-x64.msi.
```
Fehlercode 1640 bedeutet: Installation aus einer anderen Sitzungsebene heraus nicht erlaubt (UAC/Sitzungskonflikt bei MSI-Paketen).
**Workaround – lessmsi als MSI-Extraktor verwenden:**
```powershell
# Fehlgeschlagene Installation bereinigen
scoop uninstall 7zip
scoop cache rm 7zip
Remove-Item -Recurse -Force "$env:USERPROFILE\scoop\apps\7zip" -ErrorAction SilentlyContinue
# lessmsi aktivieren (ersetzt den Windows Installer für MSI-Pakete)
scoop config use_lessmsi true
# 7zip erneut installieren
scoop install 7zip
```
Danach läuft `scoop install upterm` ohne weitere Probleme durch.
---
### Nutzung unter Windows
**Session starten (PowerShell):**
```powershell
upterm host --server ssh://upterm.ebesch.de:2222 --accept
```
Beim **ersten Verbinden** erscheint eine Host-Key-Warnung – einmalig mit `yes` bestätigen:
```
The authenticity of host '[upterm.ebesch.de]:2222 ...' can't be established.
ED25519 key fingerprint is SHA256:nOHK++kJYUJz1bqUY1AM6defn36vTXsgWuSEhr3ltLk.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
```
Danach erscheint der Token sofort:
```
Session: MCZoCPoVAz5uTINZkdNN
➤ SSH: ssh TOKEN:HASH@upterm.ebesch.de -p 2222
➤ SFTP: sftp -P 2222 TOKEN:HASH@upterm.ebesch.de
```
> Unter Windows startet upterm eine `powershell -NoLogo` Session statt `bash`.
**Client verbindet sich (nur SSH nötig):**
```powershell
ssh TOKEN:HASH@upterm.ebesch.de -p 2222
```
---
### Troubleshooting
| 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 installieren |
| Host-Key Warnung | Erster Verbindungsaufbau | Einmalig `yes` – Fingerprint: `SHA256:nOHK++kJYUJz1bqUY1AM6defn36vTXsgWuSEhr3ltLk` |
| `upterm` nicht gefunden | PATH noch nicht aktiv | PowerShell neu starten |