From dc0819594baa7b2e4ecb28672495e49ba975cb04 Mon Sep 17 00:00:00 2001 From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com> Date: Thu, 1 Sep 2022 07:32:52 +0200 Subject: [PATCH 1/3] Use sentence case instead of title case As required by the style guide --- user/how-to-guides/how-to-use-usb-devices.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index e515231f..c3db0601 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -28,9 +28,9 @@ Examples of valid cases for USB-passthrough: (If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/). But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).) -## Attaching And Detaching a USB Device +## Attaching and detaching a USB device -### With Qubes Device Manager +### With Qubes device manager Click the device-manager-icon: ![device manager icon](/attachment/doc/media-removable.png) A list of available devices appears. @@ -48,7 +48,7 @@ Hover on the attached device to display a list of running VMs. The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it. Click that and your device will be detached. -### With The Command Line Tool +### With the command line tool In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. @@ -87,14 +87,14 @@ sys-usb:2-5 058f:3822 058f_USB_2.0_Camera sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse ``` -## Maintenance And Customisation +## Maintenance and customisation -### Creating And Using a USB qube +### Creating and using a USB qube If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/). -### Installation Of `qubes-usb-proxy` +### Installation of `qubes-usb-proxy` To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to. This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. @@ -111,13 +111,13 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you sudo apt-get install qubes-usb-proxy ``` -### Using USB Keyboards And Other Input Devices +### Using USB keyboards and other input devices **Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing! Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/). -### Finding The Right USB Controller +### Finding the right USB controller Some USB devices are not compatible with the USB pass-through method Qubes employs. In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. From 2b24640962d12880aa91c93a478d0b71d4553444 Mon Sep 17 00:00:00 2001 From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com> Date: Thu, 1 Sep 2022 08:00:33 +0200 Subject: [PATCH 2/3] Add instructions for using Qube Manager Using the Qube Manager to determine USB controller and address --- user/how-to-guides/how-to-use-usb-devices.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index c3db0601..f845f89e 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -123,6 +123,10 @@ Some USB devices are not compatible with the USB pass-through method Qubes emplo In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it. +You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address. + +#### Method 1: Using lsusb and readlink + If you have multiple USB controllers, you must first figure out which PCI device is the right controller. First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube): @@ -155,6 +159,8 @@ This should output something like: ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ``` +If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. + Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM. For example, On R 4.0 the command would look something like @@ -162,3 +168,17 @@ For example, On R 4.0 the command would look something like ``` qvm-pci attach --persistent personal dom0:00_1a.0 ``` + +#### Method 2: Using the Qube Manager + +Open the Qube Manager, then right click on one of the VMs and open the settings. Go to the tab "Devices". + +Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller". + +They should look something like: `01:00.0 USB controller: Name of manufacturer` + +The first part is the BDF address, in this example: `01:00.0` + +If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation" while the added controller shows another name of manufacturer. + +Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller. From 7870666de371d924021449f8886e1e99d4b110b2 Mon Sep 17 00:00:00 2001 From: unman Date: Wed, 30 Apr 2025 11:42:31 +0000 Subject: [PATCH 3/3] Clarified that main method relates to finding controller for attached device. Moved QubeManager method to separate section --- user/how-to-guides/how-to-use-usb-devices.md | 45 ++++++++++---------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index f845f89e..58d704ce 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -13,7 +13,7 @@ title: How to use USB devices If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/how-to-use-block-storage-devices/) page. -**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/). +**Note:** Attaching USB devices to qubes requires a [USB qube](/doc/usb-qubes/). **Important security warning:** USB passthrough comes with many security implications. Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**. @@ -36,7 +36,7 @@ Click the device-manager-icon: ![device manager icon](/attachment/doc/media-remo A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon](/attachment/doc/generic-usb.png) -Hover on one device to display a list of VMs you may attach it to. +Hover on one device to display a list of qubes you may attach it to. Click one of those. The USB device will be attached to it. @@ -44,7 +44,7 @@ You're done. After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget. You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**. -Hover on the attached device to display a list of running VMs. +Hover on the attached device to display a list of running qubes The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it. Click that and your device will be detached. @@ -74,7 +74,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse ``` Now, you can use your USB device (camera in this case) in the `work` qube. -If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy). +If you see the error `ERROR: qubes-usb-proxy not installed in the qube` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy). When you finish, detach the device. @@ -100,7 +100,7 @@ To use this feature, the `qubes-usb-proxy` package needs to be installed in the This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. Under normal conditions, `qubes-usb-proxy` should already be installed and good to go. -If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to. +If you receive this error: `ERROR: qubes-usb-proxy not installed in the qube`, you can install the `qubes-usb-proxy` with the package manager in the qube you want to attach the USB device to. - Fedora: ``` @@ -121,12 +121,9 @@ Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/). Some USB devices are not compatible with the USB pass-through method Qubes employs. In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. -However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it. - -You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address. - -#### Method 1: Using lsusb and readlink +However, with this approach you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it. +You can find your controller and its BDF address using the method described below, using the command-line tools `lsusb` and `readlink`. If you have multiple USB controllers, you must first figure out which PCI device is the right controller. First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube): @@ -145,7 +142,7 @@ Bus 003 Device 003: ID 413c:818d Dell Computer Corp. (In this case, the device isn't fully identified) The device is connected to USB bus \#3. -Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM. +Check which other devices are connected to the same bus, since *all* of them will be attached to the target qube. To find the right controller, follow the usb bus: @@ -158,27 +155,29 @@ This should output something like: ``` ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ``` - -If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. - -Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM. - -For example, On R 4.0 the command would look something like - +Now you see the path: the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the target qube, like this: ``` qvm-pci attach --persistent personal dom0:00_1a.0 ``` -#### Method 2: Using the Qube Manager +It is possible that on some system configurations the readlink method produces output which is different from the example above, +For example, you might see output like this: +``` +../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1 +``` +In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0 -Open the Qube Manager, then right click on one of the VMs and open the settings. Go to the tab "Devices". +If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. +#### Identifying controllers using the Qube Manager +Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses. + +Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices". Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller". - They should look something like: `01:00.0 USB controller: Name of manufacturer` The first part is the BDF address, in this example: `01:00.0` -If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation" while the added controller shows another name of manufacturer. +If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation", while the added controller shows another manufacturer's name. -Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller. +Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.