usb-server/README.md

# USB Server

USB-Sharing ueber Netzwerk mit Relay-Server fuer NAT-Traversal.

## Architektur

```
┌──────────────────┐         ┌──────────────┐         ┌──────────────────┐
│  Client (share)  │──ws/wss─│ Relay Server │─ws/wss──│  Client (use)    │
│  gibt USB-Geraete│         │ (Docker)     │         │  empfaengt USB-  │
│  frei            │         │ gruppiert    │         │  Geraete         │
│  Web-UI :8080    │         │ nach Hash    │         │  Web-UI :8080    │
└────────┬─────────┘         └──────────────┘         └────────┬─────────┘
         │                                                     │
    Physische USB                                     Virtuelle USB
    Geraete                                           (vhci-hcd)
```

**Relay-Server:** Einfacher WebSocket-Vermittler. Braucht keine Konfiguration - verbindet alle Clients die den gleichen Hash haben. Als Docker-Container deploybar.

**Client:** Kann in zwei Modi betrieben werden:
- **Share-Modus:** Gibt alle lokalen USB-Geraete frei. Geraete werden erst dann vom System getrennt wenn ein Use-Client sie anfordert.
- **Use-Modus:** Zeigt verfuegbare Geraete von allen Share-Clients an. Geraete koennen einzeln verbunden/getrennt werden.

**Gruppierung:** 3 zufaellige Tokens werden zu einem SHA256-Hash kombiniert. Alle Clients mit dem gleichen Hash gehoeren zusammen.

## Quick Start

### 1. Relay-Server starten

```bash
# Mit Docker
docker compose up -d

# Oder direkt
make relay
./bin/usb-relay --port 8443
```

### 2. Tokens generieren

Auf dem ersten Client:

```bash
./bin/usb-client generate-token
```

Ausgabe:
```
Token 1: aB3dE...
Token 2: xY7zW...
Token 3: mN4pQ...
Hash:    a1b2c3d4e5...
```

Die 3 Tokens auf alle weiteren Clients kopieren.

### 3. USB-Geraete freigeben (Share-Modus)

```bash
./bin/usb-client share --relay ws://relay-server:8443
```

### 4. USB-Geraete empfangen (Use-Modus)

```bash
./bin/usb-client use --relay ws://relay-server:8443
```

Web-UI oeffnen: http://localhost:8080

## Installation

### Go installieren

#### Linux (Debian/Ubuntu)

```bash
# Aktuelle Version herunterladen (go1.25.0 oder neuer)
wget https://go.dev/dl/go1.25.0.linux-amd64.tar.gz

# Altes Go entfernen und neues installieren
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz

# PATH einrichten - ans Ende von ~/.bashrc oder ~/.profile anfuegen:
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Pruefen
go version
```

#### Windows

1. Installer herunterladen: https://go.dev/dl/ (Datei `go1.25.0.windows-amd64.msi`)
2. MSI-Installer ausfuehren - installiert Go nach `C:\Program Files\Go`
3. Der Installer richtet den PATH automatisch ein
4. Neue Eingabeaufforderung oeffnen und pruefen:
   ```cmd
   go version
   ```

Falls der PATH nicht automatisch gesetzt wurde:
1. Windows-Taste > "Umgebungsvariablen" suchen > "Umgebungsvariablen fuer dieses Konto bearbeiten"
2. Variable `Path` bearbeiten > Neu > `C:\Program Files\Go\bin` hinzufuegen
3. Eingabeaufforderung neu oeffnen

### Make installieren

#### Linux (Debian/Ubuntu)

```bash
sudo apt update
sudo apt install make
```

#### Linux (Fedora/RHEL)

```bash
sudo dnf install make
```

#### Windows

**Option A: Chocolatey** (empfohlen)
```powershell
# Chocolatey installieren (Admin-PowerShell):
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Make installieren:
choco install make
```

**Option B: MSYS2**
1. MSYS2 von https://www.msys2.org herunterladen und installieren
2. In der MSYS2-Shell:
   ```bash
   pacman -S make
   ```
3. `C:\msys64\usr\bin` zum Windows PATH hinzufuegen

**Option C: Ohne Make** - Go-Befehle direkt ausfuehren (siehe unten)

### Plattform-Unterstuetzung

| Funktion | Linux | Windows |
|----------|-------|---------|
| Share-Modus (USB-Geraete freigeben) | Ja | Nein (kein usbdevfs) |
| Use-Modus (USB-Geraete empfangen) | Ja (vhci-hcd) | Ja (usbip-win2) |
| Relay-Server | Ja | Ja |
| Web-UI / Config | Ja | Ja |

**Windows Use-Modus:** Benoetigt den [usbip-win2](https://github.com/vadimgrn/usbip-win2/releases) VHCI-Treiber (WHKL-zertifiziert, Microsoft-signiert). Der Client erkennt automatisch ob usbip-win2 installiert ist.

**Windows Share-Modus:** Nicht verfuegbar - erfordert Linux-spezifische Kernel-Schnittstelle (usbdevfs).

### Voraussetzungen (Laufzeit)

**Linux (Share-Modus):**
- Root-Rechte (fuer USB-Geraetezugriff)

**Linux (Use-Modus):**
- Kernel-Modul `vhci-hcd`:
  ```bash
  sudo modprobe vhci-hcd
  ```
- Fuer automatisches Laden bei Boot:
  ```bash
  echo "vhci-hcd" | sudo tee /etc/modules-load.d/vhci-hcd.conf
  ```

### Bauen

#### Mit Make

```bash
# Alles bauen (Relay + Client, Linux)
make all

# Nur Relay-Server
make relay

# Nur Client (Linux)
make client

# Client fuer Windows (Cross-Compilation von Linux)
make client-windows
```

#### Ohne Make (Go direkt)

```bash
# Linux Relay-Server
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/usb-relay ./cmd/usb-relay/

# Linux Client
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/usb-client ./cmd/usb-client/

# Windows Client (Cross-Compilation von Linux)
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o bin/usb-client.exe ./cmd/usb-client/
```

Unter Windows (cmd.exe):
```cmd
set CGO_ENABLED=0
go build -ldflags="-s -w" -o bin\usb-client.exe ./cmd/usb-client/
```

Unter Windows (PowerShell):
```powershell
$env:CGO_ENABLED=0
go build -ldflags="-s -w" -o bin\usb-client.exe ./cmd/usb-client/
```

### Docker (Relay-Server)

```bash
docker compose up -d
```

Der Relay lauscht auf Port 8443.

## CLI Befehle

```
usb-client generate-token          # 3 Tokens + Hash generieren
usb-client share [optionen]        # Share-Modus starten
usb-client use [optionen]          # Use-Modus starten
usb-client list                    # Lokale USB-Geraete auflisten
usb-client gui                     # Nur Web-UI starten
usb-client config                  # Konfiguration anzeigen
usb-client config set [optionen]   # Konfiguration aendern
usb-client install-service         # Als systemd-Service installieren
usb-client uninstall-service       # Service deinstallieren
```

### Optionen

```
--config <pfad>    Config-Datei (Standard: ~/.usb-server/config.json)
--relay <adresse>  Relay-Server (z.B. ws://localhost:8443)
--hash <hash>      Gruppen-Hash
--name <name>      Client-Name
--web-port <port>  Web-UI Port (Standard: 8080)
--no-gui           Web-UI deaktivieren
```

## Web-UI

Die Web-UI ist unter http://localhost:8080 erreichbar und bietet:

- **Geraete-Tab:** Liste aller verfuegbaren/verbundenen USB-Geraete
- **Einstellungen:** Relay-Adresse, Modus, Name konfigurieren
- **Token:** Tokens generieren oder eintragen
- **Service:** Als Systemdienst installieren/deinstallieren

## Konfiguration

Die Konfiguration wird in `~/.usb-server/config.json` gespeichert:

```json
{
  "relay_addr": "ws://localhost:8443",
  "hash": "a1b2c3d4...",
  "mode": "use",
  "name": "Mein-PC",
  "web_port": 8080,
  "token1": "...",
  "token2": "...",
  "token3": "...",
  "auto_connect": [
    {"vendor_id": "1234", "product_id": "5678"},
    {"bus_id": "1-1.4"}
  ]
}
```

## Als Service installieren

```bash
# Service installieren (braucht root)
sudo ./bin/usb-client install-service

# Service Status pruefen
systemctl status usb-client

# Service deinstallieren
sudo ./bin/usb-client uninstall-service
```

## Sicherheit

- **Transport-Verschluesselung:** Verwende `wss://` (WebSocket over TLS) fuer den Relay-Server bei Einsatz ueber das Internet.
- **Gruppierung:** Die 3 Tokens dienen als gemeinsames Geheimnis. Nur wer alle 3 Tokens kennt kann den Hash berechnen.
- **Relay:** Der Relay-Server sieht nur den Hash, nicht die Tokens.

Fuer TLS am Relay-Server empfiehlt sich ein Reverse-Proxy (nginx/traefik) mit Let's Encrypt:

```nginx
server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    location /ws {
        proxy_pass http://localhost:8443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## Technische Details

- **Sprache:** Go (single binary, keine Runtime-Abhaengigkeiten)
- **USB/IP:** Natives USB/IP-Protokoll (kein externes `usbip`-Paket noetig)
- **USB-Zugriff:** Direkte usbdevfs-ioctls (kein CGO/libusb)
- **VHCI:** Direkte sysfs-Schnittstelle zum vhci-hcd Kernel-Modul
- **Relay:** WebSocket mit JSON-Kontrollnachrichten und Binary-Tunneldaten
- **Tunnel:** USB/IP-Protokolldaten werden durch WebSocket-Binary-Frames getunnelt

## Verzeichnisstruktur

```
cmd/usb-relay/       - Relay-Server Binary
cmd/usb-client/      - Client Binary (share + use Modi)
internal/relay/      - WebSocket Relay & Hub
internal/protocol/   - Nachrichtentypen
internal/client/     - Client Core, Share & Use Manager
internal/usbip/      - USB/IP Protokoll, Server, VHCI
internal/usb/        - USB Enumeration & usbdevfs
internal/token/      - Token-Generierung
internal/config/     - Konfiguration
internal/web/        - Web-UI (embedded)
internal/service/    - Systemd Service
```

## Lizenz

Proprietaere Software. Alle Rechte vorbehalten.
Siehe [LICENSE](LICENSE) fuer Details.

### Third-Party Lizenzen

Diese Software verwendet Open-Source-Bibliotheken. Siehe [NOTICE](NOTICE) fuer Details.