> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/run-the-platform/de/systemadministration/usb-passthrough.md). # USB-Passthrough Wie man USB-Geräte-Passthrough in VergeOS konfiguriert, einschließlich Host-Setup, Erstellung von Ressourcengruppen, VM-Gastkonfiguration und Durchreichen von USB-Geräten an Mandanten. An einen Host angeschlossene USB-Geräte können an VMs weitergereicht werden (und an Mandanten, damit diese sie an ihre VMs weiterreichen können), sodass ein Gerät so erscheint und sich so verhält, als wäre es direkt an die VM angeschlossen. Beispiele für USB-Passthrough-Geräte sind: * Laufwerke mit Software-Lizenzschlüsseln * Sicherheitskameras/Überwachungsausrüstung * Tastatur/Maus (unterstützt die Verwendung über mehrere VMs hinweg; oft bequemer als Dual-/Multi-Boot-VM-Konfigurationen für Spezialhardware) ## Host-Installation/Konfiguration Die folgenden Anweisungen konfigurieren das Device Passthrough, indem automatisch für jedes ausgewählte Gerät eine neue Regel erstellt und das/die Gerät(e) der Ressourcengruppe hinzugefügt wird/werden. Weitere Informationen darüber, wie Ressourcengruppen und Ressourcenregeln funktionieren, finden Sie unter: [**Geräte-Passthrough – Ressourcenregeln**](/run-the-platform/de/systemadministration/device-pass-overview.md#resource-rules). 1. Navigieren Sie zum **Dashboard des Ressourcen-Managers** (*Infrastruktur > Ressourcen*) **-ODER-** Navigieren Sie zu einem **bestimmten Knoten** auf dem die USB-Geräte angeschlossen sind. (*Infrastruktur > Knoten* > gewünschten Knoten in der Liste doppelklicken.) 2. Klicken Sie auf **USB-Geräte**. Die Liste der erkannten USB-Geräte wird angezeigt. {% hint style="success" %} **Ein USB-Gerät, bei dem im Feld *****Ressourcengruppe***** und *****Ressourcenregeln***** Werte angezeigt werden, ist bereits für Passthrough konfiguriert.** {% endhint %} 3. **Wählen Sie** die geeigneten **USB-Gerät(e)** aus der Liste aus. {% hint style="info" %} **Alle ausgewählten Geräte werden derselben Ressourcengruppe (Ressourcenpool) hinzugefügt, für jedes Gerät wird jedoch eine separate Ressourcenregel erstellt.** {% endhint %} 4. Klicken Sie auf **Ressource erstellen** im linken Menü. 5. **Eine neue USB-Ressourcengruppe erstellen** **-ODER-** **Eine USB-Ressourcengruppe auswählen** aus der Liste aus. ### Felder der USB-Ressourcengruppe * **Name**: Bezeichnung zur Identifizierung der Ressourcengruppe (d. h. des Gerätepools); verwenden Sie einen aussagekräftigen Namen, damit Benutzer leicht erkennen können, um welche Art von Gerät(en) es sich in dieser Gruppe handelt. * **Typ**: ***USB***. * **Beschreibung**: (optional) Feld für zusätzlichen administrativen Text zur Ressourcengruppe. * **Klasse**: ermöglicht die Auswahl einer allgemeinen Gerätekategorie für die Gruppe; zum Beispiel generisches USB-Gerät, Eingabegerät, Medien usw. Dieses Feld wird nur verwendet, um ein zugehöriges Symbol anzuwenden, und hat keinen Einfluss auf die Funktionalität. #### USB-Einstellungen * **Gast-Reset zulassen**: Wenn aktiviert, kann der VM-Benutzer das USB-Gerät zurücksetzen. * **Alle Gast-Resets zulassen**: Wenn aktiviert, kann der VM-Benutzer den USB-Hub zurücksetzen, an den das Gerät angeschlossen ist. {% hint style="info" %} **Die Rücksetzfunktion eines USB-Geräts hängt vom Gerätetreiber ab; einige Geräte unterstützen einen Reset, andere nicht.** {% endhint %} Nachdem die Ressourcengruppe ausgewählt oder eine neue erstellt wurde, sollte eine \**Erfolg* Meldung angezeigt werden, die darauf hinweist, dass für das/die Gerät(e) Ressourcenregeln erstellt wurden. 6. **Ein Neustart des/der zugehörigen Knoten(s) kann erforderlich sein**; oben im Dashboard des Ressourcen-Managers wird eine Meldung angezeigt. {% hint style="warning" %} **Beachten Sie die ordnungsgemäßen** [**Wartungsmodus**](/run-the-platform/de/betrieb/maintenance-mode.md) **Verfahren beim Neustart eines Knotens, um Beeinträchtigungen der Workloads zu vermeiden.** {% endhint %} Das Dashboard der Ressourcengruppe enthält die Ressourcenregeln, die automatisch für Ihre ausgewählten Geräte erstellt wurden. Sie können auf eine einzelne Regel klicken, um die Konfigurationsdetails anzuzeigen. Eine vom System erstellte Regel kann bei Bedarf geändert werden; zum Beispiel kann der *Knoten* Filter geändert werden zu *-- Keine --* um passende Geräte von allen Knoten einzubeziehen. Informationen zu Ressourcenregeln finden Sie unter: [**Übersicht über Device Passthrough – Ressourcenregeln**](/run-the-platform/de/systemadministration/device-pass-overview.md#resource-rules) ## VM/Gast-Konfiguration 1. Navigieren Sie zum **VM-Dashboard** (über das obere Menü: Virtuelle Maschinen > Liste > gewünschten VM-Eintrag in der Liste doppelklicken) 2. Klicken Sie auf **Geräte** im linken Menü. 3. Klicken Sie auf **Neu** im linken Menü. {% hint style="success" %} **Sie können Geräte auch über den Ressourcen-Manager an eine VM anhängen: im Dashboard der Ressourcengruppe > die gewünschte SR-IOV-Gruppe doppelklicken > Virtuelle Maschinen anzeigen > Neu; wählen Sie die VM aus der Dropdown-Liste „Maschine“ aus.** {% endhint %} ### Felder des Geräteeintragsformulars * **Name**: Geben Sie einen Namen an, um das Gerät zu identifizieren, z. B. „exapp license key“, oder lassen Sie das Feld leer, damit das System automatisch einen Gerätenamen erzeugt. * **Typ**: ***USB*** * **Beschreibung**: (optional) Hier kann zusätzlicher Text für administrative Zwecke eingegeben werden. * **Ressourcengruppe**: wählen Sie die passende USB-Ressourcengruppe aus der Dropdown-Liste aus * **USB-Einstellungen**: siehe oben. 4. Klicken Sie auf **Absenden** um das Hinzufügen des neuen Geräts abzuschließen. 5. Installieren Sie alle erforderlichen Client-Treiber; konsultieren Sie bei Bedarf die Hardwaredokumentation des Geräts. 6. Die VM benötigt einen **Neustart** um das Gerät anzuhängen. Klicken Sie im VM-Dashboard auf den *Neustart* -Link in der Meldung, die oben im Dashboard angezeigt wird, oder klicken Sie auf **Neustart** im linken Menü. ## Ein USB-Gerät an einen Mandanten durchreichen USB-Geräte können an einen Mandanten weitergereicht werden, damit der Mandant sie an seine eigenen VMs weiterreichen kann. Wenn Sie USB-Geräte an den Mandanten durchreichen, wird innerhalb des Mandanten eine neue Ressourcengruppe erstellt. {% hint style="info" %} **Wenn Geräte an einen Mandanten freigegeben werden, werden sie vollständig zugewiesen (d. h. der Mandant besitzt die Geräte dann, sodass sie auch bei Nichtbenutzung nicht anderen VMs oder Mandanten zugewiesen werden können.)** {% endhint %} 1. Navigieren Sie zum gewünschten **Mandanten-Dashboard** (über das obere Menü: Mandanten > Liste > den Mandanten in der Liste doppelklicken.) 2. Klicken Sie auf **Knoten** im linken Menü. 3. **Doppelklicken Sie auf einen der Mandantenknoten**. 4. Klicken Sie auf **Geräte** im linken Menü. 5. Klicken Sie auf **Neu** im linken Menü. 6. Geben Sie einen **Name** ein oder lassen Sie das Feld leer, damit das System automatisch einen Namen erstellt; dieser Name wird für die im Mandanten erstellte Ressourcengruppe verwendet. 7. **Typ**: ***USB***. 8. **Beschreibung**: bietet einen Ort zum Speichern zusätzlicher administrativer Informationen über das Gerät/den Gerätepool. 9. **USB-Einstellungen**: siehe oben. 10. Wenn die Felder ausgefüllt sind, klicken Sie auf **Absenden** um das Durchreichen an den Mandanten abzuschließen. 11. Das/die Gerät(e) sind nun als Ressourcengruppe verfügbar, die an Mandanten-VMs angehängt werden kann. Folgen Sie den [**VM/Gast-Konfiguration**](#vmguest-configuration) Anweisungen oben. Damit das Passthrough-Gerät verwendet werden kann, muss die VM auf dem Mandantenknoten ausgeführt werden, an den das Gerät angeschlossen ist. ## Fehlerbehebung ### VM startet nach einem Knoten-Neustart nicht **Symptom:** Eine VM mit einem USB-Passthrough-Gerät startet nach einem Neustart des Host-Knotens nicht (zum Beispiel nach einem VergeOS-Update). Die VM versucht wiederholt zu starten, kann das USB-Gerät jedoch nicht öffnen. **Ursache:** Die automatisch erzeugte Ressourcenregel identifiziert das Gerät anhand seiner physischen Busadresse (des Pfadfilters). Diese Adresse wird jedes Mal zugewiesen, wenn das USB-Gerät enumeriert wird. Änderungen in der Hardware-Topologie des Servers — etwa das Hinzufügen oder Entfernen von PCI-Geräten — können die Art und Weise verändern, wie der USB-Controller seine Ports darstellt, was zu einem anderen Pfad führt. Auf einer kleinen Minderheit von Systemen kann die Firmware des Mainboards USB-Ports nach einem Controller-Reset anders neu enumerieren, sodass sich der Pfad auch ohne Hardwareänderungen ändert. Wenn das Gerät an einer neuen Adresse erscheint, stimmt die Regel nicht mehr mit einem aktiven Gerät überein, wodurch das Starten der VM verhindert wird. **Behebung:** Bearbeiten Sie die Ressourcenregel so, dass das Gerät anhand seiner stabilen Hardware-IDs statt anhand der physischen Adresse übereinstimmt: 1. Navigieren Sie zu **Infrastruktur > Ressourcen**. 2. In den ***Regeln*** Abschnitt finden Sie die automatisch erzeugte Regel für das USB-Gerät. 3. **Doppelklicken Sie auf die Regel** um sie zur Bearbeitung zu öffnen. 4. Aktivieren Sie die **Hersteller-ID** (`vendor_id`) und **Modell-ID** (`model_id`) Filterfelder. Die Modell-ID ist die USB-Produkt-ID. 5. Aktivieren Sie die **Seriennummer** Feld (nur unterstützte Geräte), um die Regel auf ein bestimmtes Gerät festzulegen. Die meisten USB-Sticks, externen HDDs/SSDs, Webcams und Drucker/Scanner namhafter Hersteller enthalten eine eindeutige, ab Werk programmierte Seriennummer. 6. Deaktivieren Sie die Filterfelder für den physischen Standort (Pfad und Gerät), wenn Ihr Server über mehrere Starts hinweg keinen konsistenten PCI-Pfad zuweist. Sie können diese Felder auch deaktivieren, wenn die Regel das Gerät unabhängig davon erfassen soll, an welchem USB-Port es angeschlossen ist. 7. Klicken Sie auf **Absenden** um die Regel zu speichern. 8. Starten Sie die VM. Hersteller-, Modell-ID- und Seriennummer bleiben über Neustarts hinweg stabil, sodass die Regel das Gerät unabhängig davon findet, wie es neu enumeriert wird. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/run-the-platform/de/systemadministration/usb-passthrough.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.