first commit
This commit is contained in:
Stefan Hacker
@@ -0,0 +1,232 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user