upterm/README.md at aa9f37557eb78cec18b0ac60eebbc0f309c1e5a3

Files

Ralf-Peter Wolff aa9f37557e Expand Windows section: execution policy, UAC/MSI error explanation, permission notes

2026-05-04 11:32:59 +02:00

7.5 KiB

Raw Blame History

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

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

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

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.

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

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

# NPM Advanced – falls WebSocket-Header fehlen
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

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

# 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

# ~/.bashrc oder ~/.zshrc
alias share='upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash'

share
# Token erscheint sofort – kopieren und weitergeben

Session-Info

upterm session current

Client verbinden

# 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

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):

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:

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:

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:

# 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):

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):

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

7.5 KiB Raw Blame History Unescape Escape

Upterm – Terminal Session Sharing