---
title: Kapitel 25. USB Gerätemodus
part: Teil III. Systemadministration
prev: books/handbook/dtrace
next: books/handbook/partiv
---

[[usb-device-mode]]
= USB Gerätemodus
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:table-caption: Tabelle
:figure-caption: Abbildung
:example-caption: Beispiel
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:sectnumoffset: 25

ifeval::["{backend}" == "html5"]
:imagesdir: ../../../images/books/handbook/usb-device-mode/
endif::[]

ifeval::["{backend}" == "pdf"]
:imagesdir: ../../../../static/images/books/handbook/usb-device-mode/
endif::[]

ifeval::["{backend}" == "epub3"]
:imagesdir: ../../../../static/images/books/handbook/usb-device-mode/
endif::[]

include::shared/authors.adoc[]
include::shared/releases.adoc[]
include::shared/de/mailing-lists.adoc[]
include::shared/de/teams.adoc[]
include::shared/de/urls.adoc[]

toc::[]

[[usb-device-mode-synopsis]]
== Übersicht

Dieses Kapitel behandelt die Verwendung des USB Gerätemodus und USB On-The-Go (USB OTG) unter FreeBSD. Dazu gehören virtuelle serielle Konsolen, virtuelle Netzwerkkarten und virtuelle USB-Laufwerke.

Wenn die eingesetzte Hardware den USB-Gerätemodus oder USB OTG unterstützt, kann FreeBSDs USB-Stack im Gerätemodus ausgeführt werden. Solche Hardware wird häufig in eingebetteten Systeme verbaut. Der Gerätemodus ermöglicht es dem Rechner verschiedene Arten von USB-Geräteklassen darzustellen, einschließlich serieller Schnittstellen, Netzwerkkarten und Massenspeicher oder Kombinationen davon. Ein USB-Host, beispielsweise ein Notebook oder ein Desktop-Rechner, kann wie auf ein physisches USB-Gerät darauf zugreifen.

Es gibt zwei grundlegende Möglichkeiten, wie die Hardware den Gerätemodus bereitstellen kann: mit einem separaten "Client Modus", der nur den Gerätemodus unterstützt, und mit einem USB-OTG-Port, der sowohl den Geräte- als auch den Hostmodus bereitstellen kann. Bei USB-OTG-Ports wechselt der USB-Stack automatisch zwischen host- und geräteseitig, je nachdem, was an dem Port angeschlossen ist. Wenn Sie ein USB-Gerät wie einen Speicherstick an den Port anschließen, wechselt FreeBSD in den Hostmodus. Wenn Sie einen USB-Host wie einen Computer anschließen, wechselt FreeBSD in den Gerätemodus. "Client Ports" arbeiten immer im Gerätemodus.

Was FreeBSD dem USB-Host präsentiert, hängt von der sysctl-Variable `hw.usb.template` ab. Einige Vorlagen bieten ein einzelnes Gerät, beispielsweise ein serielles Terminal, andere bieten mehrere, die alle gleichzeitig verwendet werden können. Ein Beispiel ist die Vorlage 10, die ein Massenspeichergerät, eine serielle Konsole und eine Netzwerkkarte bereitstellt. man:usb_template[4] enthält eine Liste der verfügbaren Werte.

Beachten Sie, dass in einigen Fällen, abhängig von der Hardware und dem Betriebssystem des Hosts, die Änderung an der Konfiguration nur dann bemerkt werden kann, wenn der Host entweder physisch getrennt und wieder verbunden oder gezwungen wird, den USB-Bus auf eine systemspezifische Weise neu zu scannen. Wenn FreeBSD auf dem Host läuft, kann man:usbconfig[8] `reset` verwendet werden. Dies muss auch nach dem Laden von [.filename]#usb_template.ko# geschehen, wenn der USB-Host bereits an der USB OTG-Buchse angeschlossen war.

Nachdem Sie dieses Kapitel gelesen haben, werden Sie wissen:

* wie man den USB Gerätemodus unter FreeBSD einrichtet.
* wie man die virtuelle serielle Schnittstelle unter FreeBSD konfiguriert.
* wie man sich mit der virtuellen seriellen Schnittstelle von verschiedenen Betriebssystemen aus verbindet.

[[usb-device-mode-terminals]]
== Virtuelle serielle USB-Ports

=== Konfiguration des USB-Gerätemodus für serielle Ports

Die virtuellen seriellen Ports werden durch die Vorlagen 3, 8 und 10 unterstützt. Beachten Sie, dass Vorlage 3 mit Microsoft Windows 10 ohne spezielle Treiber und INF-Dateien funktioinert. Andere Host-Betriebssysteme arbeiten mit allen drei Vorlagen. Die beiden Kernelmodule man:usb_template[4] und man:umodem[4] müssen geladen werden.

Um die seriellen Ports im USB-Gerätemodus zu aktivieren, fügen Sie folgenden Zeilen in [.filename]#/etc/ttys# hinzu:

[.programlisting]
....
ttyU0	"/usr/libexec/getty 3wire"	vt100	onifconsole secure
ttyU1	"/usr/libexec/getty 3wire"    vt100   onifconsole secure
....

Danach fügen Sie folgende Zeilen in [.filename]#/etc/devd.conf# hinzu:

[.programlisting]
....
notify 100 {
	match "system"		"DEVFS";
	match "subsystem"	"CDEV";
	match "type"		"CREATE";
	match "cdev"		"ttyU[0-9]+";
	action "/sbin/init q";
};
....

Laden Sie die Konfiguration neu, falls man:devd[8] bereits läuft:

[source,bash]
....
# service devd restart
....

Stellen Sie sicher, dass die notwendigen Module geladen sind und die richtige Vorlage beim Booten gesetzt ist. Fügen Sie dazu folgende Zeilen in [.filename]#/boot/loader.conf# ein:

[.programlisting]
....
umodem_load="YES"
hw.usb.template=3
....

Um das Modul zu laden und die Vorlage ohne Neustart zu aktivieren, verwenden Sie:

[source,bash]
....
# kldload umodem
# sysctl hw.usb.template=3
....

=== FreeBSD mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Verwenden Sie `pstat -t` auf dem Host, um die Terminalzeilen aufzulisten. Am Ende der Liste sollten Sie einen seriellen USB-Anschluss sehen, zum Beispiel "ttyU0". Um die Verbindung zu öffnen, benutzen Sie:

[source,bash]
....
# cu -l /dev/ttyU0
....

Nach mehrmaligem Drücken der kbd:[Enter]-Taste erscheint ein Anmeldeprompt.

=== macOS mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Um die Verbindung zu öffnen, benutzen Sie:

[source,bash]
....
# cu -l /dev/cu.usbmodemFreeBSD1
....

=== Linux mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Um die Verbindung zu öffnen, benutzen Sie:

[source,bash]
....
# minicom -D /dev/ttyACM0
....

=== Windows 10 mit der seriellen Schnittstelle im USB-Gerätemodus verbinden

Um eine Verbindung zu einer Karte herzustellen, die so konfiguriert ist, dass sie serielle Ports im USB-Gerätemodus bereitstellt, schließen Sie den USB-Host, beispielsweise einen Laptop, an den USB OTG- oder USB-Client-Port der Karte an. Um die Verbindung zu öffnen, benötigen Sie ein Terminalprogramm mit Unterstützung für serielle Schnittstellen, zum Beispiel PuTTY. Um den von Windows(R) verwendeten COM-Port zu ermitteln, starten Sie den Geräte-Manager und erweitern Sie "Ports (COM & LPT)". Dort sehen Sie einen Namen wie "USB Serial Sevice (COM4)". Starten Sie das Terminalprogramm Ihrer Wahl, zum Beispiel PuTTY. Im Dialog von PuTTY setzen Sie den "Connection type" auf "Serial" und notieren im Feld "Serial line" den ermittelten COM-Namen. Danach klicken Sie auf "Open".

[[usb-device-mode-network]]
== Netzwerkkarten im USB-Gerätemodus

Virtuelle Netzwerkkarten werden durch die Vorlagen 1, 8 und 10 unterstützt. Beachten Sie, dass keine dieser Vorlagen mit Windows(R) funktioniert. Andere Host-Betriebssysteme arbeiten mit allen drei Vorlagen. Die Kernelmodule man:usb_template[4] und man:if_cdce[4] müssen geladen sein.

Stellen Sie sicher, dass die notwendigen Module geladen sind und die richtige Vorlage beim Booten gesetzt ist. Fügen Sie dazu folgende Zeilen in [.filename]#/boot/loader.conf# ein:

[.programlisting]
....
if_cdce_load="YES"
hw.usb.template=1
....

Um das Modul zu laden und die Vorlage ohne Neustart zu aktivieren, verwenden Sie:

[source,bash]
....
# kldload if_cdce
# sysctl hw.usb.template=1
....

[[usb-device-mode-storage]]
== Virtuelle USB-Speichergeräte

[NOTE]
====
man:cfumass[4] ist ein USB-Gerätetreiber, der seit FreeBSD 12.0 verfügbar ist.
====

Virtuelle Speichergeräte werden durch die Vorlagen 0 und 10 unterstützt. Die Kernelmodule man:usb_template[4] und man:cfumass[4] müssen geladen sein. man:cfumass[4] ist die Schnittstelle zum CTL-Subsystem, das auch für iSCSI- oder Fibre-Channel-Targets benutzt wird. Auf dem Host können Initiatioren von USB-Massenspeichern nur auf eine einzige LUN, LUN 0 zugreifen.

=== Konfiguration von USB-Massenspeicher Targets mit dem cfumass-Startskript

Der einfachste Weg, ein schreibgeschütztes USBSpeicherziel einzurichten, ist die Verwendung des [.filename]#cfumass# rc-Skripts. Kopieren Sie einfach die Dateien, die dem USB-Host präsentiert werden sollen, in das Verzeichnis [.filename]#/var/cfumass# und fügen Sie diese Zeile in [.filename]#/etc/rc.conf# ein:

[.programlisting]
....
cfumass_enable="YES"
....

Um das Ziel ohne Neustart zu konfigurieren, führen Sie diesen Befehl aus:

[source,bash]
....
# service cfumass start
....

Im Gegensatz zur seriellen und Netzwerkfunktionalität sollte die Vorlage in [.filename]#/boot/loader.conf# nicht auf 0 oder 10 gesetzt werden, da die LUN vor dem Setzen der Vorlage konfiguriert werden muss. Das [.filename]#cfumass# rc-Skript setzt beim Start automatisch die richtige Vorlage.

=== USB-Massenspeicher mit anderen Werkzeugen konfigurieren

Der Rest dieses Kapitels enthält eine detaillierte Beschreibung der Konfiguration ohne die Verwendung des [.filename]#cfumass# rc-Skripts. Dies ist beispielsweise notwendig, wenn man eine beschreibbare LUN zur Verfügung stellen will.

Im Gegensatz zu iSCSI ist es bei USB-Massenspeichern nicht zwingend erforderlich, dass der man:ctld[8] Daemon läuft. Es gibt zwei Möglichkeiten, das Target zu konfigurieren: man:ctladm[8] oder man:ctld[8]. Beide erfordern, dass das Kernelmodul [.filename]#cfumass.ko# geladen ist. Das Modul kann manuell geladen werden:

[source,bash]
....
# kldload cfumass
....

Wenn [.filename]#cfumass# nicht im Kernel integriert ist, kann [.filename]#/boot/loader.conf# angepasst werden, damit das Modul beim Booten geladen wird:

[.programlisting]
....
cfumass_load="YES"
....

Eine LUN kann ohne den man:ctld[8] Daemon erstellt werden:

[source,bash]
....
# ctladm create -b block -o file=/data/target0
....

Dies stellt den Inhalt des Abbilds von [.filename]#/data/target0# als LUN auf dem USB-Host dar. Die Datei muss vor der Ausführung des Befehls vorhanden sein. Um die LUN beim Systemstart zu konfigurieren, muss das Kommando in [.filename]#/etc/rc.local# eingetragen werden.

man:ctld[8] kann auch benutzt werden, um LUNs zu verwalten. Dazu erstellen Sie eine [.filename]#/etc/ctl.conf# und fügen eine Zeile in [.filename]#/etc/rc.conf# hinzu, um sicherzustellen, dass man:ctld[8] beim Booten automatisch gestartet wird. Danach kann der Daemon gestartet werden.

Es folgt ein Beispiel einer einfachen Konfiguration für [.filename]#/etc/ctl.conf#. Eine ausführliche Beschreibung der Optionen finden Sie in man:ctl.conf[5].

[.programlisting]
....
target naa.50015178f369f092 {
	lun 0 {
		path /data/target0
		size 4G
	}
}
....

Dieses Beispiel erstellt ein einzelnes Target mit einer einzigen LUN. `naa.50015178f369f092` ist eine Gerätekennung, die aus 32 zufälligen Hexadezimalziffern besteht. `path` definiert den absoluten Pfad zu einer Datei oder eines zvol, welches die LUN als Speicher nutzen kann. Diese Datei muss vor dem Start von man:ctld[8] existieren. Die zweite Zeile ist optional und definiert die Größe der LUN.

Damit der man:ctld[8] Daemon beim Booten gestartet wird, muss diese Zeile in [.filename]#/etc/rc.conf# hinzugefügt werden:

[.programlisting]
....
ctld_enable="YES"
....

Sie können man:ctld[8] mit diesem Befehl direkt starten:

[source,bash]
....
# service ctld start
....

Der man:ctld[8] Daemon liest beim Start [.filename]#/etc/ctl.conf#. Wenn diese Datei nach dem Start des Daemons bearbeitet wird, müssen die Änderungen neu geladen werden, damit sie sofort wirksam werden:

[source,bash]
....
# service ctld reload
....
