# Upterm – Terminal Session Sharing

---

## ⚡ Schnellstart – Session teilen

> Voraussetzung: upterm installiert (siehe unten). Server läuft auf `upterm.ebesch.de`.

### Linux / macOS

```bash
upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash
```

Per Alias (in `~/.bashrc` / `~/.zshrc`):

```bash
alias share='upterm host --server ssh://upterm.ebesch.de:2222 --accept -- bash'
```

```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.

---


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

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