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

# Mit Docker
docker compose up -d

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

2. Tokens generieren

Auf dem ersten Client:

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

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

4. USB-Geraete empfangen (Use-Modus)

./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:

  sudo modprobe vhci-hcd
  

• Fuer automatisches Laden bei Boot:

  echo "vhci-hcd" | sudo tee /etc/modules-load.d/vhci-hcd.conf
  

Bauen

# Benoetigt Go 1.21+
make all

# Fuer Windows (Cross-Compilation):
make client-windows

Docker (Relay-Server)

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:

{
  "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

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

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 fuer Details.

Third-Party Lizenzen

Diese Software verwendet Open-Source-Bibliotheken. Siehe NOTICE fuer Details.