Difference between revisions of "USB Devices in Virtual Machines"
m |
|||
| Line 1: | Line 1: | ||
| − | + | == Introduction == | |
| − | = Introduction = | ||
There can be good reasons to access to USB hardware directly from a guest as it would be part of the VM itself, e.g.: | There can be good reasons to access to USB hardware directly from a guest as it would be part of the VM itself, e.g.: | ||
* Storage exclusively for the VM | * Storage exclusively for the VM | ||
| − | |||
* Separate NIC for the VM, but Direct I/O not avaiable | * Separate NIC for the VM, but Direct I/O not avaiable | ||
| − | |||
* Special device which needs a driver which exists only in the VM | * Special device which needs a driver which exists only in the VM | ||
The assignment of such devices can be predefined in the configuration file or "plugged" into the VM while it is running. | The assignment of such devices can be predefined in the configuration file or "plugged" into the VM while it is running. | ||
| − | = Simple Way: pass the USB device ID to the guest = | + | == Simple Way: pass the USB device ID to the guest == |
Assigning an Alcor memory stick connected to the host to VM 804. | Assigning an Alcor memory stick connected to the host to VM 804. | ||
| Line 30: | Line 27: | ||
Shutdown the VM (if running) and start it again. | Shutdown the VM (if running) and start it again. | ||
| − | = Alternate way: pass the USB port to the guest = | + | == Alternate way: pass the USB port to the guest == |
| − | == Example == | + | === Example === |
In order to demonstrate how devices, physically connected to the host can be identified it´s assumed the following 7 USB devices are currently connected: | In order to demonstrate how devices, physically connected to the host can be identified it´s assumed the following 7 USB devices are currently connected: | ||
| − | + | # External HD Toshiba USB 3.0 | |
| − | + | # memory stick Cruzer Blade USB 2.0 | |
| − | + | # memory stick SanDisk USB 2.0 | |
| − | + | # memory stick SanDisk USB 2.0 behind a USB hub | |
| − | + | # memory stick Alcor behind the same USB hub as above | |
| − | + | # Ethernet Network adapter USB 1.1 behind the same USB hub as above | |
| − | + | # External HD Western Digital USB 3.0 | |
| − | + | === Show Device Types === | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == Show Device Types == | ||
This is the simplest form and sufficient in most cases. | This is the simplest form and sufficient in most cases. | ||
| Line 77: | Line 68: | ||
Note that the "Device" number is just a number assigned automatically by the host, independent where the device is connected to. If the device is removed and plugged in again it gets a new number. | Note that the "Device" number is just a number assigned automatically by the host, independent where the device is connected to. If the device is removed and plugged in again it gets a new number. | ||
| − | == Show Device Map and Types == | + | === Show Device Map and Types === |
Sometimes it is necessary to specify where a device is physically connected. This information can be obtained by | Sometimes it is necessary to specify where a device is physically connected. This information can be obtained by | ||
| Line 88: | Line 79: | ||
in case of our example it is | in case of our example it is | ||
| − | |||
| − | |||
Bus 2, Addr 4, Port 1.8, Speed 480 Mb/s | Bus 2, Addr 4, Port 1.8, Speed 480 Mb/s | ||
| Line 112: | Line 101: | ||
* 12 MB/s = USB 1.1 | * 12 MB/s = USB 1.1 | ||
| − | |||
* 480 Mb/s = USB 2.0 | * 480 Mb/s = USB 2.0 | ||
| − | |||
* 5000 Mb/s = USB 3.0 | * 5000 Mb/s = USB 3.0 | ||
| − | |||
Just the map can be displayed by | Just the map can be displayed by | ||
| Line 124: | Line 110: | ||
but it´s sometimes not complete and not recommended. | but it´s sometimes not complete and not recommended. | ||
| − | == Complete Information == | + | === Complete Information === |
usb-devices | usb-devices | ||
| Line 130: | Line 116: | ||
which contains everything but i´s a little bit difficult to read - for the current subject it´s sufficient to use the qm monitor as described above. The only one thing is a running VM must exist when processing the command. | which contains everything but i´s a little bit difficult to read - for the current subject it´s sufficient to use the qm monitor as described above. The only one thing is a running VM must exist when processing the command. | ||
| − | = Assigning Devices to VMs = | + | == Assigning Devices to VMs == |
Note that only "real" devices can be assigned, i.e. assigning of USB hubs is not possible. | Note that only "real" devices can be assigned, i.e. assigning of USB hubs is not possible. | ||
| − | == In Configuration == | + | === In Configuration === |
| − | === General Remark === | + | ==== General Remark ==== |
Using the below mentioned "qm set" command has the same effect as writing directly into the conf file. Moreover a preconfigured usb configuration file /usr/share/qemu-server/pve-usb.cfg could be adapted. But in order to avoid confusion this article recommends to use only the "qm set" command. | Using the below mentioned "qm set" command has the same effect as writing directly into the conf file. Moreover a preconfigured usb configuration file /usr/share/qemu-server/pve-usb.cfg could be adapted. But in order to avoid confusion this article recommends to use only the "qm set" command. | ||
| − | === USB1.x, USB2.0 === | + | ==== USB1.x, USB2.0 ==== |
The syntax for assigning in configuration is (see also [https://pve.proxmox.com/wiki/Qm_manual man page for qm]) | The syntax for assigning in configuration is (see also [https://pve.proxmox.com/wiki/Qm_manual man page for qm]) | ||
| Line 159: | Line 145: | ||
When the usb devices have to be removed from configuration the conf file has to be changed. In our example remove in /etc/pve/qemu-server/804.conf the following two lines: | When the usb devices have to be removed from configuration the conf file has to be changed. In our example remove in /etc/pve/qemu-server/804.conf the following two lines: | ||
| − | |||
usb0: host=058f:6387 | usb0: host=058f:6387 | ||
usb1: host=host=2-1.2.2 | usb1: host=host=2-1.2.2 | ||
| − | === USB3.0 === | + | ==== USB3.0 ==== |
| − | ==== 1 Device ==== | + | ===== 1 Device ===== |
The external Toshiba drive should be assigned VM 804 and work with USB 3.0 protocol on a USB 3.0 port. | The external Toshiba drive should be assigned VM 804 and work with USB 3.0 protocol on a USB 3.0 port. | ||
| Line 178: | Line 163: | ||
args: -device nec-usb-xhci,id=xhci,addr=0x5 -device usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007 | args: -device nec-usb-xhci,id=xhci,addr=0x5 -device usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007 | ||
| − | ==== More Devices ==== | + | ===== More Devices ===== |
For one machine only one "-args" argument is possible. If already an "-args" advice was given giving another one overwrites the first. Moreover, the usb3 driver needs only to be defined once. In the following example 2 USB3 devices are assigned to the VM, the second one has the ID 1058:0820 | For one machine only one "-args" argument is possible. If already an "-args" advice was given giving another one overwrites the first. Moreover, the usb3 driver needs only to be defined once. In the following example 2 USB3 devices are assigned to the VM, the second one has the ID 1058:0820 | ||
| Line 185: | Line 170: | ||
-device usb-host,bus=xhci.0,vendorid=0x1058,productid=0x0820" | -device usb-host,bus=xhci.0,vendorid=0x1058,productid=0x0820" | ||
| − | == Assign Devices to an already Running VM == | + | === Assign Devices to an already Running VM === |
How to connect devices to a running machine without shutting it down is demonstrated by the examples from above. If device is assigned in that way the assignment is valid until the machine stops. The assignment is independent of the actual status of the device (whether it´s currently plugged in or not), i.e. it can be plugged in and out multiple times and will be always assigned to the VM; regardless if the "Productid" or "busaddress" method is used. | How to connect devices to a running machine without shutting it down is demonstrated by the examples from above. If device is assigned in that way the assignment is valid until the machine stops. The assignment is independent of the actual status of the device (whether it´s currently plugged in or not), i.e. it can be plugged in and out multiple times and will be always assigned to the VM; regardless if the "Productid" or "busaddress" method is used. | ||
| − | === USB1.x, USB2.0 === | + | ==== USB1.x, USB2.0 ==== |
qm monitor 804 | qm monitor 804 | ||
| Line 199: | Line 184: | ||
Note that the "usb_add" command offered in "qm monitor" is NOT FUNCTIONING for this case! | Note that the "usb_add" command offered in "qm monitor" is NOT FUNCTIONING for this case! | ||
| − | === USB3.0 === | + | ==== USB3.0 ==== |
qm monitor 804 | qm monitor 804 | ||
| Line 206: | Line 191: | ||
device_add usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007 | device_add usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007 | ||
| − | + | ==== Reassign to Host ==== | |
| − | === Reassign to Host === | ||
t.b.d. | t.b.d. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
[[Category: HOWTO]] | [[Category: HOWTO]] | ||
Revision as of 15:06, 27 October 2015
Introduction
There can be good reasons to access to USB hardware directly from a guest as it would be part of the VM itself, e.g.:
- Storage exclusively for the VM
- Separate NIC for the VM, but Direct I/O not avaiable
- Special device which needs a driver which exists only in the VM
The assignment of such devices can be predefined in the configuration file or "plugged" into the VM while it is running.
Simple Way: pass the USB device ID to the guest
Assigning an Alcor memory stick connected to the host to VM 804.
Figure out in the host the Device Type by
lsusb | grep Alcor
The result is
Bus 002 Device 013: ID 058f:6387 Alcor Micro Corp. Flash Drive
Assign it to the VM by
qm set 804 -usb0 host=058f:6387
Shutdown the VM (if running) and start it again.
Alternate way: pass the USB port to the guest
Example
In order to demonstrate how devices, physically connected to the host can be identified it´s assumed the following 7 USB devices are currently connected:
- External HD Toshiba USB 3.0
- memory stick Cruzer Blade USB 2.0
- memory stick SanDisk USB 2.0
- memory stick SanDisk USB 2.0 behind a USB hub
- memory stick Alcor behind the same USB hub as above
- Ethernet Network adapter USB 1.1 behind the same USB hub as above
- External HD Western Digital USB 3.0
Show Device Types
This is the simplest form and sufficient in most cases.
lsusb
The result is
Bus 002 Device 004: ID 0781:5567 SanDisk Corp. Cruzer Blade # <-------- (2) Bus 002 Device 008: ID 0fe6:9700 Kontron (Industrial Computer Source / ICS Advent) DM9601 Fast Ethernet Adapter # <-------- (6) Bus 002 Device 007: ID 0781:556b SanDisk Corp. # <-------- (4) Bus 002 Device 013: ID 058f:6387 Alcor Micro Corp. Flash Drive # <-------- (5) Bus 002 Device 005: ID 05e3:0605 Genesys Logic, Inc. USB 2.0 Hub [ednet] Bus 002 Device 010: ID 0781:556b SanDisk Corp. # <-------- (3) Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 004 Device 003: ID 1058:0820 Western Digital Technologies, Inc. # <-------- (7) Bus 004 Device 002: ID 0480:a007 Toshiba America Info. Systems, Inc. External Disk USB 3.0 # <-------- (1) Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
The numbers on the far right refer to the previously defined example. The other entries are the USB hubs of the system.
Note that the "Device" number is just a number assigned automatically by the host, independent where the device is connected to. If the device is removed and plugged in again it gets a new number.
Show Device Map and Types
Sometimes it is necessary to specify where a device is physically connected. This information can be obtained by
qm monitor 804
where "804" is the ID of a running VM - regardless which VM is specified, the following command inside of the monitor reports always the same
info usbhost
in case of our example it is
Bus 2, Addr 4, Port 1.8, Speed 480 Mb/s Class 00: USB device 0781:5567, Cruzer Blade # <---- (2) Bus 2, Addr 8, Port 1.2.3, Speed 12 Mb/s Class 00: USB device 0fe6:9700, USB 2.0 10/100M Ethernet Adaptor # <---- (6) Bus 2, Addr 7, Port 1.2.2, Speed 480 Mb/s Class 00: USB device 0781:556b, Cruzer Edge # <---- (4) Bus 2, Addr 13, Port 1.2.1, Speed 480 Mb/s Class 00: USB device 058f:6387, Mass Storage # <---- (5) Bus 2, Addr 10, Port 1.1, Speed 480 Mb/s Class 00: USB device 0781:556b, Cruzer Edge # <---- (3) Bus 4, Addr 3, Port 1, Speed 5000 Mb/s Class 00: USB device 1058:0820, My Passport 0820 # <---- (7) Bus 4, Addr 2, Port 1, Speed 5000 Mb/s Class 00: USB device 0480:a007, External USB 3.0 # <---- (1)
The devices behind the external hub have port addresses 1.2.x
This form shows also the currently used USB protocol (btw: even the device (6) calls itself "USB 2.0 10/100M Ethernet Adaptor" it works only as USB 1.1 device)
- 12 MB/s = USB 1.1
- 480 Mb/s = USB 2.0
- 5000 Mb/s = USB 3.0
Just the map can be displayed by
lsusb -t
but it´s sometimes not complete and not recommended.
Complete Information
usb-devices
which contains everything but i´s a little bit difficult to read - for the current subject it´s sufficient to use the qm monitor as described above. The only one thing is a running VM must exist when processing the command.
Assigning Devices to VMs
Note that only "real" devices can be assigned, i.e. assigning of USB hubs is not possible.
In Configuration
General Remark
Using the below mentioned "qm set" command has the same effect as writing directly into the conf file. Moreover a preconfigured usb configuration file /usr/share/qemu-server/pve-usb.cfg could be adapted. But in order to avoid confusion this article recommends to use only the "qm set" command.
USB1.x, USB2.0
The syntax for assigning in configuration is (see also man page for qm)
qm set <VM-ID> -usb[<n>] host={ <bus>-<port>(.<port>)* | <vendor-id>:<product-id> }
According to the above example let´s say the Alcor stick and the Cruzer Edge connected to the external hub (which is device (4) from the example) should be assigned to VM 804:
For the Alcor stick (as already shown):
qm set 804 -usb0 host=058f:6387
For the Cruzer Edge this form will not be sufficient - there are two devices from the same type. Therefore the form specifying bus and port is used:
qm set 804 -usb1 host=2-1.2.2
More details about ports can be found here - but note as already mentioned the "lsusb -t" call is not reliable. Use "qm monitor" and "info usbhost" instead!
When the usb devices have to be removed from configuration the conf file has to be changed. In our example remove in /etc/pve/qemu-server/804.conf the following two lines:
usb0: host=058f:6387 usb1: host=host=2-1.2.2
USB3.0
1 Device
The external Toshiba drive should be assigned VM 804 and work with USB 3.0 protocol on a USB 3.0 port.
qm set 804 -args "-device nec-usb-xhci,id=xhci,addr=0x5 -device usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007"
Note that "addr=0x5" works only if there is no other device assigned to this address. If a failure occurs because of double use of this address choose another one.
When the usb device has to be removed from configuration the conf file has to be changed. In our example remove in /etc/pve/qemu-server/804.conf the following line:
args: -device nec-usb-xhci,id=xhci,addr=0x5 -device usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007
More Devices
For one machine only one "-args" argument is possible. If already an "-args" advice was given giving another one overwrites the first. Moreover, the usb3 driver needs only to be defined once. In the following example 2 USB3 devices are assigned to the VM, the second one has the ID 1058:0820
qm set 804 -args "-device nec-usb-xhci,id=xhci,addr=0x5 -device usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007 \ -device usb-host,bus=xhci.0,vendorid=0x1058,productid=0x0820"
Assign Devices to an already Running VM
How to connect devices to a running machine without shutting it down is demonstrated by the examples from above. If device is assigned in that way the assignment is valid until the machine stops. The assignment is independent of the actual status of the device (whether it´s currently plugged in or not), i.e. it can be plugged in and out multiple times and will be always assigned to the VM; regardless if the "Productid" or "busaddress" method is used.
USB1.x, USB2.0
qm monitor 804
device_add usb-host,vendorid=0x058f,productid=0x6387 device_add usb-host,hostbus=2,hostport=1.2.2
Note that the "usb_add" command offered in "qm monitor" is NOT FUNCTIONING for this case!
USB3.0
qm monitor 804
device_add nec-usb-xhci,id=xhci,addr=0x5 device_add usb-host,bus=xhci.0,vendorid=0x0480,productid=0xa007
Reassign to Host
t.b.d.