Initial commit: Upterm setup documentation
This commit is contained in:
187
README.md
Normal file
187
README.md
Normal file
@ -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)
|
||||
Reference in New Issue
Block a user