233 lines
6.5 KiB
Markdown
233 lines
6.5 KiB
Markdown
# 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
|
|
|
|
### Voraussetzungen
|
|
|
|
**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
|
|
|
|
```bash
|
|
# Benoetigt Go 1.21+
|
|
make all
|
|
|
|
# Fuer Windows (Cross-Compilation):
|
|
make client-windows
|
|
```
|
|
|
|
### 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.
|